mcp-multi-db provides four read-only database tools with consistent naming, clear descriptions, and Zod-based input schemas. All tools start with action verbs (list_, describe_, run_) and have descriptions 60-90 characters, within best-practice range (10-1024 chars). However, the server lacks output schema documentation, error handling guidance, and actionable recovery instructions. Tool descriptions state WHAT but not WHEN or WHY to use them. Parameter descriptions are terse but present. No tool uses idempotent hints, readonly annotations, or destructive hints despite being read-only. Return types are JSON text blobs with no field-level documentation.

• Add output schema documentation for each tool. E.g., list_databases returns [{id: string, type: string, label: string, description: string}]. Describe field meanings and why they matter for downstream selection.
• Enhance descriptions with WHEN/WHY guidance: 'Call this first to discover which database_id to use for list_tables, describe_table, or run_query.' This primes the LLM to build correct multi-step plans.
• Add readOnlyHint: true annotation to all four tools. This enables MCP hosts to infer that results can be safely cached and calls can be batched without side-effect concerns.
• Document SQL validation for run_query: 'Supports SELECT, WITH (CTEs), and EXPLAIN queries. INSERT, UPDATE, DELETE, and DDL are rejected with an error message listing allowed statement types.'
• Add error recovery guidance: E.g., 'If database_id is invalid, call list_databases() to see available connections.' This teaches the LLM how to self-correct.
• Clarify pagination behavior for run_query: 'If the query returns more than limit rows, only the first limit rows are returned. Use a LIMIT clause in your SQL to control which rows are fetched.'
• Consider adding a query_info or describe_query tool to validate/plan SQL without executing it, reducing trial-and-error loops for complex queries.
• Document the database_id discovery flow in list_databases output: include a reference field or note that the id is the key for downstream tools.