Server Quality Checklist

Tool Scores

• get_itemA
  4.4/5.0
  Behavior5/5

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

  The description adds extensive behavior beyond readOnly/idempotent annotations: routing/refusal logic, terms-of-reuse semantics, empty-vs-absent fields, windowed text with line boundaries, offset past end behavior, and latency warning. No contradiction with annotations.

  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 verbose and tangentially structured, with convoluted phrasing about identifier routing and a phantom parameter. While informative, it would benefit from tighter organization and shorter sentences. It is not concise but not entirely wasteful.

  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 handles many edge cases and behaviors (ambiguous identifiers, reuse terms, empty fields, pagination, latency) making it largely complete for a complex read tool. However, the phantom parameter and lack of explicit return-value summary (though output schema exists) prevent a top score.

  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 the input schema already covers all parameters (100% coverage), the description adds context about identifier origin and routing, sections semantics, and text_offset windowing. However, it references a non-existent 'description_means' parameter, which could mislead the agent and detracts from clarity.

  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 function with a specific verb ('Read') and resource ('one record in full'), and distinguishes it from sibling search tools by requiring identifiers from search_inside/search_items and explaining archive routing. The title reinforces the purpose.

  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 implies usage after search tools and describes constraints on identifiers (refuses ambiguous/unminted strings), giving clear context. It doesn't explicitly list alternatives for exclusion, but the routing and identifier source make the intended use clear.

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

• search_insideA
  5/5.0
  Behavior5/5

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

  Discloses extensive behavioral context beyond the annotations: results are additive across archives with no total, page_number is null for archives without a leaf index, excerpt_kind distinguishes passages from page openings, ordering groups matches by excerpt type without ranking, and no match is ever dropped. Also explains the meaning of non_word_characters and the fan_out derivation. No contradiction with the readOnly/openWorld/idempotent annotations.

  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?

  Although lengthy, every sentence contributes unique value—covering result semantics, ordering, parameter behavior, and performance. The description is front-loaded with the core purpose and then systematically adds detail. No redundant restatement of schema or annotations.

  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?

  The description is exceptionally complete given the tool's complexity: it explains output semantics (per_source, page_number, excerpt_kind, found_by_query), inter-archive behavior, parameter interactions, edge cases like derived wordings, and performance expectations. The presence of an output schema does not reduce the need for this context, and it delivers.

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

  Parameters5/5

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

  Schema coverage is 100%, but the description adds significant meaning beyond the schema: it clarifies that 'fan_out' enables derived wordings and that 'per_source' names every wording sent, each match carries 'found_by_query', and 'max_excerpt_chars' and 'max_excerpts_per_match' multiply to form answer size. It also explains the query syntax and behavior for sentence queries.

  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?

  Opens with a specific verb+resource+scope statement: 'Search the machine-read text of every archive this server reads... and get one list of where a phrase was printed.' It clearly distinguishes from siblings by explicitly telling the user to 'Use search_items for a work by its title, its creator or its subject' because this tool reads page text and knows nothing of a catalogue.

  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?

  Provides explicit when-to-use and when-not-to-use guidance, naming the alternative tool (search_items) and explaining why a title query would fail here. Also details nuanced usage rules: how fan_out behaves, how results are combined across archives, and that answers take several seconds due to a request ceiling.

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

• search_itemsA
  5/5.0
  Behavior5/5

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

  Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: interleaving, per-archive sorting, date semantics, fan-out derivation, media_type vocabulary differences, per_source counts, and non-word handling. There is no contradiction with annotations.

  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?

  Although long, every sentence adds distinct value and no redundancy is apparent. The purpose is front-loaded in the first sentence, and subsequent paragraphs are organized by topic (sorting, counts, media_type, fan-out, alternatives). It is appropriately sized for the tool's complexity.

  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?

  The description is exceptionally complete for a tool with 9 parameters, an output schema, and complex cross-archive semantics. It covers edge cases, per-archive behaviors, counting rules, and even latency. It fully compensates for any structured-field gaps and leaves no major operational ambiguity.

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

  Parameters5/5

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

  Schema coverage is 100%, but the description adds significant meaning beyond the schema: it explains sort is applied per archive rather than across, media_type vocabularies are per-archive with absence behavior, fan_out triggers only when results are sparse, and year ranges are interpreted per archive. This goes far beyond the schema 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 opens with a specific verb and resource ('Search the catalogue of every archive this server reads, at the same time') and clearly distinguishes this tool from siblings by referencing get_item for reading records and search_inside for page-level phrases. It is unambiguous about the merged-list output and cross-archive scope.

  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 names alternatives: 'Use search_inside for a phrase printed on a page' and 'Read the record with get_item for what that record itself says.' It also provides usage context, such as latency, per-archive counts, and when the tool is or isn't appropriate for sentence-level queries.

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