Server exposes 6 tools with basic schemas and descriptions. All tools have input schemas with type definitions and descriptions present. However, descriptions are generic and lack LLM-optimized guidance on WHEN to use each tool vs alternatives. Parameter descriptions are minimal (e.g., 'Sheet tab name' lacks format/constraint details). No output schemas documented. Error handling returns raw exception text rather than actionable recovery guidance. Tools lack annotations (readOnlyHint/destructiveHint) despite clear risk profiles. Naming is verb-forward (execute_, list_, get_, read_, write_, flag_) but descriptions don't disambiguate overlapping tools (read_sheet vs write_metric both operate on Sheets). No pagination support despite list_tables potentially returning many results.

• Add output schemas to all tools. Document execute_sql returns {rows: [{col1: value, ...}], row_count: int, truncated: bool}. Document list_tables returns {tables: [string], total: int}. This enables LLM to plan chained calls.
• Replace raw exception text with actionable error messages. E.g., 'Invalid table name: got "clean_events_typo", available tables: clean_events, raw_events, audit_log. Call list_tables() to see all tables.' This guides LLM self-correction.
• Add tool annotations: readOnlyHint=true for execute_sql, list_tables, get_table_schema, read_sheet; destructiveHint=true for write_metric, flag_suspicious_user. This signals to LLM which tools are safe to retry.
• Convert parameter examples to formal constraints. For 'tab' parameter, use enum: ["metrics", "alerts"] instead of 'e.g. metrics, alerts'. For 'risk_level', enum is already present, apply same pattern to 'tab'.
• Add pagination to list_tables: accept optional limit (default 50, max 500) and offset parameters. Return {tables: [...], total: int, has_more: bool}. This prevents context window overflow for large datasets.