RunLoop MCP Server has 51 tools with significant structural issues. Positive: tools are explicitly registered with names, basic descriptions, and Zod schemas. Critical gaps: (1) descriptions are universally too brief (avg ~15 chars, p10=7), far below the 50-200 char baseline for LLM optimization; (2) parameter descriptions are completely absent, Zod schemas define types but LLMs cannot read JSON Schema fields, they need human text descriptions; (3) no output schemas documented, preventing LLMs from planning downstream tool calls; (4) naming inconsistencies ('list' instead of 'listDevboxes'; 'retrieve' instead of 'retrieveDevboxes'); (5) no error handling guidance; (6) no pagination limits documented despite list tools accepting unbounded results. The server depends on Zod schemas imported from '../types/runLoopAPI.js', which are not visible in the source extract, so actual parameter schema quality cannot be verified. Tools score consistently 30-45 due to missing parameter descriptions and output documentation. This is a common pattern for API wrapper servers that expose CRUD operations without agent-specific optimization.
Parameter descriptions completely absent. Zod schemas imported from '../types/runLoopAPI.js' define types but are not visible in source. All 51 tools expose Zod parameters without human-readable text descriptions, LLMs cannot read JSON Schema 'type' fields, they need explicit text. This violates the fundamental pattern that every parameter must have a description. Example: 'limit' param in listBenchmarks has no description explaining its range, default, or purpose.
Expand all tool descriptions to 80-150 characters following the prompt-engineering model: state WHAT (action), WHEN (use case vs. similar tools), and WHAT returns (key fields). Example: 'Create a new Devbox from an optional blueprint. Returns devbox_id, status, and public_ip for subsequent commands like executeSync. Requires a blueprint_id if no default is set.'
Add parameter descriptions inline in tool definitions. Export parameter metadata as objects with 'type', 'description', 'required', 'enum' (if applicable), and 'default' fields. Every parameter exposed to the LLM must have a human-readable description. Example: { 'limit': { type: 'number', description: 'Max results (1-100, default 20)', required: false, min: 1, max: 100 } }.
Document output schemas for every tool. Create a separate 'returns' field in each tool definition listing: field names, types, and whether they are always present or conditional. Example for createBlueprint: 'Returns: { blueprint_id (string, unique identifier), name (string), status (enum: building|ready|failed), created_at (ISO 8601 date) }'.
Rename generic devbox tools from 'list', 'create', 'retrieve' to 'listDevboxes', 'createDevbox', 'retrieveDevbox' to eliminate ambiguity across tool groups.
Add max result limits to all list tools and document them in descriptions. Example: 'Returns up to 50 benchmarks per page. Use starting_after for pagination.'
Implement confirmation pattern for destructive tools. Add optional 'confirm' parameter (default false) to deleteSnapshot and deleteRepositoryConnection. When false, return a confirmation message with the resource details instead of deleting. Only delete if confirm=true.
Tool descriptions universally too brief (avg 25 chars, all under 40 chars). Baseline for LLM-optimized descriptions is 50-200 chars. Current descriptions like 'List all available benchmarks.' are minimal and lack context for when to use the tool vs. similar tools, prerequisites, or return value structure. LLMs struggle to select the right tool when descriptions are this sparse.
No output schemas documented. LLMs cannot plan downstream tool calls or extract relevant data without knowing the response structure. Example: after calling 'createBlueprint', what fields does the response contain? Does it return a blueprint_id that subsequent tools expect? Without documented schemas, agents cannot compose tools effectively.
No error handling guidance. Tools do not document what can go wrong, how to recover, or whether errors are retryable. Example: if 'retrieveBenchmark' fails with 'Benchmark not found', should the LLM try a different ID, call listBenchmarks first, or give up? Without recovery hints, agents are left guessing.
Naming inconsistencies and poor verb alignment in devbox tools. 'list', 'create', 'retrieve', 'suspend', 'resume', 'shutdown' are bare verbs without object context (should be 'listDevboxes', 'createDevbox', etc.). LLMs struggle to disambiguate when multiple tool groups use bare verbs, which 'list' applies to which resource? This violates verb_noun naming pattern.
No pagination limits documented for list tools. listBenchmarks, listBlueprints, listScenarios accept 'limit' parameter but no max is specified. Without enforced limits, agents could request 10000 items, blowing context windows. Baseline pattern requires capping at 20-50 and documenting the limit in descriptions.
Destructive tools (deleteSnapshot, deleteRepositoryConnection, shutdown) have no confirmation or dry-run patterns. Agents can delete resources irreversibly without warning. Baseline pattern 'confirmation-request' requires supporting a confirm step for destructive operations to prevent accidental data loss.
Zod schemas not visible in source extract. Tools import from '../types/runLoopAPI.js' (e.g., 'createBenchmarkBody', 'listBenchmarksQueryParams'), but the actual schema definitions are not provided. Cannot verify if schemas include required/optional flags, constraints (min/max for numbers, patterns for strings), enum declarations, or type correctness.
Provide Zod schema definitions (from '../types/runLoopAPI.js') in a separate 'schemas.ts' file or inline comment section so validators and constraint info are visible. Include min/max bounds, enums, and regex patterns in schema definitions.
Add recovery hints to error scenarios. Document expected errors for each tool (e.g., 'retrieveBenchmark may return 404 if benchmark_id is invalid, try listBenchmarks first to find valid IDs').
Create tool groups with consistent naming: all 'read' tools start with 'get_' or 'list_', all 'write' tools start with 'create_', 'update_', or 'delete_'. This helps LLMs categorize operations by risk level.