Flashframe exposes 4 ClickHouse/chDB query tools with minimal documentation. Tool names lack clear action verbs (run_query, run_chdb_select_query are vague). Descriptions are present but generic (10-50 chars, below the 50-200 char LLM-optimized baseline). Input schemas visible but sparse: run_query and run_chdb_select_query accept only a 'query' string with no validation, enums, or constraints. list_databases has empty input {}. list_tables accepts 'database' string but no format guidance. No output schemas documented. No error handling guidance. No parameter descriptions beyond the query string itself. Tools appear to be proof-of-concept spikes (files in spikes/ directory) rather than production-grade definitions.

• Rename tools with clear action verbs: 'execute_clickhouse_query', 'execute_chdb_select', 'list_clickhouse_databases', 'list_clickhouse_tables'. This helps LLMs parse intent from the name alone.
• Expand descriptions to 80-150 chars. Example: 'Execute a SQL query against ClickHouse. Returns results as JSON rows. Use for analytics, aggregations, and data retrieval. Supports SELECT, INSERT, UPDATE, DELETE. Errors: connection timeout, syntax error, permission denied.'
• Document output schemas. Specify that results are returned as an array of objects with typed fields, include pagination info (total_rows, has_more), and document error response format (error_code, error_message, suggestion).
• Add input validation: constrain 'query' length (e.g., max 10KB), document SQL dialect (ClickHouse vs. chDB), and provide examples of valid queries in parameter descriptions.
• Add error recovery guidance. Example: 'If query fails with syntax error, check ClickHouse documentation. If connection times out, retry after 5 seconds. If permission denied, verify user role.'