ClickHouse MCP has 5 tools with basic naming and descriptions, but significant gaps in schema completeness and parameter documentation. Tool names follow verb_noun convention (list_*, run_*), which is good. However, descriptions are minimal (10-50 chars), parameter descriptions are sparse or missing, and output schemas are not documented. The server lacks error handling guidance, input validation documentation, and security considerations around SQL injection. No tool annotations (readOnlyHint/destructiveHint) despite clear risk differentiation between read and write operations.

• Document output schemas for all tools. E.g., list_databases should specify: returns {databases: [{name: string, tables_count: int}], total: int}. This enables LLMs to chain tools correctly.
• Expand parameter descriptions. run_query: 'SQL SELECT query (no INSERT/UPDATE/DELETE). Max 10000 chars. Use parameterized queries to prevent injection.' run_statement: 'Non-SELECT SQL (INSERT, UPDATE, DELETE, CREATE, ALTER, DROP). Requires explicit confirmation for destructive ops.'
• Add error recovery guidance. E.g., 'If query fails with syntax error, check ClickHouse docs. If permission denied, verify user role. If timeout, reduce result set or add LIMIT clause.'
• Implement input validation and document it. Reject non-SELECT in run_query, validate SQL syntax early, return actionable errors like 'Invalid SQL: expected SELECT, got INSERT. Use run_statement for INSERT.'
• Add tool annotations via go-sdk. Mark read-only tools with readOnlyHint=true; mark run_statement with destructiveHint=true. This signals to agents which tools are safe to retry.

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

• Relies on Dynamic Client Registration (deprecated) - use Client ID Metadata Documents (CIMD)