Server Quality Checklist

Tool Scores

• export_openapiA
  3.6/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 mentions the important constraint about using summary mode before imports and hints at context-saving benefits, but doesn't describe authentication requirements, rate limits, error conditions, or what the exported data looks like. For a tool with no annotations, this leaves significant behavioral aspects undocumented.

  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 appropriately concise with two sentences. The first states the purpose, the second provides important usage guidance. Both sentences earn their place by adding value. However, the structure could be slightly improved by front-loading the purpose more explicitly.

  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?

  Given no annotations, no output schema, and 4 parameters, the description provides adequate purpose and usage guidance but lacks details about authentication, error handling, rate limits, and output format. For a tool that exports potentially complex data, more context about what gets returned would be helpful, though the schema coverage is excellent.

  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?

  With 100% schema description coverage, the schema already documents all 4 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions 'summary 模式' (summary mode) which aligns with the 'mode' parameter, but provides no additional semantic context about parameters beyond what the schema already states.

  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 the tool's purpose: '从 Apifox 项目导出接口信息' (export interface information from an Apifox project). It specifies the resource (Apifox project interfaces) and verb (export), but doesn't explicitly differentiate from its sibling 'import_openapi' beyond the obvious export/import distinction.

  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 provides clear usage guidance: '在导入新接口前，务必先使用 summary 模式查看现有目录结构和接口列表，以便将新接口放入合适的目录中' (before importing new interfaces, use summary mode to view existing directory structure and interface list). This gives a specific when-to-use scenario and recommends summary mode for context-saving. However, it doesn't explicitly state when NOT to use this tool or alternatives beyond the sibling import tool.

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

• import_openapiA
  4.4/5.0
  Behavior4/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 effectively describes key behavioral traits: the tool performs a write operation (importing), mentions safety mechanisms like batch importing to avoid large-scale errors, and details how 'markDeprecatedEndpoints' and 'confirmHighDeprecation' options work as safeguards. It doesn't cover all potential behavioral aspects like error handling or performance limits, but provides substantial context beyond basic functionality.

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

  Conciseness3/5

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

  The description is appropriately front-loaded with the core purpose, but the best practices section is quite detailed (multiple bullet points with explanations). While all content is relevant, it could be more concise; some explanations (like the benefits of batch importing) are somewhat verbose. The structure is logical but not maximally efficient.

  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 the tool's complexity (import operation with multiple behavioral options), no annotations, and no output schema, the description does a good job of providing context. It covers the core purpose, usage guidelines, key behavioral traits, and parameter semantics. However, it lacks details on error cases, response format, or authentication requirements, leaving some gaps for a tool of this nature.

  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 schema description coverage is 100%, so the baseline is 3. The description adds meaningful context about parameters: it explains the purpose of 'markDeprecatedEndpoints' in practice (recommending its use and detailing what it does), and implicitly relates to 'spec' by discussing batch importing strategies. While it doesn't detail every parameter, it enhances understanding of key options beyond the schema's technical descriptions.

  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: '将 OpenAPI/Swagger 规范导入到 Apifox 项目' (import OpenAPI/Swagger specifications into Apifox projects). It specifies supported formats (OpenAPI 3.0/3.1, Swagger 2.0) and distinguishes from its sibling 'export_openapi' by being the import counterpart. The verb '导入' (import) with resource 'Apifox 接口文档' (Apifox API documentation) 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 Guidelines5/5

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

  The description provides explicit usage guidelines with a '最佳实践' (best practices) section that details when and how to use the tool effectively. It recommends batch importing by module, explains the benefits of this approach, and mentions specific configuration options like 'markDeprecatedEndpoints: true'. While it doesn't explicitly mention alternatives, the guidelines are comprehensive for proper usage.

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