Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The server provides 7 AWS Athena tools with reasonable parameter schemas and basic descriptions. Parameter descriptions exist but are minimal. Output schemas are not documented, only raw JSON responses via json.dumps(). Error handling returns generic AWS errors without recovery guidance. Tools follow verb_noun naming convention (list_, get_, start_), which is good, but descriptions fail to explain WHEN to use each tool or WHAT to expect from it. Schema quality is moderate, parameters are typed but lack constraints (enums, ranges, formats). Overall, this is a functional but below-average implementation that would not pass production code review.
Examples: 'List all Athena work groups' (28 chars but minimal context), 'List databases in a data catalog' (33 chars, no guidance on ordering or pagination). Descriptions lack actionable guidance for LLM tool selection.
Output schema is not documented. Tools return raw json.dumps() of boto3 responses without specifying what fields are present, which are IDs for chaining, or how to handle pagination tokens. LLMs cannot plan downstream calls without seeing the response structure.
Expand tool descriptions to 50 - 200 characters, following the pattern: [ACTION] [WHAT] [WHEN] [CONTEXT]. Example: 'List all Athena work groups in the current region. Use this to discover available work groups before executing queries. Returns group names and IDs. Supports pagination.'
Document the output schema for every tool. Specify which fields are returned, which are IDs suitable for chaining to other tools (e.g., WorkGroupName for input to start_query_execution), and pagination structure (NextToken format, total count).
Add actionable error recovery guidance. Replace generic 'AWS Error: ...' with specific hints: 'Catalog "AwsDataCatalog" not found. Try list_databases() to discover available catalogs.' or 'Query still running. Check get_query_execution() again in 2 seconds.'
Expand parameter descriptions to 20 - 50 characters minimum. Specify format, valid range, and dependency hints. Example: 'max_results: Integer 1 - 100. Defaults to 10. Limits the number of items per page; use next_token to fetch subsequent pages.'
Correct the 'expression' parameter in list_tables to match AWS behavior. Rename to 'filter_pattern' and document: 'Athena filter expression (not regex) to match table names. Example: .*_prod to match production tables.'
Add 'output_location' validation and required-ness documentation in start_query_execution. State: 'S3 path for query results (required). Example: s3://my-bucket/athena-results/. Athena will store all query outputs here.'
Implement result stripping: filter boto3 responses to return only user-relevant fields. For list_work_groups, return {"work_groups": [{"name": "...", "description": "..."}, ...], "next_token": "..."}. For get_query_results, return {"columns": [...], "rows": [...], "result_count": ...} instead of raw boto3 metadata.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Error handling returns only generic boto3 ClientError messages without recovery guidance. Example: 'AWS Error: ValidationException - ...' tells the LLM nothing actionable, should suggest 'Catalog not found. Try list_databases() first.' or 'Database missing from catalog.'
Parameters lack constraints (enums, ranges, patterns). 'max_results' has no min/max documented (baseline: 1 - 100 for pagination). 'expression' parameter for list_tables accepts arbitrary regex but does not state format or valid patterns. 'work_group' defaults to 'primary' but lists no alternatives.
start_query_execution has conflicting/unclear parameters: 'database' is optional but query execution may require database context. 'output_location' is optional but Athena requires results location, should be required or auto-generated. Parameter interdependencies are undocumented.
list_tables 'expression' parameter is described as 'Regular expression to filter table names' but AWS API calls it 'Expression' and interprets it differently (Athena format, not regex). Parameter description is misleading.
No idempotency or confirmation support. start_query_execution has no dry-run or confirmation step, agents could accidentally run expensive/destructive queries without validation.
Parameter descriptions are minimal (1 - 5 words). 'Token for pagination' does not explain what token is returned from the previous call or how to use it. Baseline: 50 - 100 chars per param description. Current average: ~15 chars.
Add a dry-run or preview option to start_query_execution. Include a parameter 'preview: bool' that returns the parsed query and estimated result count without executing. This prevents accidental expensive queries.
Document parameter interdependencies. State: 'If database is omitted, the query must specify a fully qualified table name (catalog.database.table) or use a work group with a default database configured.'
Add rate-limit guidance in tool descriptions: 'Athena has API rate limits (typically 20 requests/second). Agents should batch list operations and cache results where possible.'
Implement proper pagination bounds. Set max_results: {"type": "integer", "minimum": 1, "maximum": 100, "default": 20} in JSON schemas instead of relying on description text.
Return work group IDs or names in paginated list responses so that subsequent start_query_execution calls have the exact string to pass to the work_group parameter.