Static source inference · medium confidence · evidence: Streamable HTTP
Current-spec patterns detected
Summary
This TRMM MCP server has 56 tools with mixed definition quality. Strengths: most tools have basic descriptions (1-3 sentences) and clear verb-noun naming conventions (list_, get_, create_, run_, etc.). Critical weaknesses: (1) many tools lack input parameter descriptions entirely, parameters like 'agent_id', 'check_id', 'script_id' have type but no description explaining what they control or their valid ranges; (2) output schemas are undocumented, no tool specifies what fields are returned or their structure; (3) many descriptions are generic and under 50 characters, insufficient for LLM tool selection guidance; (4) error handling is absent, no tool provides recovery guidance or error classification; (5) sensitive operations (reboot_agent, shutdown_agent, uninstall_agent_software, kill_agent_process) have no confirmation/dry-run pattern; (6) several tools duplicate functionality (run_checks vs run_checks_for_agent, test_script_on_agent vs run_agent_script) without clear distinction. Per-tool analysis reveals ~40% of tools have incomplete parameter documentation. This server is functional for agent integration but falls well below production quality standards.
Output schemas completely undocumented. No tool declares what fields are returned, their types, or structure. LLMs cannot plan downstream tool calls or extract required data (e.g., which response fields contain agent_id, status, timestamp).
Many parameters lack descriptions. 'agent_id', 'check_id', 'script_id', 'policy_id', 'task_id' appear repeatedly across tools with type but no description of what they represent, valid format, or how to obtain them. This forces LLMs to guess whether IDs are UUIDs, numeric, or alphanumeric.
get_agentget_agent_history
Recommendations
Document the output schema for every tool. Specify the structure of the response object, field names, types, and which fields are required. Example: 'Returns {ok: boolean, agents: [{id: string, hostname: string, status: string, last_seen: ISO8601_datetime}], total: integer}', this helps LLMs know what data is available and how to chain calls.
Add descriptions to all input parameters. For every parameter, explain: what it controls, what values are valid, how to obtain it if it's an ID. Example: 'agent_id (string): The unique agent identifier from TRMM. Can be obtained from list_agents response or provided by the user.'
Consolidate duplicate tools. Merge 'run_checks' and 'run_checks_for_agent' into a single 'run_agent_checks' with optional check_ids parameter. Merge 'test_script_on_agent' and 'run_agent_script' into 'run_agent_script' with both script_id and script_name options.
Expand descriptions for generic tools to 100-150 characters, following the pattern: 'ACTION on RESOURCE for PURPOSE. Returns DATA. Use this when CONTEXT.' Example: 'Get full details for a specific agent including hostname, status, last check-in, and assigned policies. Returns agent object with all metadata. Use this after searching to retrieve a specific agent's configuration.'
Add confirmation/dry-run pattern to destructive operations. For shutdown_agent, reboot_agent, kill_agent_process, uninstall_agent_software: add an optional 'dry_run: boolean' parameter. When true, return what WOULD happen without executing. This prevents accidental infrastructure destruction.
Duplicate/overlapping tools without clear distinction. 'run_checks' and 'run_checks_for_agent' both run checks; 'test_script_on_agent' and 'run_agent_script' both execute scripts. LLMs cannot reliably distinguish when to use one vs. the other, wasting reasoning cycles.
Destructive/irreversible operations (shutdown_agent, reboot_agent, kill_agent_process, uninstall_agent_software) lack confirmation or dry-run patterns. Agents can accidentally destroy infrastructure without a safety gate. No descriptions warn of irreversibility.
Generic tool descriptions under 50 characters. Many descriptions like 'Get one agent by ID', 'Get history for an agent', 'Get notes for an agent' are too brief to guide LLM tool selection. No context on WHEN to use the tool, WHAT problem it solves, or HOW it differs from similar tools.
No error handling guidance. Tools provide no recovery instructions, error classification (retryable vs. fatal), or examples of what went wrong. A 404 or timeout returns raw error with no actionable next step for the LLM.
Parameter constraints undocumented or vague. 'timeout_seconds' defaults to 90 but no min/max specified. 'mode' enum for reboot_agent is clear, but many other enums (shell, action, status) lack context. 'query' parameter in query_api/run_api is too vague, what format? what constraints?
query_api and run_api tools are dangerously generic. They forward arbitrary requests to an external API, creating injection risks if not properly sanitized. No scope/permission declaration, no rate limiting guidance, no audit trail documentation.
query_apirun_api
Add error handling descriptions to tools that call external APIs. Example: 'If the agent is offline, returns {ok: false, error: 'agent_offline', recovery: 'Try run_agent_command to wake the agent or check connectivity via list_agents.'}'. This guides the LLM on next steps.
Specify parameter constraints in descriptions. For timeout_seconds, document the range (e.g., '1-3600 seconds, default 90'). For query in query_api/run_api, document expected format (e.g., 'URL path relative to TRMM API root, e.g. /agents or /checks/1').
Add permission/scope declarations to sensitive tools. Document that query_api and run_api require 'admin' or 'api_full' permission, and that shutdown_agent, kill_agent_process require 'infrastructure_control'. This enables least-privilege agent configurations.
Implement rate limiting and input validation for query_api and run_api. Sanitize the 'query' parameter to prevent path traversal or injection. Log all calls with agent name, timestamp, and query for audit trails.
Add pagination guidance to list_* tools. Specify that results are capped (e.g., 'Returns up to 100 agents. For larger datasets, results are paginated by agent ID.') and document how to fetch the next page if applicable.