Server Quality Checklist

Tool Scores

• get_batchA
  3.5/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true, and the description matches (batch get). The description adds non-obvious behavioral details: automatic deduplication of referenced schemas into a shared appendix, a hard limit of 40 keys after dedup, and the mixed key format. This exceeds the baseline provided by the readOnly hint.

  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 sentences, each adds distinct value: the first states the core operation and dedup behavior; the second specifies key types, source, and limits. No fluff, efficient front-loading, and the most critical constraint (≤40) is highlighted.

  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?

  The output schema covers return format, so that's adequate. The description covers the key parameter well but leaves include_refs unexplained. Given the tool is a batch utility with siblings, the missing parameter explanation and the lack of explicit when-to-use guidance make it only partially complete.

  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 for both parameters. It thoroughly explains 'keys' (format, source, dedup, cap) but completely omits 'include_refs'. The missing semantics for a boolean parameter that likely controls whether the shared appendix is included is a significant gap.

  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 purpose: batch retrieval of endpoint details and schema property tables, with referenced schemas integrated into a shared appendix. It distinguishes itself from singular siblings like get_endpoint and get_schema by explicitly being a batch operation, though it doesn't name alternatives directly.

  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 provides guidance on where keys come from ('list_endpoints / select'), implying the intended use case. However, it doesn't explicitly state when to use this tool instead of get_endpoint or get_schema, nor does it describe conditions for not using it. The batch nature is evident but the routing logic is left implicit.

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

• list_endpointsA
  3.9/5.0
  Behavior3/5

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

  The annotation only declares readOnlyHint, which is about side effects. The description adds that the tool returns a table of endpoints, but does not disclose any other behavioral traits such as performance, pagination, or filtering behavior. It goes slightly beyond the annotation but not significantly.

  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 main action ('list all API endpoints') and then provides context for sibling tools. There is no unnecessary detail, and it is efficiently structured.

  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?

  The description gives enough context for a simple list tool: it states what it does and when to use it. However, it omits any explanation of the optional 'tag' parameter, which could be relevant for filtering. This slight gap prevents a perfect score, but overall the tool's purpose and usage are well covered.

  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?

  The only parameter 'tag' is completely undocumented in both the schema and the description. The description does not mention the parameter at all, providing no meaning or usage guidance for it. With 0% schema coverage and no description mention, parameter semantics are critically lacking.

  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: it lists all API endpoints with method/path/summary table. It distinguishes itself from sibling tools by positioning it as the first step and explicitly pointing to get_endpoint/get_schema for details, which helps an agent select it appropriately.

  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 explicitly states when to use this tool (as the first step for an API overview) and when to use alternatives (when details are needed, use get_endpoint/get_schema). This provides clear guidance on tool selection relative to siblings.

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

• get_schemaA
  4.1/5.0
  Behavior4/5

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

  The readOnlyHint=true annotation already declares the safety profile, and the description is fully consistent with... annotation contradiction absent. The description adds value by disclosing what the tool RETURNS (property table, nested drill keys) and documenting the data-flow prerequisite (input derived from get_endpoint output). For a read-only tool whose annotation covers the risk profile, this is solid supplementary detail. No contradiction between '获取' and readOnlyHint=true.

  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 sentences with zero filler. The first defines purpose and output; the second resolves the input sourcing. No repetition of what annotations or schema already provide — it's tight, information-dense, and every word earns its place. This is the model of conciseness.

  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 low-complexity tool (1 param, no enums, no nested objects) with an output schema handling return-type doc and annotations covering the read-only profile, the description is nearly complete. It establishes the retrieval flow and content. The main gap is minor: it doesn't address the arrow-prefix format ambiguity or explicitly suggest downstream actions (e.g., passing a schema to select/get_batch).

  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?

  Although schema description coverage is 0%, the description compensates by explaining the single parameter's provenance — 'schema 名从 get_endpoint 输出的 `→ get_schema(Name)` 中获得'. For a one-argument tool, this effectively documents what 'name' is and where to find it. The only shortfall: it doesn't clarify whether the '→' arrow is part of the literal string value.

  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 verb+resource — '获取单个 schema 的属性表与嵌套下钻键' (get a single schema's property table and nested drill-down keys) — going beyond a tautology by specifying what is retrieved. The '单个 schema' scope distinguishes it from list-like siblings without naming them. It would earn a 5 with explicit sibling differentiation, but the core purpose is unambiguous on its own.

  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 explicitly tells the agent where to get the `name` parameter: 'schema 名从 get_endpoint 输出的 `→ get_schema(Name)` 中获得' — establishing a call sequence and naming a sibling tool (get_endpoint). This is concrete, actionable guidance for the critical input-sourcing question. However, it doesn't mention when NOT to use this tool or contrast with select/get_batch, leaving a small but real gap.

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

• get_endpointA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, and the description adds the missing behavioral traits: case-insensitive matching and the dependency on list_endpoints for key discovery. It doesn't describe rate limits or error behavior, but these are minor for a read-only detail fetcher.

  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?

  One compact sentence starts with the core action, uses a parenthetical for content, then adds two focused notes. No filler or redundant restatement of the tool name.

  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 two simple parameters, an output schema, and a read-only annotation, the description covers the main behavior and parameter provenance. It omits only an explicit alternative-selection rule, which is a minor gap for a low-complexity tool.

  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?

  With 0% schema description coverage, the description partially compensates by explaining the method is case-insensitive and that keys originate from list_endpoints. It does not spell out the path format, but the key-source hint is actionable for both parameters.

  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 extracts markdown details for a single endpoint and enumerates the content (auth, params, request body, response). It distinguishes from siblings by focusing on 'single endpoint' and referencing list_endpoints, without needing the schema to understand scope.

  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?

  It provides explicit usage context: keys should come from list_endpoints, and method matching is case-insensitive. It does not explicitly list when to prefer get_endpoint over get_schema or select, so sibling routing is left partially implicit.

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

• selectA
  4.4/5.0
  Behavior4/5

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

  The description adds behavioral details beyond the readOnlyHint annotation by explaining pattern matching rules (case-insensitive, wildcard method) and the behavior on zero matches (returns available condition hints). It also clarifies that this tool does not return details itself, which is a significant behavioral trait. Some aspects like error handling are not mentioned, but the provided information is substantive.

  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 concise and well-structured. It presents the main purpose first, then explains the pattern format, the zero-match hint behavior, and the follow-up action with get_batch. No unnecessary information is included.

  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 (4 optional parameters, no required), the description covers the essential aspects: what it does, how to use it, and what to do next. It does not explain the output schema, but since an output schema exists, that is acceptable per the criteria. The description is complete enough for an agent to understand the tool's role and usage.

  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?

  With zero schema description coverage, the description compensates by explaining that patterns are glob patterns with specific format (e.g., 'GET /v1/*'), and that tag and security are used for filtering. It gives enough meaning for the parameters, though it could elaborate more on tag and security specifics. Overall, it adds meaningful semantics to the input 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 clearly states that the tool filters and selects endpoint keys and schema names using glob patterns and authentication/tag criteria. It specifies the resource (endpoints and schemas) and the action (filter/select) with sufficient detail.

  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 guidance on when to use this tool versus get_batch by stating that after selection, get_batch should be used for details. It also explains the pattern format and the behavior on zero matches, which aids in troubleshooting. However, it does not explicitly contrast with list_endpoints or get_endpoint, but the filtering purpose is implied.

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