Server Quality Checklist

Tool Scores

• get_itemB
  3.4/5.0
  Behavior2/5

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

  The description includes extensive behavioral details, but several of them are false: it mentions 'date', 'date_stated', 'date_code', and 'year' as section options, yet the schema's enum only allows 'basic', 'citations', 'resources', and 'full_metadata'. This actively misleads an agent about the tool's behavior, which is worse than omitting details. The readOnlyHint and idempotentHint annotations are accurate, but the description's incorrect claims undermine transparency.

  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 organized with the purpose first, then identifier details, section explanations, and pagination. However, a significant portion is devoted to explaining 'date', 'date_stated', 'date_code', and 'year'—all of which are not valid section values. This makes the description unnecessarily long and misleading, though the structure itself is logical.

  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 description covers many important aspects: identifier format, pagination, and the purpose of each valid section. With an output schema present, it need not describe return values. However, it omits any mention of the actual allowed section enum and instead lists invalid options, leaving an agent with inaccurate information about how to use the tool. This is a significant completeness gap.

  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?

  The input schema already describes all four parameters with 100% coverage, giving a baseline of 3. The description does add useful semantics for 'identifier' (slash format) and 'offset' (pagination), but it incorrectly lists non-existent section values, which would cause an agent to pass invalid inputs. This misinformation cancels out the added value and makes the description a net negative for parameter understanding.

  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 begins with 'Read one Library of Congress record by its identifier', clearly stating the verb, resource, and scope. It also distinguishes itself from sibling tools by noting that the identifier is 'as returned by search_items or search_newspapers', making the tool's purpose unmistakable.

  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 context on when to use the tool: after obtaining an identifier from search tools. It also explains pagination ('call again with offset set to it') and section options. However, it does not explicitly state when not to use this tool or compare it against alternatives like list_collections, so it falls short of a 5.

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

• search_newspapersA
  4.8/5.0
  Behavior5/5

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

  Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds substantial behavioral context: quote semantics vary, 'total' counts pages not occurrences, unmatched filters are silently dropped, and the page_opening excerpt quirk is explained. 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.

  Conciseness4/5

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

  The description is front-loaded with the core purpose and then builds with related behavioral details. It is long, but most sentences earn their place; minor awkwardness like 'and they page' prevents a perfect score.

  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 9-parameter search tool with output schema and annotations, the description is remarkably complete. It covers pagination, filter behavior, return fields, excerpt types, result-count semantics, and when to use an alternative tool, leaving little unaddressed.

  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 baseline is 3. The description adds meaning beyond the schema by explaining quote behavior, the meaning of 'location', 'publication', 'year_from/year_to', and the semantics of 'total' and pagination, going beyond the raw parameter 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 uses a specific verb and resource: 'Search the text inside digitised American newspaper pages held by the Library of Congress.' It clearly distinguishes from siblings by explaining this is full-text search of OCR content, and explicitly contrasts with 'search_items' for title/creator/subject searches.

  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 guidance: full-text newspaper search when the phrase may not appear in catalog records, and 'Use search_items instead when looking for a work by its title, creator or subject.' It also gives practical guidance on double-quote behavior, pagination, and filter usage.

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

• list_collectionsA
  4.9/5.0
  Behavior5/5

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

  The description adds substantial behavioral context that the annotations do not cover. It explains the meaning of collection_filter, searchable_media_types, and the important distinction that 'item_count' is 'the size of the corpus rather than the number of rows here'. It also clarifies that empty searchable_media_types gathers things like web archives that the catalogue search does not divide into. This enriches the agent's understanding beyond the readOnly/idempotent hints.

  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 longer than average but every sentence serves a purpose: it defines the resource, explains when to use it, clarifies field semantics, and distinguishes row count from item_count. The information is front-loaded with the core action, followed by relevant detail. No redundancy or filler exists, making it as concise as the content permits.

  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 moderate complexity, the output schema, and strong annotations, the description is fully complete. It explains the relationship to search_items, clarifies the meaning of output fields like collection_filter and item_count, and acknowledges edge cases like empty searchable_media_types. The description preempts likely misunderstandings and gives the agent all necessary context to invoke the tool correctly.

  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 input schema has 100% description coverage for all four parameters, so the baseline is 3. The description adds extra meaning for 'searchable_only' by explaining the condition in context: 'A collection whose searchable_media_types is empty... set searchable_only to leave those out.' This goes beyond the schema's wording and helps clarify the parameter's practical intent. However, the description does not add meaning for page, limit, or max_description_chars beyond what the schema already states, so it does not earn a 5.

  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 'List the digital collections of the Library of Congress', using a specific verb and resource. It then clarifies the concept of a 'collection' as 'bodies of material a curator chose, described and published together', and distinguishes it from sibling search tools by stating 'Use it to see what is there before searching, since a collection names a corpus that a query would have to guess at.' This clearly differentiates it from find/search operations.

  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 advises when to use the tool: 'Use it to see what is there before searching', and explains how it relates to sibling tools: 'collection_filter on each row is the wording search_items takes as its collection argument'. It also gives conditional guidance for searchable_only, explaining that collections with empty searchable_media_types are not searchable and how to exclude them. This goes beyond generic statements and provides concrete usage context.

  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?

  Despite having annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description delivers significant additional behavioral context: filter fallback behavior, online_only default, the distinction between records and collections, and how identifiers work. It also explicitly states what the tool does NOT do (does not read text-inside-scans), which is valuable. No contradictions 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?

  The description is long but every sentence earns its place by adding unique, non-redundant behavioral detail. It is front-loaded with the core purpose and then systematically addresses caveats, alternatives, and edge cases. No fluff or repetition of schema.

  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 parameter count (12) and presence of an output schema, the description covers essential context: required media_type, exact filter terms, fallback filtering, digitized-copy default, and how to interpret collection rows. It also references sibling tools appropriately. The description is complete enough for an agent to use the tool effectively without surprise.

  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?

  The description enriches schema understanding with practical semantics: media_type required due to separate catalogues, filters must use exact Library vocabulary, behavior when a filter matches nothing, and the meaning of online_only. It also clarifies that rows with is_collection have null identifier and use source_url, going beyond the basic 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 clearly states it searches the Library of Congress catalogue with a specific list of material types, and explicitly distinguishes itself from sibling search_newspapers by noting it does not read text inside scans. The verb 'search' plus resource 'Library of Congress catalogue' and scope makes the purpose unmistakable.

  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 guidance on when to use this tool vs search_newspapers, explains why media_type is required, and details special behaviors like filter matching (or being dropped) and online_only default. It even instructs users on how to handle collection rows versus record rows, leaving little ambiguity about usage.

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