YApi MCP server has 2 tools with basic definitions present in main.go handleListTools(). Both tools have names starting with action verbs (get_), which is correct. However, the definitions suffer from critical gaps: parameter descriptions are minimal and lack detail about expected format/constraints; output schemas are not documented anywhere in the code; error handling is present but generic without recovery guidance. Tool names are clear and distinct (get_yapi_interface vs get_yapi_project_interfaces), but descriptions are in Chinese and lack the depth required for LLM disambiguation. No parameter validation rules documented. Overall, definitions are functional but well below production quality.
从YApi文档链接读取接口信息
获取YApi项目中所有接口的列表
Parameter descriptions are minimal and lack validation guidance. The 'url' parameter for get_yapi_interface is described only as 'YApi文档链接' (YApi document link) with no mention of expected format, whether it must be a full URL or can be a path, or what constitutes a valid link. Similarly, 'project_url' lacks clarity on whether it accepts project ID, full URL, or both, and no guidance on format.
No output schema documented. The handleCallTool() function returns JSON.MarshalIndent(info, ...) but there is no specification of what the 'info' structure contains, what fields are present, their types, or what the LLM should expect. This violates the requirement that tools must document output schemas.
Tool descriptions are written in Chinese and are extremely brief (10-20 characters each). While the descriptions state WHAT the tool does, they do not explain WHEN to use it instead of the other tool, what prerequisites exist (e.g., must YAPI_BASE_URL env var be set?), or what the tool returns. Descriptions should be 50-200 characters for LLM disambiguation.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 47 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 31 | 2024-11-05+ | v1 |
Error responses are generic text without recovery guidance. When get_yapi_interface fails (line in handleCallTool: 'Error: %s', err.Error()), the LLM receives a raw error message with no instruction on what to do next. Should it retry? Try a different URL format? Check the environment variables? The pattern:recovery-guide is not followed.
Credentials are injected via environment variables YAPI_BASE_URL and YAPI_TOKEN, which is correct (pattern:secret-injection). However, no documentation exists in the tool descriptions or README about how to configure these, making it difficult for agents to know prerequisites.
No documentation of return structure or pagination. If get_yapi_project_interfaces returns a list of interfaces, there is no indication of whether results are paginated, what the limit is, how to fetch more, or what fields each interface object contains. This forces LLMs to guess at response structure.
No parameter type constraints or enums. Both tools accept string parameters with no validation constraints (min/max length, regex pattern, allowed values). The yapi_parser.go file is not provided, so actual validation is unclear, but the tool definitions expose no constraints to the LLM.