Single tool 'query' has a clear verb-noun name and proper JSON Schema with typed parameters. Description is adequate (58 chars) but minimal, lacks context on when to use it, prerequisites, or output structure. Schema includes required fields and type constraints, but output schema is undocumented. No parameter descriptions visible in the schema definition. Tool annotations are present (read_only_hint=True) but not declared in the tool definition code shown. Error handling is basic, no recovery guidance or actionable error messages documented.

• Add parameter descriptions to the schema: 'sql' should explain 'SQL query to execute against materialized tool results (DuckDB syntax)' and 'max_rows' should clarify 'Maximum number of rows to return (default: 100, max: 10000)'.
• Document the output schema in the tool description or as a separate response_schema field. Specify that responses include 'rows' (array of objects), 'columns' (array of column names), 'row_count' (integer), and 'query_time_ms' (integer).
• Expand tool description to 100-150 characters: 'Execute SQL queries against a DuckDB scratch database populated with materialized results from upstream tools. Use this to aggregate, filter, or join tool outputs. Requires prior tool calls to populate the database.'
• Implement error classification: return structured errors with 'error_type' (syntax_error, table_not_found, timeout, permission_denied) and 'recovery_hint' (e.g., 'Table not found. Available tables: [list]. Did you mean one of these?').
• Add a 'format' parameter (optional, enum: json|csv|markdown) to let agents choose output format, improving composability with downstream tools.

Inferred effective spec: 2026-07-28+.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry