Server Quality Checklist

Tool Scores

• list_kindsA
  4.5/5.0
  Behavior4/5

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

  Annotations already cover read-only/idempotent behavior. The description adds meaningful context beyond that: kinds derive from the site's cross-reference index, vary per site, and the return shape for both markdown and JSON is fully documented. It does not contradict any annotation.

  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 well-structured: a concise opening definition, a brief explanatory paragraph about site variability and usage, then clearly formatted Args and Returns sections. Every sentence adds value, and there is no unnecessary verbosity.

  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 tool is simple and well-covered: annotations declare safety, the description details what kinds are, how they relate to sites, how to use the output with `search`, and the exact return formats for both markdown and JSON. This is complete for an agent to select and invoke correctly.

  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 the schema already documents both parameters. The description's Args section restates the same information (site alias, response_format options) without adding new meaning. This meets the baseline for high schema coverage.

  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 opening sentence states a specific action ('List') and resource ('kinds of entries') with the scope of a Verso site and counts. It clearly distinguishes itself from siblings by explaining that the returned kind values are used to filter `search`, and it references `list_sites` for site aliases.

  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 tells the agent when to use this tool: to obtain `kind` values for filtering `search`. It also explains that kinds vary per site, implying the tool is needed to discover them dynamically. This is an explicit use case with a named alternative (`search`).

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

• fetch_pageA
  4.6/5.0
  Behavior5/5

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

  The description discloses many behavioral traits: converts HTML to Markdown, anchor handling, relative vs absolute resolution, rejection of off-site URLs and path traversal, truncation at ~200KB, and different return formats. It also states 'Read-only', matching the annotations. This adds significant context beyond the readOnly/destructive hints, such as error behavior and metadata in json mode.

  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 structured with clear sections (Args, Returns, Examples) and starts with a one-sentence summary. It is longer than minimal but every part adds value: parameter clarifications, return format, examples, and constraints. No filler or redundancy. Slightly verbose but justified by 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 fully covers the tool's behavior: inputs, outputs, error handling, truncation, edge cases, and examples. It even mentions integration with search results and list_sites. Even though the input schema includes an output schema reference, the description explains the return shapes in detail, making the tool self-contained. Sibling context is well integrated.

  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: it explains that site is used only for relative paths and ignored for absolute URLs, that anchors focus on a section, and that url_or_path can be an absolute URL on a configured site or a site-relative path. It also clarifies the response_format options and their payloads, exceeding what the schema states.

  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: 'Fetch a page from a Verso documentation site and return it as Markdown.' It clearly distinguishes from siblings by explaining it fetches page content, while list_sites lists sites, list_kinds lists kinds, and search finds content. The scope (single page/section with anchor) is also stated.

  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 instructs when to use the tool: to read a chapter, a single entry via #anchor, or resolve a search hit. It references list_sites for the site alias and search for passing the url field, showing context. It does not explicitly say 'when not to use' but the URL constraints and examples imply alternatives. This is clear guidance, though not as explicit as naming an alternative tool.

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

• list_sitesA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds significant behavioral detail: it specifies the exact return format for both markdown and JSON, including the structure of the JSON object. It also discloses that sites are configured via an environment variable, which is context not available in the 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 well-structured with a clear intent, relationship to siblings, configuration note, and Args/Returns sections. Every sentence contributes essential information, and it is front-loaded with the primary purpose.

  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?

  For a simple listing tool, the description is fully self-sufficient: it covers purpose, usage, configuration, parameters, and return formats. The relationship to sibling tools is explicitly stated, and the presence of an output schema further enriches the context. No gaps remain for the agent to guess.

  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 fully documents the `response_format` parameter with an enum and default. The description goes beyond by explaining concretely what each format returns (line-by-line markdown vs. structured JSON with a default site and sites list), helping the agent choose the right format. This adds value beyond the schema's generic description.

  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 lists Verso documentation sites the server is configured to serve, using the verb 'List' and a specific resource. It also distinguishes itself from siblings by explaining how each site's alias is used as the `site` argument in `search`, `list_kinds`, and `fetch_page`.

  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 explains that the returned aliases should be passed to sibling tools, providing concrete usage instructions. It also mentions configuration via `VERSO_MCP_SITES`, giving the agent context for how sites are populated and when to expect them.

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

• searchA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses that results are 'ranked by match quality and paginated,' and explains the behavior for pagination via offset and the hint to re-call with a higher offset. It also details return formats and what fields are included.

  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 well-structured with clear sections (main description, Args, Returns, Examples). Every sentence contributes useful information, and the use of labeled sections improves readability without unnecessary fluff.

  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 complexity (6 parameters, multiple response formats, pagination) and rich schema/annotations, the description fully covers all aspects: what it searches, how to filter, pagination behavior, return formats, and examples. No significant gaps remain.

  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 covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds value through concrete examples mapping natural language ('Find the simp tactic') to parameter combinations, which helps the agent select correct arguments. However, the Args section itself largely paraphrases the 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 states a specific verb and resource: 'Search a Verso documentation site's cross-reference index by name.' It clearly distinguishes itself from sibling tools by noting that it does not search free text inside pages, for which `fetch_page` is the intended alternative.

  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 gives usage context: 'Matches entry names and display names (not free text inside pages — use `fetch_page` to read a page).' It also references sibling tools `list_sites` and `list_kinds` for valid site and kind values, and provides examples of when to use the tool.

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