Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
This server has moderate definition quality with mixed results. All 5 tools are explicitly registered with the @mcp.tool decorator in dea/server.py and have input schemas and descriptions. However, descriptions are generic and lack the detail needed for confident LLM tool selection. Parameter descriptions are minimal. Output schemas are not documented. Error handling is absent, tools return raw results or may fail silently. Naming is reasonable (verb_noun pattern) but descriptions do not clarify when/why to use each tool or how results relate. The server follows basic definition patterns but falls short of production readiness.
No output schemas documented. Tools return unstructured dicts with 'status' and 'content' fields. LLMs cannot reliably extract results or chain tool calls. E.g., list_tables_tool returns a JSON array but the structure is not declared.
Descriptions lack context and guidance. 'Upload file to s3 bucket' does not explain when to use this vs other S3 operations, what happens on success/failure, or whether it's idempotent. Descriptions should be 50-200 chars and answer WHAT, WHEN, and WHY. Current descriptions average ~30 chars and are too terse.
Parameter descriptions are missing or trivial. E.g., 'database_name' appears in create_table and run_sql_athena but lacks guidance on valid formats, whether it must exist beforehand, or dependencies. All 4 parameters in create_table need clearer descriptions.
Recommendations
Add formal output schema documentation for each tool. E.g., s3_upload_file should document: returns {status: 'success'|'error', error_message?: string, file_key?: string}. LLMs cannot extract or chain without knowing response structure.
Expand tool descriptions to 50-150 chars each, answering: What does it do? When should I call it? What are prerequisites? Example: 's3_upload_file: Upload a local CSV file to S3. Use this after listing available files with available_files_to_upload. Requires valid local_file_path (must exist), S3 bucket (must be writable), and S3 key (path under bucket). Returns status and file URL on success. Idempotent: safe to retry.'
Add descriptions to all parameters. For database_name, specify: 'AWS Glue database name (alphanumeric, 1-255 chars, underscores allowed). Must exist before calling this tool. If unsure, use list_tables_tool to discover available databases.' Similar clarity for table_name, query, etc.
Wrap all tool calls in try-catch. Return structured errors with actionable recovery hints. E.g., if s3_upload_file fails with 'NoSuchBucket', return: 'S3 bucket "my-bucket" does not exist or is not accessible. Available buckets: [list]. Or create a new bucket first.' This lets LLMs self-correct without extra calls.
Add input validation. Reject invalid database_name or table_name formats early with clear error messages. Validate that local_file_path exists and is readable before attempting upload. Return 'File not found: /path/to/file (checked: current dir is /home/user). Available files: [list]' to guide the agent.
No error handling or recovery guidance. Tools do not catch exceptions or return actionable errors. If s3_upload_file fails (file not found, permissions, bucket does not exist), the LLM receives a raw stack trace. Error responses must tell the LLM what to do next.
Tool naming ambiguity: 'available_files_to_upload' lists local data/ directory files, but the description does not clarify scope (only .csv? only under data/?) or what to do next. Should it be 'list_local_csv_files' or 'get_uploadable_files'? Current name is too generic.
list_tables_tool has awkward naming. Should be 'list_glue_tables' or 'list_database_tables' for clarity. Tool names should follow verb_noun; 'list_tables_tool' has 'tool' appended, suggesting the name itself is incomplete.
No pagination or result limits. create_table and run_sql_athena may process large datasets. list_tables_tool could return hundreds of tables. Tools do not accept limit/offset parameters or cap results. Large unbounded results blow context windows.
No tool annotations for destructiveness. create_table modifies Glue state (deletes/recreates tables); s3_upload_file is write-only. Neither declares destructiveHint or idempotentHint. This prevents agents from reasoning about safety and retry semantics.
Parameter naming lacks type suffixes. 's3_bucket' and 's3_key' are clear, but 'database_name' and 'table_name' could benefit from documentation about valid formats (alphanumeric, length limits, special chars allowed?). No enums or pattern constraints provided.
create_tablerun_sql_athenalist_tables_tool
Rename 'list_tables_tool' to 'list_glue_tables' or 'list_database_tables' for clarity. Remove 'tool' suffix, it is redundant and signals incomplete naming.
Clarify scope in available_files_to_upload. Rename to 'list_uploadable_files' and document: 'Lists all CSV files in ./data/ directory available for upload to S3. Returns file names only. Use this first to confirm the file exists before calling s3_upload_file.'
Add tool annotations (requires fastmcp support): mark create_table with destructiveHint=true (deletes existing table), s3_upload_file with destructiveHint=true (overwrites object). Mark read-only tools (run_sql_athena, list_tables_tool, available_files_to_upload) with readOnlyHint=true. Mark idempotent operations if any.
Implement pagination for list_tables_tool. Add optional 'limit' and 'next_token' parameters. Return {tables: [...], next_token?: string, total_count: number}. Cap default limit at 50 to prevent context explosion.
Add parameter constraints. For query in run_sql_athena, document: 'Valid SQL SELECT queries. DDL/DML not supported. Max query length 10KB. Must reference tables in the specified database.' For table_name, specify: 'Alphanumeric + underscores, 1-255 chars, must start with letter.'
Document parameter relationships. E.g., in create_table: 's3_key must point to a valid CSV file (not a directory). The CSV header row determines column names. table_name and database_name must be valid Glue identifiers and unique within the database.' Cross-reference related tools: 'After upload with s3_upload_file, call this to register the table for querying with run_sql_athena.'
Add dry-run support for destructive operations. Allow create_table to accept a 'dry_run=true' parameter that validates the CSV and database without modifying state. This prevents accidental table overwrites.
Return chaining IDs in responses. If s3_upload_file returns the full S3 URI, create_table can be called immediately without parsing. If run_sql_athena returns table metadata, the agent can plan downstream operations. Ensure each tool output includes IDs the next tool needs.