This AWS MCP server has 11 tools with visible schemas and basic descriptions, but suffers from significant gaps in parameter documentation, output schemas, and error handling guidance. All tools are properly named with action verbs (aws_ec2_list_instances, aws_s3_upload_object, etc.), which is a strength. However, most parameter descriptions are minimal (typically 1-3 words: 'Instance ID', 'Bucket name'), falling below the production baseline of 72 characters average per parameter. Critical parameters like 'filters' in aws_ec2_list_instances lack any guidance on structure or format. Output schemas are completely undocumented, the code does not show what these tools return, making it impossible for LLMs to chain calls or extract required fields. Error handling is absent from visible code; there is no recovery guidance, no categorization of retryable vs fatal errors, and no validation error messages. The aws_dynamodb_query tool exposes raw DynamoDB syntax ('key_condition_expression') without constraint validation or format examples, inviting malformed queries. Multi-account/region parameters (account, region) are present but lack clear defaults or validation rules. Security: the config module is not shown, but there is no visible evidence of API key injection or permission gates. Overall, the server defines tools at a minimal viable level but does not meet production standards for LLM-driven composition.
Output schemas completely undocumented. No tool shows what it returns, making tool chaining impossible. LLMs cannot extract fields needed for downstream calls.
Add explicit output schemas for all 11 tools. Example for aws_ec2_list_instances: {"type": "object", "properties": {"instances": {"type": "array", "items": {"type": "object", "properties": {"instance_id": {"type": "string"}, "state": {"type": "string"}, "instance_type": {"type": "string"}, "public_ip": {"type": "string"}}}}, "total_count": {"type": "integer"}}}. Document in tool description: 'Returns list of instances with id, state, type, and IP.'
Expand every parameter description to 50-150 characters with format and constraint details. Example for instance_type: 'Instance type (e.g., t2.micro, t3.small, m5.large). Must be available in the target region. Larger types cost more.'
For aws_dynamodb_query, replace 'key_condition_expression' with a structured input. Add example: 'Query a DynamoDB table. Key condition format: {"partition_key": {"value": "...", "type": "S|N"}, "sort_key": {"value": "...", "type": "S|N", "operator": "="|"<"|">"|"<="|">="|"BETWEEN"}}'. Provide validation error messages for malformed conditions.
Add recovery guidance to tool descriptions for common failures. Example for aws_s3_upload_object: 'If bucket not found, call aws_s3_list_buckets() to find correct bucket name. If permission denied, verify AWS credentials and bucket policy.'
Add defaults and constraints to region and account parameters in all tools. Example: 'AWS region (default: us-east-1). Must be a valid AWS region: us-east-1, us-west-2, eu-west-1, etc.'
For list tools, add pagination parameters: 'max_results' (integer, 1-100, default 20) and 'next_token' (string, optional). Return output schema with 'items' array and 'next_token' if more results exist. Cap results at 20-50 per call to avoid context window exhaustion.
aws_dynamodb_query exposes raw DynamoDB key_condition_expression syntax without format guidance, examples, or validation. LLMs will hallucinate invalid expressions.
No error handling guidance. Code does not show recovery prompts, error categorization (retryable vs fatal), or actionable error messages. Agents will fail silently or retry blindly.
Destructive/write tools (create_instance, upload_object, invoke) lack state-change warnings in descriptions. LLMs need explicit guidance that these operations are irreversible or have side effects.
List tools (list_instances, list_buckets, list_objects, list_functions) lack pagination guidance and result limits. max_keys defaults to 1000, which may exhaust context windows. No mention of cursor/marker-based pagination.
Parameter 'filters' in aws_ec2_list_instances has no structure guidance. Is it an array of {key, value} pairs? What keys are valid? LLMs will guess or hallucinate.
account and region parameters lack clear defaults. Tool descriptions do not state: if region is omitted, which region is used? If account is omitted, does it default to the server's primary account?
instance_type, ami_id, and operation parameters lack enum constraints or format patterns. Descriptions do not list valid values (t2.micro, t3.small, etc.). LLMs will hallucinate invalid values.
No visible security patterns: no credential injection mechanism shown, no permission gates, no audit logging visible in code. Configuration module (config.py) is not shown, so cannot verify secret handling.
Add enum constraints to constrained parameters. Example for invocation_type in aws_lambda_invoke: '"invocation_type": {"type": "string", "enum": ["RequestResponse", "Event", "DryRun"], "description": "Synchronous (RequestResponse) or asynchronous (Event) invocation."}'
For destructive operations (create_instance, upload_object, invoke), add state-change warnings to descriptions. Example: 'Creates a new EC2 instance and charges to your AWS account. This operation is reversible (you can terminate the instance later) but not free.'
Implement input validation with actionable error messages. Example: 'Invalid instance_type: got "t2.xlarge" but region "ap-south-1" does not offer t2 instances. Available types: t3.micro, t3.small, ...' instead of raw 400/500 errors.
Document instance_id format in aws_ec2_stop_instance and aws_ec2_start_instance: 'Instance ID (format: i-0123456789abcdef0, typically 10+ hex chars after i-).'
For aws_s3_presigned_url, add enum constraint for operation: '"operation": {"type": "string", "enum": ["get_object", "put_object", "delete_object"], "description": "S3 operation to authorize."}'
Add security audit log configuration visible in code. Show in server.py or config.py: 'Every tool call is logged with user ID, tool name, parameters (excluding secrets), timestamp, and result. Audit log written to /var/log/aws-mcp-audit.log or CloudWatch Logs.'
Verify credential handling in config.py (not shown). Ensure AWS credentials come from environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) or IAM role, NOT from tool parameters.
Add permission scopes to tool descriptions. Example for aws_ec2_create_instance: 'Requires EC2:RunInstances IAM permission.'
Include field-mapping guidance in chained workflows. Example in aws_ec2_list_instances output description: 'The instance_id returned can be passed to aws_ec2_stop_instance, aws_ec2_start_instance, or aws_lambda_invoke (if Lambda function accepts instance_id parameter).'