The server provides 8 well-scoped tools for Databricks SQL access with consistent security controls. Tool naming follows verb_noun conventions (list_*, describe_*, query). All tools have non-empty descriptions (range 52 - 178 chars, well within the 10 - 1024 baseline). Input schemas are present and typed for all tools. However, output schemas are NOT documented, callers cannot see what fields to expect from responses. Error handling exists but lacks LLM-actionable recovery guidance. No tool annotations (readOnlyHint/destructiveHint) despite the framework supporting them. The query tool has strong input validation (blocklist regex, prefix enforcement) but this is implementation detail, not exposed to the LLM in descriptions.

• Add output schema documentation to all tools. Document the structure of responses: e.g., for query() return {'columns': List[str], 'rows': List[List[Any]], 'row_count': int}. Use JSDoc or explicit schema comments.
• Enhance error messages with actionable recovery hints for LLMs. E.g., 'Blocked: query contains a non-read-only keyword (INSERT, UPDATE, DELETE, etc.). Only SELECT, WITH, SHOW, DESCRIBE, DESC, EXPLAIN are allowed.' Or provide a suggested correction.
• Add tool annotations via FastMCP's @mcp.tool(readOnlyHint=True) decorator to all read-only tools. This helps LLMs avoid planning destructive chains.
• Expand parameter descriptions with explicit constraints. For 'sql', list allowed keywords. For 'catalog_or_db', state format rules. For 'max_rows', document the clamping range (1 - HARD_MAX_ROWS).
• Implement pagination for list_schemas and list_tables. Add optional limit (default 50, max 500) and offset parameters. Return total_count and has_more boolean to enable agent-driven pagination.
• Create a separate 'suggest_schemas' or 'find_schemas' tool that fuzzy-searches catalog/database names. This addresses the use case 'find all schemas matching pattern xyz' without loading everything into memory.
• Document that all tools are READ_ONLY and stateless. Add a security note to the server description: 'All SQL queries are validated against a prefix allowlist and keyword blocklist. No INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, or GRANT operations are permitted.'
• Add a 'explain_query' tool that parses a query and returns the estimated plan or checks if it would pass read-only validation, helping agents verify queries before execution.