BoxOffice Brain defines 2 tools with clear, domain-specific purposes and solid descriptions (194 - 250 chars, within baseline 34 - 392). Both tools have input schemas with type definitions and parameter descriptions. However, output schemas are documented only in prose (return dict structure described in docstrings), not as formal JSON Schema. Error handling is present but generic, status codes (ok|rejected|suppressed|error) lack recovery guidance. Tool naming is verb-noun compliant (run_*, describe_*). No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite both being read-only. Parameter descriptions are adequate but could specify constraints more formally (e.g., SQL statement length, allowed table patterns). The grounding trace structure is well-designed for auditability but not schema-documented for LLM consumption.

• Add formal JSON Schema definitions for output objects. Document the grounding trace schema (sql: string, rows_read: int, bytes_read: int, elapsed_ms: int, source: enum[offline_snapshot|clickhouse_http|mcp_clickhouse], guardrail?: string, reason?: string) and the tables schema returned by describe_tables.
• Enhance error messages with recovery guidance. E.g., 'status: rejected, reason: "Query references table cinema.unknown, not in allowed set. Call describe_tables() to see available tables."'
• Add tool annotations in the MCP tool registration: set readOnlyHint=true for both tools to signal they are safe for speculative execution.
• Formalize parameter constraints. For 'sql', add a description: 'A single SELECT or WITH statement (max 10,000 chars). No INSERT, UPDATE, DELETE, CREATE, ALTER, or DROP. No table functions (url, s3, etc.) or SETTINGS clauses.' For 'note', specify max length (e.g., 200 chars).
• Document the status enum values with recovery paths: 'ok' (rows are valid), 'rejected' (guardrail blocked; see reason), 'suppressed' (rate limit or budget exhausted; retry after delay), 'error' (server error; retry or contact support).