BudgetKey presents three well-structured data query tools with comprehensive descriptions and clear usage patterns. All three tools have proper input schemas with type definitions and descriptions. Descriptions are detailed and actionable (200-500 chars), exceeding baseline minimums and providing explicit prerequisites and multi-step workflows. Tool naming follows verb_noun conventions (DatasetInfo, DatasetFullTextSearch, DatasetDBQuery). However, output schemas are not formally documented in the visible code, while the code fetches data from an external API, there is no explicit JSON Schema or field listing for responses returned to the LLM. Error handling is minimal: tools catch exceptions and return a basic {error: str(e)} without recovery guidance or categorization. The tools lack explicit per-parameter constraints (enums, min/max bounds) in the schema definitions, relying instead on free-text parameter descriptions to convey allowed values. Tool composition is sound, each tool has a single responsibility, and the workflow instructions guide proper sequencing.

• Document output schemas for each tool. Add a 'Returns' section to each tool docstring with example JSON structure, field types, and descriptions. Example: 'Returns {columns: [{name: str, type: str, description: str}], schema: {tables: [...]}}'. This allows LLMs to plan subsequent calls and extract required fields.
• Replace generic error handling with structured, actionable errors. Categorize exceptions by type (API error, invalid dataset, network timeout, etc.) and return guided recovery messages. Example: 'Dataset "invalid_id" not found. Available: budget_items_data, contracts_data, entities_data. Did you mean one of these?'
• Add enum constraints to the 'dataset' parameter in all three tools. Replace free-text description with a JSON Schema enum listing all 10 valid dataset IDs. This prevents hallucinated dataset names and makes the tool self-documenting.
• Add min/max constraints to the 'page_size' parameter: minimum 1, maximum 1000 (or appropriate API limit). Include in both JSON Schema and description.
• Formalize response field mappings. Document that DatasetFullTextSearch returns result records with 'entity_id', 'code', etc., which can be directly passed to DatasetDBQuery's WHERE clause. This closes the composition chain and prevents LLM guessing.
• Add rate-limit handling. If the external API returns 429 Too Many Requests, return a retryable error with backoff guidance rather than a generic exception.
• Consider adding a 'dry_run' or 'explain_query' mode to DatasetDBQuery to let users preview what a query will return before execution, following the confirmation-request pattern.

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

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