Server Quality Checklist

Tool Scores

• opds_browseB
  3.2/5.0
  Behavior3/5

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

  With no annotations, the description is the sole source of behavioral info. It explains the output structure (navigation links, entries with links) and the input format (URL, auth). However, it does not disclose error behavior, pagination, rate limits, or side effects. The description adds marginal value beyond what the input schema already conveys.

  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 a single sentence that efficiently conveys the core functionality and output. However, it is somewhat long and could be split for readability. It is not overly verbose, so it earns a 4.

  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 the complexity of the tool (no output schema, no annotations, moderate parameter count), the description covers the return values but lacks details on error handling, pagination limits, or authentication failure scenarios. It is sufficient for basic understanding but not fully 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 description coverage is 100%, so the description does not need to add parameter details. However, it adds no additional context beyond the schema (e.g., clarifying when url is required). The baseline of 3 is appropriate since the schema already explains all three parameters.

  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 fetches an OPDS catalog document and returns navigation links and entries. It specifies the document types and formats, aligning well with the title. However, it does not explicitly differentiate from sibling tools like opds_search or opds_download, though the purpose is distinct enough given the context.

  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, nor does it mention prerequisites, authentication requirements beyond the schema, or scenarios where it should not be used. This lack of usage direction is a significant gap.

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

• opds_get_entryA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description shoulders the transparency burden. It explains what the tool does (fetches and returns details) but omits failure modes, auth error behavior, or read-only nature beyond what's implied.

  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 front-loads the action ('Fetches') and efficiently conveys key details without wasted words.

  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 simplicity of the tool (3 parameters, no output schema), the description adequately covers what is fetched and the typical source of the URL. It could mention error handling but is largely complete for a straightforward fetch.

  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 baseline is 3. The description adds no extra parameter meaning beyond what the schema already provides—it essentially repeats the schema's parameter comments.

  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 fetches a single OPDS entry document with full details and acquisition links, distinctly separating it from siblings like opds_browse, opds_download, and opds_search.

  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 mentions the typical use case ('URL found in an entry's rel="alternate" link') but does not explicitly compare with siblings or provide when-not-to-use guidance. Still, context is clear.

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

• opds_downloadA
  4.1/5.0
  Behavior3/5

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

  No annotations provided, so description carries full burden. Describes download destination (temp dir or configurable) and return value. Lacks details on failure behavior, overwrite policy, or file extension handling.

  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, front-loaded with main action, no redundancy. Efficiently conveys purpose and configuration option.

  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 no output schema, the description clearly states return value (saved file path) and destination. Low-complexity tool is fully specified for agent use.

  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% with descriptions for all 4 parameters. Description adds context about URL origin but no parameter-specific guidance beyond 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 it downloads a file from an OPDS acquisition link to a local directory and returns the path. It distinguishes from siblings (opds_browse, opds_search, opds_get_entry) which handle metadata discovery.

  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?

  Explicitly specifies when to use: after obtaining an acquisition link from opds_browse/opds_search/opds_get_entry. Does not include exclusions or alternatives, but siblings naturally cover different operations.

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

• opds_searchA
  4.4/5.0
  Behavior4/5

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

  No annotations provided, so description carries full burden. Discloses that it discovers OpenSearch description and returns matching entries, similar to opds_browse. Does not mention safety, but for a search tool, read-only inference is reasonable.

  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, front-loaded with the action, no unnecessary words. Every sentence adds value.

  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?

  No output schema, but description references return format via 'same way opds_browse does', which helps if that tool is known. Could mention pagination or error handling, but overall adequate for a search tool with 4 parameters.

  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%, but description adds meaning by explaining the URL parameter's two possible forms (feed root or OpenSearch document) and that query is free-text. Auth parameters are repeated without additional context.

  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 searches an OPDS catalog, specifies the resource and action, and distinguishes it from siblings by mention of 'same way opds_browse does'.

  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?

  Provides context on when to use (searching an OPDS catalog) and how to specify the URL (root feed or OpenSearch document). Implicitly excludes browsing (sibling opds_browse) but lacks explicit when-not guidance.

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