Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The server provides 10 tools with complete JSON Schema definitions and descriptions for all parameters. However, several definition quality issues prevent a higher score: (1) Most tool descriptions are extremely brief (15-45 characters), below the 50-200 character baseline for LLM optimization. For example, 'Disconnect from current database' (34 chars) lacks context about state management or prerequisites. (2) Several tools have vague descriptions that don't explain WHEN to use them vs similar tools. 'Analyze database schema and structure' doesn't distinguish it from 'Get detailed database information'. (3) Output schemas are completely undocumented, we have no specification of what these tools return, forcing LLMs to infer structure. (4) Error handling descriptions are absent, no guidance on recovery paths. (5) Tool naming mostly follows verb_noun convention (good), but 'natural_language_to_sql' is awkwardly long for a straightforward operation. (6) The server accepts sensitive credentials (username, password) as tool parameters for connect_database, violating the secret-injection pattern, these should use environment variables or server-side vaults.
Tools (10)
analyze_schemaread onlyauthsource verified60/100
Analyze database schema and structure
connect_databasewritesource verified57/100
Connect to a database (SQLite, PostgreSQL, or MySQL)
Output schemas completely undocumented across all 10 tools. LLMs have no formal specification of what each tool returns, forcing them to infer field names and types. This causes hallucinated downstream tool calls when chaining tools.
Credentials (username, password) exposed as plaintext tool parameters in connect_database. This violates secret-injection pattern, secrets in tool parameters are logged in traces and prompt history, risking exposure in agent logs and client-side caches.
Tool descriptions are extremely brief (20-93 characters, averaging 42 chars). Baseline for A-grade tools is 50-200 chars. Most descriptions lack WHEN to use the tool, consequences (read-only vs destructive), and recovery guidance. Descriptions should prompt-engineer the LLM's reasoning.
Recommendations
Document complete output schemas for all 10 tools. For each tool, specify the JSON structure, field names, types, and what data each field contains. Example: execute_sql_query should return { rows: [{ col_name: string, col_name: any, ... }], row_count: integer, execution_time_ms: integer }. This enables LLMs to chain tools without hallucinating field names.
Remove username and password parameters from connect_database. Instead, accept a 'connection_string' parameter or 'environment_config_key' that references server-side environment variables (NLSQL_DB_USER, NLSQL_DB_PASS). Document in the tool description: 'Credentials are loaded from server environment variables for security.'
Expand tool descriptions to 80-150 characters. Include: (1) What the tool does (2) When to use it instead of similar tools (3) Whether it reads or writes (4) What it returns. Example for analyze_schema: 'Analyzes and caches the database schema (table names, column types, constraints). Call once before natural_language_to_sql for better query generation. Use force_refresh=true to detect recent schema changes. Returns schema_hash for change detection.'
Rename analyze_schema and get_database_info to reduce ambiguity. Suggest: 'analyze_schema' → 'cache_schema' (emphasizes caching for LLM query optimization), 'get_database_info' → 'describe_tables' (explicitly returns table and column metadata). Update descriptions to clarify: cache_schema is a lightweight lookup service; describe_tables returns full metadata.
Add explicit risk markers to tool descriptions. For execute_sql_query and disconnect_database, prepend: '[WRITE OPERATION] This tool modifies database state and may execute DELETE or DROP statements. Irreversible if not wrapped in a transaction.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Tools analyze_schema and get_database_info have similar names and overlapping descriptions ('schema and structure' vs 'tables, columns, and relationships'). LLMs cannot reliably distinguish when to call one vs the other without clearer differentiation.
Destructive operations (execute_sql_query, disconnect_database) have descriptions that do not explicitly state they are WRITE operations with irreversible consequences. Pattern:command-tool requires this declaration so LLMs know which calls are safe to retry.
natural_language_to_sql tool name is awkwardly long (24 characters vs. production baseline average 18 chars). Shorter names like 'translate_to_sql' or 'sql_from_text' would be more idiomatic.
No error handling guidance in any tool descriptions. Pattern:recovery-guide requires error responses tell the LLM what to do next, but current descriptions give no hints about expected errors or recovery paths.
Tool descriptions lack dependency hints. E.g., 'natural_language_to_sql' doesn't clarify whether it requires a prior connect_database call, or if analyze_schema should be called first for better SQL generation.
natural_language_to_sqlexecute_sql_query
Add dependency hints to descriptions. For natural_language_to_sql, append: 'Tip: Call analyze_schema or get_database_info first to ensure the LLM model has the latest schema. Results improve when schema context is fresh.'
Add error handling guidance to each tool description. Example for execute_sql_query: 'On syntax error, the LLM can call validate_sql_query to diagnose the issue. On permission error, check get_connection_status to verify the connected user has required privileges.'
Add examples of valid input ranges to parameter descriptions. E.g., for get_table_sample, append to limit description: 'Recommended: 5-20 for LLM summary, 50+ for detailed analysis. Capped at 100 to prevent large result sets from exhausting context.'
Consider adding a tool for transaction management: 'begin_transaction', 'commit_transaction', 'rollback_transaction'. This lets LLMs wrap multi-step SQL executions in ACID guarantees, reducing the risk of partial failures.
Add a 'get_execution_logs' or 'get_query_history' tool so LLMs can review past executed queries and results, aiding in debugging and learning from previous interactions.