Server Quality Checklist

Tool Scores

• yapi_create_interfaceB
  3.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write operation. The description adds a list of supported features but does not disclose additional behavioral traits such as permissions required, side effects, or idempotency. Since annotations cover the basic safety profile, the description provides marginal extra 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?

  The description is a single, front-loaded sentence with zero wasted words. It immediately states the primary action and lists the key supported facets. This is an excellent example of conciseness.

  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 21 parameters and 5 required ones, the description is extremely sparse. It does not highlight required fields, provide examples, or explain how to structure the request. While an output schema exists, the description lacks crucial orientation an agent needs to correctly invoke this complex tool. The minimalism leaves major gaps.

  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 100%, so every parameter has a description in the schema. The tool description lists categories (request parameters, body, response, status, tags) but does not add meaning to individual parameters beyond what the schema already documents. Baseline 3 is appropriate when the schema does the heavy lifting.

  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 clear verb ('创建' = create) and resource ('YApi 接口' = YApi interface), and lists supported aspects (request parameters, body, response, status, tags). It is unambiguous and distinct from sibling tools like yapi_update_interface, though it does not explicitly name alternatives.

  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 on when to use this tool versus alternatives. No mention of prerequisites, conditions that favor this over yapi_update_interface, or any exclusions. The description only states what it does, not when to use it.

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

• yapi_list_interfacesB
  3.4/5.0
  Behavior2/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. Beyond that, the description only restates the filtering capability already visible in the schema parameters. It does not disclose any side effects, limits, or behavioral nuances such as response ordering, pagination semantics, or potential performance considerations. With annotations absorbing the safety disclosure, the description adds almost no new behavioral 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, well-structured sentence that immediately conveys the tool's purpose and key capabilities. No filler, no redundancy, and the core function is front-loaded. It is appropriately sized for the tool's simplicity.

  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 read-only paginated list tool, the description combined with a full schema and an output schema covers everything an agent needs to invoke it correctly. The description implies the project scope via '项目下', and pagination/filter parameters are well-documented in the schema. No critical information is missing for a tool of this complexity.

  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?

  The schema covers 100% of parameters with descriptions, so the baseline is 3. The description mentions filtering by status or tag, which aligns with the 'status' and 'tag' parameters but adds no additional meaning beyond the schema. For pagination (page/limit) and projectId, the schema already provides adequate detail. The description does not compensate for any gaps, but none exist.

  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 clearly states a specific verb ('分页获取' = paginated fetch), a specific resource ('项目下的接口列表' = interface list under project), and mentions filtering by status or tag. This distinguishes it from tools like yapi_get_interface (single) and yapi_list_categories (categories), though it does not explicitly name siblings to differentiate. The project-level scope is clear and distinct from category-level listings.

  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 establishes a clear context: this is for paginated listing of interfaces under a project, with optional status/tag filters. However, it does not provide any explicit guidance on when to use this tool versus alternatives like yapi_list_category_interfaces or yapi_search_interface. No exclusions or alternative routing are mentioned, leaving some inference to the agent.

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

• yapi_create_categoryA
  3.6/5.0
  Behavior3/5

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

  The description is consistent with annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) and simply states a create operation. It does not contradict annotations but also adds no extra behavioral context such as side effects, permission requirements, or response details. The annotations already cover the basic safety profile, so a 3 is appropriate given the minimal additional disclosure.

  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, compact sentence with no filler or redundancy. It is fully front-loaded and gets straight to the point, demonstrating excellent conciseness for a simple create operation.

  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 create tool with a full input schema, required-field marking, and an output schema (as indicated by context signals), the description is adequate. It does not explain return values, but the presence of an output schema covers that. The main gap is the lack of usage guidance, but that is already scored separately. Overall, the description is nearly complete for its simplicity.

  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 100% — all three parameters (name, projectId, description) have individual descriptions. The tool description does not add any extra meaning beyond the schema, so the baseline of 3 applies.

  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 verb 'create' (创建) and the resource 'API category' (接口分类) within a project context. It is specific enough to distinguish from sibling tools like yapi_create_interface, leaving no ambiguity about what the tool does.

  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 does not provide any guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or explicit comparisons to sibling tools. The only context is the inherent nature of the tool name, which implies category creation, but no directed usage advice is given.

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

• yapi_list_categoriesA
  3.6/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to state it's a read operation. The description adds no extra behavioral context beyond the purpose (e.g., return format, pagination, or any side effects), but this is acceptable given the read-only nature and the existence of an output schema. It does not contradict annotations, so a 3 is appropriate.

  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, front-loaded sentence that states the purpose directly with zero unnecessary words. It efficiently conveys the core action and scope without any redundant context.

  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 list tool with one parameter and an existing output schema, the description is sufficient to understand what the tool does and how to use it. The only gap is the lack of usage guidance relative to siblings, but that is covered under the usage_guidelines dimension. The description is otherwise complete for an agent to call the tool correctly.

  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 100%, with the only parameter projectId fully documented in the schema. The description does not add any parameter-specific details beyond what the schema provides, so the baseline of 3 applies. The description's mention of '项目下' (under project) aligns with the projectId parameter but adds no new semantic value.

  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 verb (获取/get), the resource (接口分类列表/category list), and the scope (项目下/under project). It is distinct from siblings like yapi_list_category_interfaces (interfaces within a category) and yapi_list_interfaces (interfaces), so an agent can easily differentiate them without opening schemas.

  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 provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or specific conditions that would select this tool over siblings such as yapi_list_category_interfaces or yapi_search_interface. The usage is only implied by the tool name and description, which is insufficient for an agent deciding between similar tools.

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

• yapi_update_interfaceA
  3.9/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds the key behavioral detail that only provided fields are updated and others remain unchanged, which goes beyond the annotations. No contradiction.

  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?

  Single, focused sentence that front-loads the action and the key usage rule. No filler, appropriately concise.

  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 tool with 21 parameters and complex nested schema, the description is minimal. It relies on the comprehensive schema for parameter details. It doesn't mention prerequisites like needing the existing interface state, but the required id and the general update guidance are adequate for basic use. However, it could offer more guidance on handling groups of related parameters (e.g., requestBody vs requestForm).

  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 coverage is 100%, so each parameter has a description in the schema. The description adds a general principle for using parameters (only pass fields to modify) but does not add per-parameter specifics, so it meets the baseline of 3.

  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 '按接口 ID 更新 YApi 接口' (update YApi interface by interface ID), a clear verb+resource. It is distinct from sibling tools like create, get, list, and search, so an agent can distinguish it.

  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?

  Gives the guideline '只传需要修改的字段' (only pass fields to modify), which clarifies partial update behavior. However, it does not explicitly mention when to use this tool over alternatives, such as creating a new interface or fetching one, leaving some inference to the agent.

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

• yapi_list_category_interfacesA
  4/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true, covering safety. The description adds that the operation is paginated ('分页获取') and supports filtering by status or tag, which are behavioral traits beyond the schema. It does not go into details like auth or error behavior, but with read-only annotations, the bar is lower, and the pagination disclosure is valuable for an agent to manage paging.

  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, front-loaded sentence that states the core action and key filters. Every word earns its place; there is no redundancy or filler.

  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?

  Given that an output schema exists (so return structure is already defined), a required parameter is specified in the schema, and readOnlyHint is present, the description covers the essential operational context: it is a paginated, category-scoped interface list with optional filters. It lacks usage guidance but that is handled in another dimension; for a list tool, this is adequately complete.

  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 coverage is 100%, and each parameter already has a description. The description mentions filtering by status or tag, which essentially repeats the schema. It adds minimal new meaning, such as grouping the filters, but does not explain value formats or relationships beyond what the schema provides. This meets the baseline for high schema coverage.

  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 tool's purpose: a paginated interface list scoped to a specific category, with optional status or tag filters. It names the resource (interfaces), the scope (category), and the operation (paged retrieval), which distinguishes it from sibling tools like yapi_list_interfaces (which likely lists all interfaces) and yapi_search_interface (which searches by keyword).

  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 context (it is for interfaces under a category), but it does not explicitly mention when to use this tool versus alternatives such as yapi_list_interfaces or yapi_search_interface. There are no 'when not to use' statements or references to sibling tools, leaving the selection partially to inference.

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

• yapi_get_interfaceA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds value by disclosing the optional `full=true` behavior that returns raw YApi data instead of the standard subset, which is a meaningful behavioral distinction beyond the schema. It does not contradict annotations and provides useful 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?

  The description is a single, front-loaded sentence that immediately states the core function and the optional modifier. There is zero redundancy, and every phrase earns its place. It is short while still being informative.

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

  Completeness5/5

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

  Given the tool is a simple getter with a rich output schema (not needing return-type explanations), the description fully covers what an agent needs: the input (ID) and the two modes (standard vs full). No prerequisites, side effects, or hidden behaviors are left undisclosed, and annotations cover the read-only guarantee.

  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 100%, and both parameters are already documented with descriptions. The tool description essentially restates what the schema says (ID for lookup, full for raw data) without adding syntax, formatting, or edge-case details. Baseline 3 applies since the schema carries the semantic weight.

  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 verb ('get') and resource ('interface') and enumerates exactly what is returned (method, path, description, input/output parameters). It also mentions the optional full data flag, making it clear this is a targeted retrieval tool. The '根据接口 ID' clause distinguishes it from list/search siblings by requiring a specific ID.

  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 a specific interface ID is already known, but it does not explicitly state when to use this over siblings like yapi_list_interfaces or yapi_search_interface. No exclusions or alternatives are named, leaving the agent to infer context from the sibling list. This is the weakest area.

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

• yapi_get_projectA
  4.3/5.0
  Behavior4/5

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

  The annotations already declare readOnlyHint=true, so the agent knows it's a safe read. The description adds value beyond that by disclosing the specific fields returned (base path, environment, members). No contradictions with annotations exist, and it provides useful context about the operation's output scope.

  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 that front-loads the core purpose and details. Every word carries meaning; there is no fluff or redundancy. This is an ideal length for a simple GET tool.

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

  Completeness5/5

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

  Given the tool's simplicity (one parameter, no nested objects) and the existence of an output schema (which reduces the need to explain return values), the description covers everything an agent needs: the resource type and the key fields it can expect. No critical information is missing.

  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 100%—the parameter 'id' already has a description ('项目 ID'). The tool description does not add any additional meaning about the parameter beyond what the schema provides. Per guidelines, when coverage is high, the baseline of 3 is appropriate.

  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 verb ('获取' = get) and resource ('项目详情' = project details), and lists the exact information returned (base path, environment, members). This clearly distinguishes it from sibling tools that deal with interfaces/categories, so an agent can select it without ambiguity.

  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 makes the tool's purpose unambiguous: retrieve project-level details. While it doesn't explicitly state when not to use it, the specificity (base path, environment, members) implies usage when those are needed, and sibling tools are clearly for different resources (interfaces, categories). No exclusions are given, but the context is clear enough.

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

• yapi_search_interfaceA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, covering the read-only and non-cacheable nature. The description adds specific behavioral details beyond annotations: it searches across title, path, and HTTP method, and is case-insensitive. This provides the agent with meaningful search semantics that annotations do not convey, without contradiction.

  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, efficient sentence that front-loads the purpose and includes all necessary scope and behavior (search criteria and case-insensitivity). There is no redundancy or filler; every clause contributes value.

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

  Completeness5/5

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

  For a simple search tool with two required parameters and an output schema, the description covers the essential behavioral aspects: what is searched, how, and the case-insensitivity. The output schema presumably details return structure, so the description need not elaborate. No critical information is missing for an agent to invoke it correctly.

  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 coverage is 100%, and the schema already describes both parameters with type and examples (e.g., keyword: '活动详情或 /order/list'). The description does not add additional semantic meaning beyond what the schema provides; it neither enhances nor repeats parameter details. Given the high schema coverage, the baseline of 3 is appropriate.

  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 (search), the resource (YApi interfaces within a project), and the criteria (by title, path, or HTTP method). It also notes case-insensitivity, distinguishing it from listing tools like yapi_list_interfaces that simply enumerate interfaces. The verb-resource-criteria combination is specific and unambiguous.

  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 implies usage: use this when you need to find an interface by keyword rather than listing all interfaces. It gives concrete example keywords ('活动详情' or '/order/list') that suggest appropriate search inputs. However, it does not explicitly state when not to use it (e.g., when you already have an interface ID) or mention alternatives. The context is clear, but exclusions are absent.

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