Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
CloudCommand's MCP tools suffer from severe documentation and schema deficiencies. While tool names follow verb_noun convention (get_cluster_list, create_ec2_agent, delete_agent), actual parameter schemas, return types, and descriptions are not visible in the provided source code. The MCP server is configured via fastmcp.add_tool() calls in mcp_server.py, but the underlying tool definitions in router/agent.py and router/command.py are not shown. Without seeing the actual function signatures, parameter annotations, or docstrings, I cannot verify schema completeness. Based on the code fragment visibility, input schemas appear completely undocumented, and descriptions are either missing or not provided. This forces a conservative score reflecting the absence of verifiable quality signals.
CRITICAL: Destructive operations (delete_agent, potentially create_ec2_agent) lack error handling, confirmation patterns, and recovery guidance. Per guidelines: 'Irreversible operations should support a dry-run or confirmation step. Error responses must tell the LLM what to do next.' No dry-run, no confirmation, no actionable error text visible.
Recommendations
Add complete docstrings to all 6 tool functions in cloud_command/router/agent.py and cloud_command/router/command.py. Each docstring must answer: What does it do? When to use it instead of similar tools? What does it return? Example: 'Get the current status and metadata of a running EC2 agent. Use this before running commands to verify the agent is healthy. Returns agent_id, instance_type, region, status (running|stopped|error), last_heartbeat timestamp.'
Define JSON Schema for all tool inputs in FastMCP tool registration. Use fastmcp field annotations: @mcp.tool() with explicit input schema. For create_ec2_agent, include: instance_type (enum: t4g.nano, t4g.micro, t4g.small, ...), region (enum: us-east-1, eu-west-1, ...), availability_zone (string), dry_run (boolean, default false for safety).
Add descriptions to every parameter. Example for create_ec2_agent region param: 'AWS region code (e.g. us-east-1). See mcp_server.py instructions for full list of supported regions.'
For delete_agent, implement a two-step confirmation pattern: (1) delete_agent(..., dry_run=true) returns what would be deleted; (2) user approves, then delete_agent(..., confirm=true) executes. Add error recovery: 'Agent deletion failed: agent_id=<id> not found. Available agents: <list>. Try get_cluster_list() first.'
HIGH: Output schemas not documented. Guidelines state: 'Document the output schema. LLMs need to know what fields to expect.' Return types for all 6 tools are not visible, preventing agents from chaining tool results.
HIGH: No parameter validation or constraint documentation visible. Guidelines: 'Never expose API keys as parameters. Gate destructive tools behind permission checks. Sanitize agent input against injection.' AWS credentials, region selection, instance type, none of these constraints are visible in the schema.
MEDIUM: create_ec2_agent tool lacks guidance on instance type selection despite instructions containing detailed t4g instance table. Schema should include enum of valid instance types; descriptions should reference the sizing trade-offs documented in mcp_server.py.
MEDIUM: No pagination parameters visible for list/get tools. Guidelines: 'Tools returning lists should accept page/offset and limit parameters.' get_cluster_list likely returns multiple agents, without pagination, large results can blow context window.
get_cluster_list
Add pagination to get_cluster_list: include limit (default 20, max 100) and offset parameters. Return total_count so agents know if more results exist. Baseline: average tool description 194 chars, yours are 0.
Validate create_ec2_agent inputs server-side. Reject invalid instance types with: 'Invalid instance_type: t5.large. Must be one of: t4g.nano, t4g.micro, t4g.small, ... See instructions for CPU/memory tradeoffs.' Reject invalid regions with suggestions.
Add permission gates for destructive operations. Before delete_agent executes, check: (1) User has 'agent:delete' permission. (2) Agent is not locked. (3) No active commands running. Return clear error if any gate fails: 'Cannot delete agent-123: 1 active command running. Cancel commands first with agent_command_status() and agent_run_command(agent_id, command="kill <pid>").'
For agent_run_command and agent_command_status, specify output structure including error fields. Example agent_run_command return: '{command_id: string, agent_id: string, command: string, status: "queued"|"running"|"completed"|"error", exit_code: number|null, stdout_preview: string, stderr_preview: string, started_at: ISO8601|null, completed_at: ISO8601|null}'. This lets agents extract exit codes and plan error recovery.
Document error conditions with recovery guidance. For each tool, list common failures: 'Agent not found' (call get_cluster_list to discover available agents), 'Command timeout' (increase timeout param or break into smaller steps), 'Permission denied' (verify user role), 'Insufficient capacity' (try different region or instance type).