Server Quality Checklist

Tool Scores

• yapi_get_advanced_mockC
  2.7/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  There are no annotations, so the description carries the burden of behavioral disclosure. It clearly communicates a read operation plus the required credentials (YAPI_EMAIL/YAPI_PASSWORD or Cookie), which is useful. However, it does not describe error behavior, side effects, or what the returned script payload looks like.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single focused sentence with the action and resource front-loaded, followed by a compact authentication note. It contains no wasted words, though it could have included more parameter context without becoming overly long.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given there is no output schema, no annotations, and no parameter explanation, the description leaves too much to inference. It does not clarify the role of the optional projectId, how the result is returned, or how this tool differs from yapi_get_interface_mock.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters1/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0% and the description adds no parameter information at all. An agent cannot learn what 'interfaceId' or 'projectId' represent, which one identifies the advanced mock, or why 'interfaceId' is required and 'projectId' is optional.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('读取', meaning read/get) and names the resource ('高级 Mock 自定义脚本'), so an agent can tell this is a read operation for advanced mock scripts. It partially distinguishes itself from 'yapi_get_interface_mock' through the word 'advanced', but does not explicitly contrast with any sibling.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  No guidance is given about when to choose this tool over related alternatives such as yapi_get_interface_mock or yapi_list_mock_cases. The only contextual note is the authentication requirement, which does not help an agent decide between sibling read tools.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• yapi_delete_mock_caseC
  2.8/5.0
  Behavior2/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'delete' and does not explain irreversibility, required permissions, failure behavior, or whether the operation is scoped to a project. This is especially important for a destructive operation.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single short sentence that communicates the core operation with no filler. It is front-loaded and easy to parse, though its brevity also contributes to missing contextual information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given there are no annotations and no output schema, a simple delete-tool description should still clarify parameter usage and deletion scope. The description is too minimal to fully support correct invocation, especially for identifying the right mock case to delete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters1/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0% and the description adds no parameter-level context. The schema only provides names and types (caseId: number, projectId: number), and the description does not explain what each parameter means, whether projectId is needed, or how caseId identifies the mock expectation.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific action ('删除' / delete) and a specific resource ('一条 Mock 期望' / a Mock expectation). The tool name and description clearly distinguish it from sibling tools like yapi_save_mock_case and yapi_list_mock_cases, which perform other operations on the same resource.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  There is no guidance about when to use this tool versus alternatives. It does not mention that this is the deletion counterpart to save/list/update operations, nor does it state any preconditions such as needing an existing caseId.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• yapi_call_mockB
  3.1/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden of behavioral disclosure. It communicates that the tool performs a request to a mock URL and checks whether a write took effect, which is useful. It does not disclose how method/body affect the request, whether the response is returned, or any side-effect/authorization implications, so transparency is partial.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single compact sentence with no filler, and the primary action is front-loaded. It is concise but slightly under-specified, which is an issue for completeness rather than for this dimension.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Context is incomplete for a 5-parameter tool with no annotations and no output schema. Missing details include how to construct the request, the role of projectId/interfaceId, the meaning of method/body, and what the returned confirmation looks like. The description gives only the high-level purpose.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Input schema has 5 parameters and 0% schema description coverage, so the description must compensate. It only clarifies mockUrl through '请求 mock URL'; body, method, projectId, and interfaceId are left to name-based inference. This is insufficient for correct invocation, especially with no required parameters and no descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific action ('请求 mock URL') and a clear purpose ('确认写入是否生效'), identifying both resource and expected outcome. It is distinguishable from sibling tools like yapi_update_interface_mock and yapi_list_mock_cases because it invokes the mock URL rather than managing configuration. However, it doesn't explicitly contrast itself with siblings, and '写入' is slightly vague without context.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The phrase '确认写入是否生效' implies this tool should be used after a mock write/update to verify the change, providing clear contextual timing. It does not state explicit alternatives, exclusions, or conditions under which another sibling tool would be preferred, leaving some inference required.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• yapi_list_mock_casesB
  3.2/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations, the description must carry the behavioral disclosure burden. '列出' (list) implies a read-only operation, but the description does not disclose output format, pagination, the meaning of advanced mock expectations, or any side effects. It provides only the most basic behavioral signal.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single clear sentence with no redundant words. It is concise and front-loaded with the core action, though the brevity leaves little room for guidance.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with no output schema and no annotations, the description is too sparse. It does not specify return values, how projectId and interfaceId relate, or any expected behavior such as filtering. Sibling tools make the domain clearer, but the description alone is insufficient for confident use.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, so the description must compensate by explaining parameters. It does not mention interfaceId or projectId, their purpose, or which is required. The parameter names are somewhat self-explanatory, but no semantic detail is added beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb '列出' (list) and identifies the resource '接口的高级 Mock 期望' (advanced mock expectations of an interface), which clearly distinguishes it from sibling update/get/save/delete operations. The purpose is immediately understandable without needing to inspect the schema.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives no context for when to use this tool versus alternatives. It does not mention that it is for viewing mocks rather than creating or updating them, nor does it name sibling tools or conditions for selection.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• yapi_save_mock_caseB
  3.2/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full disclosure burden. It does reveal the key behavioral trait — the same call creates or updates depending on whether caseId is present — which goes beyond what the schema shows. It does not, however, disclose update overwrite semantics, the effect of the dryRun flag, or any return behavior, so the mutation's side effects remain opaque.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two terse sentences with the verb-resource pair front-loaded and the branching instruction ('更新时传 caseId') placed second. There is zero filler — every clause earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with 11 parameters, 0% schema coverage, no annotations, and no output schema, this description is far from complete. An agent cannot know what dryRun does, how params affect matching, what result to expect on create versus update, or what side effects an update has on an existing mock case.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, so the description needed to compensate across 11 parameters, yet it only addresses caseId's role as the update discriminator. The three required parameters (interfaceId, name, resBody) and behavior-affecting fields (dryRun, params, ipEnable, delay, code, ip) are never explained, leaving the agent guessing at nearly every parameter's meaning.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description pairs a specific verb ('新增或更新' — create or update) with a specific resource ('Mock 期望' — Mock expectation), clearly conveying an upsert of mock cases. However, it does not differentiate this tool from siblings such as yapi_update_interface_mock or yapi_update_advanced_mock, so an agent still must infer which mock domain it operates on.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  '更新时传 caseId' is actionable guidance: it tells the agent how to select the update path versus the create path. But there is no guidance on prerequisites, what must be supplied for creation, or when to prefer this tool over its sibling mock tools — the agent must infer all of that.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• yapi_create_interfaceB
  3.4/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations, the description carries the burden of behavioral disclosure. It discloses the login requirement and the category-selection fallback when catId is omitted, which is useful context. However, it does not describe side effects, dryRun behavior, or what happens after creation.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description uses three short sentences with no wasted words. It front-loads the primary purpose, then adds the login prerequisite and the catId fallback rule.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For an 11-parameter, mutation-oriented tool with no annotations and no output schema, this description is too thin. It covers login and category selection but omits important behaviors around dryRun, projectId, and the write operation's effects, leaving an agent under-informed for safe invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 55%, and the description adds meaningful semantics for catId: omitting it selects 公共分类, otherwise the first category. Yet many parameters, especially dryRun, projectId, and resBodyIsJsonSchema, remain undocumented in both the schema and description, so the description only partially compensates.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific action ('新建接口' = create interface) and resource ('指定 YApi 项目' = specified YApi project), making the core purpose clear. It does not explicitly differentiate against sibling tools, but the creation intent is readily distinguishable from the mock-update and search siblings.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage when creating a new interface in a YApi project and gives practical guidance about login requirements and catId fallback behavior. However, it does not explicitly state when to prefer this tool over alternatives or mention any exclusions.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• yapi_update_advanced_mockB
  3.4/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full disclosure burden. It reveals the two moost critical behavioral traits — the operation overwrites the existing script ('覆盖保存') and requires login-session auth rather than a project token. It does not disclose response shape, validation behavior, or the effect of the enable/dryRun flags.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two short sentences with zero filler: the purpose is front-loaded and the auth constraint earns its place as essential operational context. Every word contributes to correct invocation.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a 5-parametr mutating tool with no annotations, no output schema, and 20% schema coverage, the definition is too sparse. The auth note is valuable, but an agent still cannot correctly interpret dryRun/enable or know what to expect in return.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is only 20% (only mockScript is described), and the tool description adds no parameter guidance whatsoever. dryRun, enable, projectId, and interfaceId remain undocumented in both schema and description, leaving the agent to guess their semantics.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description names a specific verb-resource pair: '覆盖保存高级 Mock 脚本' (overwrite-save the advanced Mock script). The qualifier '高级' (advanced) distinguishes it from siblings such as yapi_update_interface_mock and yapi_get_advanced_mock, though it does not explicitly name the alternative it is not.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The second sentence supplies concrete usage context: the official plugin API is not in the project token whitelist, so this tool must be called through login state. This tells an agent when this path is required and why token-based alternatives would fail, though it stops short of explicitly naming sibling alternatives.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• yapi_update_interface_mockB
  3.4/5.0
  Behavior2/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention that the update may overwrite existing mock data, that dryRun exists as a preview option, or what effects the update has on the interface. The '普通 Mock' scope note is useful but does not describe the operation's behavior.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single efficient sentence with no fluff, and its core scope statement is front-loaded. It is concise, though the brevity leaves out important behavioral and parameter context.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  With 6 parameters, no output schema, and no annotations, this description is not complete enough for an agent to call the tool confidently. It does not explain dryRun usage, response body type choices, or JSON Schema mode, making it under-specified for a mutation-style tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is only 17%, and the description adds no parameter meaning beyond the already-described resBody field. Parameters like dryRun, resBodyType, resBodyIsJsonSchema, interfaceId, and projectId remain unexplained by both schema and description.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific action ('更新') applied to a specific resource ('接口返回体文档（普通 Mock）'), and explicitly distinguishes this from advanced mock tooling by saying advanced scripts and expectations should use the corresponding tools. This clearly separates it from siblings like yapi_update_advanced_mock.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description tells the agent this is for ordinary Mock response body updates only, and that advanced scripts and expectations should go to other tools. It does not name those sibling tools explicitly, but the contrast is clear enough to guide selection.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• yapi_get_interface_mockA
  3.8/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations, the description carries the burden of disclosing behavior. It clearly says 读取 (read), indicating a read-only operation with no side effects, and specifies what is returned: res_body and mock URL. It does not detail errors or auth requirements, but for a simple read tool the core behavior is transparent.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single concise sentence, front-loads the main action and resource, and includes the clarifying parenthetical about res_body formats. Every part contributes useful information with no filler.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple read tool, it covers the main return values (res_body and mock URL) and the normal-mock distinction. However, it omits any explanation of projectId, does not describe the response structure in the absence of an output schema, and gives no explicit guidance on selecting this over yapi_get_advanced_mock.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, so the description must explain parameters. It only indirectly clarifies interfaceId via '接口的', but projectId is never explained. The description focuses on output rather than parameter meaning, leaving one of the two parameters essentially undocumented.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the operation (读取/read), the target resource (接口的 res_body and mock URL), and the content type (普通 Mock 文档 / JSON Schema). The word '普通' helps distinguish it from the sibling yapi_get_advanced_mock, making the tool's purpose unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage for reading normal mock data, and the sibling yapi_get_advanced_mock suggests an alternative for advanced mocks, but it never explicitly says 'use this when you need normal mock data' or 'not for advanced mock'. There is no direct when-to-use vs. when-not-to-use guidance.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• yapi_list_projectsA
  4.2/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations are provided, so the description carries the behavioral disclosure burden. It adds useful context about account-scoped visibility and the lack of a required project ID configuration. However, it does not describe the return format, pagination behavior, or how list results will be presented, leaving some behavioral ambiguity.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two short sentences with no redundant language. The primary function is front-loaded, followed by the key usage guidance. Every word earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple zero-parameter listing tool, the description covers the essential 'what' and 'when'. Since there is no output schema, explicitly stating that the result includes project IDs and how to consume the returned list would make it fully complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool has zero parameters and the input schema is empty with 100% coverage, so there are no parameter semantics to document. A baseline of 4 is appropriate because the description correctly adds nothing about parameters and no information is missing.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the action (列出/list), the resource (YApi 项目), and the scope (当前账号能看到的/visible to the current account). It also distinguishes itself from sibling tools, which focus on interfaces and mocks, by framing this as the first step when the project ID is unknown.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives explicit usage context: use this first when the project ID is unknown, and no YAPI_PROJECT_ID pre-configuration is required. It does not explicitly mention when not to use it or compare against specific sibling tools, so it is clear but not exhaustive.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• yapi_search_interfacesA
  4.2/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  No annotations exist, so the description bears the full burden. It discloses the search scope (current project), criteria (title/path/method), and implies a read-only operation via the verb 'search'. However, it does not disclose return format, pagination, or match semantics, which are meaningful gaps in an annotation-free context.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A single compact sentence that front-loads the action and resource, then appends the usage hint. Every clause earns its place; there is zero redundant phrasing.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Complete enough for a low-complexity 2-param tool: both parameters are schema-documented, the projectId/env-var fallback is consistent with the schema, and the description covers the search criteria. The main gap is the lack of any description of the return value, which matters since this tool exists to discover an interfaceId for downstream calls.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the baseline is 3. The description adds genuine value by specifying that the keyword searches across title, path, and method — clarifying which fields the keyword param actually matches, which the schema's generic '搜索关键字' does not convey.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  States a specific verb (search), resource (interfaces in the current YApi project), and search dimensions (title, path, method). The qualifier '不知道 interfaceId 时先用这个' differentiates it from the sibling tools, all of which operate on a specific known interface/mock — making this the discovery entry point.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Gives an explicit when-to-use condition: 'use this first when you don't know the interfaceId.' This clearly orients an agent toward the discovery workflow. It doesn't name specific alternatives to use once the ID is known, but the context is clear enough that exclusions are implicit.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.