The nlp2sql MCP server provides 5 well-named, domain-focused tools for NLP-to-SQL conversion and database interaction. Tool names follow the verb_noun pattern (ask_database, explore_schema, run_sql, list_databases, explain_sql) and are unambiguous. All tools have descriptions exceeding 20 characters. However, several critical gaps reduce the score: (1) input schemas are visible for all 5 tools in the source specification, but the actual JSON Schema type definitions are not shown in the provided code excerpt, only parameter names and descriptions are visible in the YAML-like format. This prevents verification of full schema completeness. (2) Parameter descriptions are present but often generic and lack actionable constraints (e.g., 'database' param describes it as 'Database alias or connection URL' but does not list valid aliases or format restrictions). (3) No output schema is documented anywhere in the provided source. (4) Error handling is not evident in the code excerpt, no recovery guidance, categorization, or actionable error messages are shown. (5) Security patterns are undocumented (no scope declarations, audit trails, or permission gates are visible). The tools themselves are well-composed and avoid multi-responsibility bundling. All 5 tools are READ_ONLY, which is appropriate and well-marked.

• Add explicit output schema documentation for each tool. Example: 'ask_database returns {sql: string, results?: [{column1: string, column2: ...}], error?: string, execution_time_ms?: number}'.
• Convert the 'database' parameter from a free-form description to an enum constraint or regex pattern. Document valid aliases explicitly in schema, not just in prose: {"type": "string", "enum": ["default", "demo", "local", "test", "prod"], "description": "..."} or allow arbitrary URLs with a regex format.
• Add error response structure and categorization. Define how errors are returned (e.g., {error: string, code: 'not_found'|'invalid_query'|'timeout', retryable: boolean, suggestion?: string}).
• Document scope requirements. Add a 'scopes' field to each tool definition (e.g., 'read:database', 'execute:read_query') to clarify what permissions are required.
• For explore_schema, add pagination parameters (limit, offset) and response metadata (total_count, has_more) to handle large schemas.
• Add input validation guidance for run_sql: document the regex/pattern for valid SQL (SELECT only, no DML), and explain how the server rejects invalid queries.
• Add an idempotent hint annotation to tools that are read-only (ask_database, explore_schema, run_sql, explain_sql) if supported by MCP, this clarifies to agents that these are safe to retry.
• Consider adding a separate 'test_connection' tool to verify database connectivity before attempting queries, improving error diagnosis.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry