This OpenAPI MCP server demonstrates significant gaps in definition quality. While all 4 tools are explicitly registered with schemas and descriptions, the quality across naming, descriptions, parameters, and output documentation is below production baseline. Tool names follow verb_noun convention adequately (get-*, search-*), but descriptions are generic and lack actionable context. Parameter descriptions are sparse or absent (e.g., 'path' param in get-api-path-method has null description). No output schemas are documented, forcing LLMs to infer response structure. Error handling is minimal, the code returns plaintext Japanese error messages without actionable recovery guidance. The server targets OpenAPI spec inspection, a reasonable use case, but the tool interface does not optimize for agent composition or natural language alignment.
Get the API details of the specified path and method.
Get the methods of the specified API path.
Get all API paths.
Search the API path and description by keyword.
Output schemas not documented for any tool. LLMs cannot predict response structure, is it JSON, markdown, array, object? Implementing pattern:response-shaper requires explicit output schema definitions.
Parameter descriptions missing or inadequate. get-api-path-method has 'path' parameter with null description. search-api-by-keyword and get-api-details use Japanese descriptions, breaking LLM alignment for international models.
Tool descriptions are generic and lack actionable context. 'Get all API paths' and 'Get the methods of the specified API path' do not explain WHEN to call this tool instead of alternatives, or what the response structure is. Per pattern:tool-description baseline (average 194 chars), these descriptions are <50 chars.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 42 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 42 | - | v1 |
No pagination support. Tools like get-api-paths and search-api-by-keyword may return hundreds of results on large OpenAPI specs, exceeding context windows without limit/offset/page parameters. Per pattern:paginated-result, tools returning lists must accept pagination parameters and return total count or next_cursor.
Error responses do not guide LLM recovery. When a path is not found (return 'パス「${path}」は見つかりませんでした。'), the LLM receives plaintext Japanese without actionable next steps (e.g., 'Try search-api-by-keyword to find similar paths'). Per pattern:recovery-guide, errors must tell the LLM what to do next.
Response output is free-form markdown (human-readable) rather than structured JSON. get-api-details returns formatted markdown (e.g., '# ${endpoint.summary}\n\n**パス**: ${path}...'), which requires LLM parsing and wastes tokens. Per pattern:response-shaper, return structured objects with typed fields.
Language barrier: Japanese parameter descriptions and error messages. LLMs trained primarily on English may misinterpret or fail to understand Japanese descriptions. Per pattern:tool-description and mxe:chat-data-model, tool interfaces should align with the LLM's primary language.