MCP server that converts OpenAPI specs into tools which can query API endpoints
SpecRun exposes 5 tools, all with descriptions and Zod schemas. However, most tool parameter descriptions are minimal (e.g., 'Name of the SpecRun tool to execute in batch' for toolName is only 48 chars; 'Array of input objects to process' is 33 chars). Tool purposes are clear from names, but parameter guidance is sparse. The batch tool is well-structured with validation and error handling, but the prompt-based tools (list_apis, generate_api_call, explain_api_schema, generate_random_data) lack visible schema definitions in the source code, they are registered but their input schemas are inferred rather than explicitly shown.
Explain tool parameters and request body schema.
Collect required inputs for a tool and provide a ready-to-run JSON payload.
Generate random, ready-to-run JSON payload samples for a tool.
List loaded APIs/tools and ask the user to choose an endpoint.
Run any SpecRun tool in batch with multiple inputs
Four prompt-based tools lack visible, explicit schema definitions in source code. Tool registration exists but input schemas are inferred from the FEATURE list, not directly visible in src/prompts.ts.
Parameter descriptions are minimal and generic. 'Array of input objects to process' (33 chars) lacks format guidance. 'Name of the SpecRun tool to execute in batch' (48 chars) does not explain WHEN to use batch vs individual calls or ERROR HANDLING for partial failures. Baseline: param descriptions average 72 chars; these are well below baseline.
specrun_batch has optional parameters (failFast, confirmLargeBatch, confirmLargeBatchToken) but descriptions do not explain dependency or mutual exclusivity. failFast and confirmLargeBatch appear independent but confirmLargeBatchToken is only meaningful after a first rejection, undocumented state machine.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 51 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 21 | - | v1 |
list_apis accepts 'filter' (substring) and 'max_results' parameters but no guidance on filtering semantics (case-sensitive? substring or regex? how does it order results?). No pagination guidance despite 'cursor' param presence.
Output schema for all tools is not documented in tool descriptions. Agents do not know what to expect from generate_api_call, explain_api_schema, or generate_random_data return values, structure is unknown.
specrun_batch error handling returns a resource with an error object, but the response structure is not documented. It is unclear whether the caller should inspect the resource or check isError flag or both. Error guidance is vague.