Parse, validate, and generate code from OpenAPI specifications with full dependency tracking
Server has functional tool definitions with schemas and descriptions present for all 5 tools. However, quality is uneven: naming is mostly verb-driven (parse, query, diff, generate, status) but lacks consistency in parameter naming conventions. Descriptions are present but often lack actionable guidance for LLM selection. Schemas are formally defined but several critical patterns are missing: no pagination totals, no error guidance in descriptions, no output schema documentation, and no tool annotations. The oas_codegen tool accepts a WRITE operation but lacks confirmation/dry-run safeguards. Parameter descriptions exist but lack actionable constraints (e.g., format enums lack explanation of when to use each). Tool composition is reasonable (each does one thing) but chaining requires manual ID passing without guarantees that all necessary fields are returned.
Generate client code from OpenAPI spec. Supports TypeScript, Go, Rust, Python with customizable templates.
Query dependency graph - find affected paths when schema changes. Essential for tracking impact of schema modifications.
Compare two OpenAPI spec versions. Shows added, modified, removed endpoints and schemas, with breaking change detection.
Parse OpenAPI spec with pagination. Default format=summary returns just metadata. Use endpoints-list/schemas-list to discover, then endpoints/schemas for details.
Get server status and cache information.
No output schema documentation. Tool descriptions state WHAT they return in prose (e.g., 'Shows added, modified, removed endpoints') but none include a formal outputSchema or structured description of return fields. LLMs cannot plan downstream actions without knowing what fields to extract.
Pagination missing totals and next_cursor. oas_parse accepts 'limit' and 'offset' parameters but description does not state whether the response includes a total count or next_cursor, preventing the LLM from planning multi-page requests.
oas_codegen is a WRITE operation (generates code, modifies output_dir) but lacks confirmation/dry-run safeguard. No description warns that this tool has irreversible side effects. Agents may invoke it without intent confirmation.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 54 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 34 | - | v1 |
Format enum in oas_parse lacks actionable description. The enum lists 'summary', 'endpoints-list', 'schemas-list', 'endpoints', 'schemas', 'full' but the description does not explain WHEN to use each (e.g., when would an agent choose 'endpoints-list' vs 'endpoints'?). Descriptions should guide LLM choice.
Parameter naming inconsistency. Some tools use 'source' (oas_parse, oas_deps, oas_codegen, oas_diff), but oas_diff splits this into 'old_source' and 'new_source'. When multiple tools operate on the same resource type, their parameter names should align unless there is a clear semantic reason. 'source' vs 'old_source'/'new_source' increases cognitive load for LLMs.
oas_status description is vague ('Get server status and cache information'). It does not explain WHEN an agent should call it (e.g., to check if a spec is cached before parsing?), what 'status' means, or what fields it returns. Ambiguous descriptions reduce tool discoverability.
No error guidance in tool descriptions. None of the tools explain what errors are possible or what the LLM should do if a call fails (e.g., if oas_parse fails on an invalid spec, should the agent validate it first? Should it try a different format?). Error recovery guidance is missing.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). The source declares Risk: READ_ONLY or WRITE for each tool, but the tool definitions in handle_tools_list() do not include these annotations in the schema. Modern MCP spec rewards tool annotations for clarity on side effects.