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

The description discloses the critical behavioral rule that destructive operations require confirm:true and points to safety classification in read_docs. With only openWorldHint=false in annotations (which does not describe operation safety or side effects), the description carries the disclosure burden but covers only the destructive-confirmation aspect, not return behavior or general side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Three sentences with no redundancy: purpose, workflow, and safety caveat are packed tightly. The most important information is front-loaded, and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a generic dispatch tool with no output schema, the description directs agents to read_docs for full schema, example, and safety, covering most missing context. It does not describe what the tool returns, but the read_docs pointer compensates for the most critical gaps in a multi-step discovery flow.

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

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

Schema coverage is 100%, so all three parameters are already described structurally. The description adds operational context (operation names come from search_docs; confirm applies to destructive operations) but does not elaborate argument shape beyond the schema, which is acceptable given full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States it executes API operations by name, a clear verb-resource pair. References the search_docs → read_docs → execute flow, which distinguishes it from discovery/reading siblings, though the term 'operation' remains somewhat generic without a concrete example in the description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit workflow: discover with search_docs, then read_docs for full schema/example/safety classification, then execute. The destructive-operation confirm:true requirement also signals when caution is needed. It does not list explicit conditions for when not to use the tool, but the sequencing is clear enough.

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

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

The annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description needs to add little here. It adds context about the tool returning reference content including authentication and safety details, which is helpful but describes the payload rather than behavioral traits like rate limits or response format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

A single efficiently worded sentence that front-loads the verb and resource, then packs the parameter semantics, then closes with the alternative page type. Zero filler and every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter, read-only tool with rich annotations and no output schema, the description is largely sufficient: it covers purpose, the accepted input values, and the nature of the content returned. Minor gaps remain, such as what the return format looks like and how guide pages are addressed, but nothing critical blocks correct invocation.

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

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

With 0% schema description coverage, the description must compensate, and it does: 'by tool name, or a docs-site guide page' explains what values the single 'page' parameter accepts. It could go further by specifying expected format or how tool names are distinguished from guide page names, but for a one-parameter tool this is meaningful added semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Read) and resource (an operation's full reference or a docs-site guide page), which is clear and concrete. It distinguishes well from the siblings by implication — reading a reference rather than searching docs (search_docs) or executing (execute) — though it never explicitly names those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied through the phrase 'by tool name, or a docs-site guide page,' which suggests when direct access is appropriate. However, there is no explicit guidance about when to use this tool instead of search_docs (e.g., when you already know the exact name vs. when you need to discover it), nor any exclusions or prerequisites.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description does not need to restate that. It adds useful scope context (closed set of 44 operations, guides only if configured), but it does not disclose result shape, pagination behavior, or what happens when no docs site is configured.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two short, front-loaded sentences with no filler. Everything included is relevant, and the key scope ('search this API's operations') appears first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter search tool with read-only annotations, the description is nearly complete: it names the searchable corpus and gives the primary use case. It would be more complete if it mentioned the return format or result behavior, but this is not a critical gap given the tool's simplicity.

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

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

Schema documentation covers only 'page' (50% coverage), and the description does not explicitly describe the 'query' parameter. However, the tool's purpose makes 'query' semantically obvious as the search term, and 'page' is already documented in the schema. The description adds value implicitly but does not compensate for the undocumented query parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('search'), a precise resource ('this API's 44 generated operations and, when configured, its guides'), and explicitly positions the tool as the entry point for finding the right operation. This makes it easy to distinguish from the sibling read_docs (read a known doc) and execute (run an operation).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Start here to find the operation you need' gives an explicit when-to-use signal, especially relative to the siblings. It does not explicitly state when not to use it or name the alternatives, but the positioning is clear enough for an agent to select it as the first step.

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