AWS Cost MCP server has basic tool definitions with schemas and descriptions present, but significant quality gaps limit production readiness. All 8 tools have descriptions (10-60 chars, mostly short) and input schemas with type definitions. However, descriptions are generic and lack LLM-optimized guidance on WHEN to use each tool or HOW to chain them. Parameter descriptions are minimal (e.g., 'The SQL query statements to be executed' for query_string). No output schemas documented. Error handling returns raw exception strings instead of actionable recovery guidance. No tool annotations (readOnlyHint/destructiveHint). Naming is verb-prefixed and clear (athena_start_query_execution, athena_get_query_results), following verb_noun convention. No security issues detected (no secrets in params). Composition is reasonable, tools are single-purpose and chainable (start → get_execution → get_results). However, lack of pagination guidance, missing output field documentation, and generic error messages significantly reduce LLM usability.

• Expand tool descriptions to 100-200 chars. Include WHEN to use (e.g., 'Call after start_query_execution to check if the query has completed'), prerequisites, and what the tool returns. Example: 'Gets the status and metadata of a query execution. Call this after start_query_execution to poll for completion. Returns status (QUEUED|RUNNING|SUCCEEDED|FAILED|CANCELLED), submission time, and result location.'
• Document output schemas for all tools. Specify which fields are returned (e.g., QueryExecution returns query_execution_id, status, submission_time, completion_time, result_configuration). This enables LLMs to chain tools correctly and extract needed IDs for downstream calls.
• Replace generic error handling with actionable recovery guidance. Categorize errors: retryable (timeout, throttle) → 'Retry in 5 seconds'; user-fixable (invalid query, missing database) → 'Check query syntax or verify database exists'; fatal (permission denied) → 'Contact AWS admin'. Example: 'Invalid database: {database}. Available databases: {list}. Call athena_list_databases() to discover valid options.'
• Add tool annotations via MCP schema. Mark athena_start_query_execution, athena_stop_query_execution, and athena_run_query with destructiveHint=true. Mark read-only tools (athena_get_*, athena_list_*) with readOnlyHint=true. Mark idempotent tools (e.g., athena_get_query_execution) with idempotentHint=true.
• Add parameter constraints. Specify max_results range (1-1000), poll_interval range (1-60 seconds), max_wait_time range (1-3600 seconds). Add regex pattern for query_string if applicable. Example: 'max_results: Maximum number of results to return (1-1000, default 20). Larger values may slow pagination.'

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

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