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

Annotations already carry readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Beyond those, the description adds useful behavioral detail: case-insensitive matching, regex support, per-match surrounding context, and section-id association—none of which the annotations convey. No contradiction with annotations; the description complements them well.

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 sentences with no filler. The first sentence front-loads the mechanism and result shape; the second gives a crisp usage pointer. Every phrase 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?

With an output schema present and strong annotations, much of the return contract is already structured. The description covers the core behaviors an agent needs: target scope (page/PDF), matching modes, and result content. Minor gaps remain—match limits, behavior on zero matches, and what 'section id' means—but they're not critical for a read-only, idempotent tool.

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 only 50% (url and context are described; text and regex are not). The description compensates by clarifying that 'text' is exact text or a regular expression, and by implying the regex boolean toggles that mode. This adds meaning beyond the bare schema for the two undocumented parameters, though it doesn't specify regex flags or the default behavior of the regex flag.

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 names a specific verb ('Finds'), resource ('a page or PDF'), and two distinct modes (exact case-insensitive text or regular expression) plus the output shape (matches with surrounding context and section id). This clearly differentiates it from siblings like read_page, page_links, and page_outline, which are structurally different operations.

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 a concrete when-to-use signal: 'For facts whose wording you know: a name, a number, an error message.' This helps the agent choose search over reading a whole page. However, it stops short of explicitly naming alternatives or stating when not to use this tool (e.g., when the tool should defer to read_page), so it doesn't earn a 5.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavior not covered by annotations: tracking parameters are removed and duplicates dropped, plus optional filters for same-site and text/URL containment. This is useful, though it doesn't cover aspects like pagination or rate limits, which are minor for this read-only tool.

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?

The description is a single well-structured sentence: core purpose first, then output transformations in parentheses, then optional filters, ending with a use-case clause. Every phrase earns its place with no redundancy or filler.

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?

Given an output schema exists and annotations carry the safety profile, the description covers the necessary behavior, filters, and use cases. It does not explain return format (handled by output schema) or edge cases like limit application order, which are minor for a tool of this 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 coverage is only 50%, but the description compensates by semantically explaining 'contains' ("containing a word in text or URL") and 'same_site' ("same-site ones"). It also describes the output preprocessing. It doesn't re-explain 'url' or 'limit', but those are self-explanatory from the schema and default behavior.

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+resource: "The links on a page" with precise output transformations (text and absolute URL, tracking parameters removed, duplicates dropped). This clearly differentiates it from sibling tools like find_in_page (text search), page_outline (outline), and read_page (full content) without needing to inspect schemas.

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?

The closing phrase "For crawling docs or finding a download" gives concrete use cases and implies a lightweight extraction role. However, it does not explicitly name alternatives or state when not to use this tool versus siblings, so it falls short of full exclusion guidance.

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 establish that this is read-only, idempotent, and non-destructive, so the description does not need to repeat that. It adds useful context by specifying that the input can be a page or PDF and by enumerating the returned metadata, going beyond what annotations alone provide.

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?

The description is a single efficient sentence that packs in the output contents, supported input types, and the read_page relationship. It is slightly dense and grammatically awkward near the end, but every phrase 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?

With an output schema, 100% schema parameter coverage, and safety annotations, nothing essential is missing. The description explains what data is returned and how to use it with read_page, making the tool fully callable.

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%: both url and depth have descriptions. The tool description adds no extra parameter-level meaning, so the baseline of 3 applies.

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 clearly identifies the tool's output: headings of a page or PDF with section ids, sizes, title, site, date, and length. It distinguishes itself from read_page by presenting itself as the outline rather than the full page content.

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?

The description gives an explicit workflow: use page_outline to locate a section, then call read_page with that section instead of reading the whole page. This tells the agent when this tool is the right choice and when read_page is the alternative.

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 declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds behavioral context beyond annotations: it specifies that only main content is extracted, that query filters passages, that section selects from an outline, and that long pages provide an outline and next_start for pagination. 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.

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

Three sentences, each earning its place. The core purpose is front-loaded, then query/section behavior is explained succinctly, and default behavior and pagination are covered. No filler or redundancy.

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?

The description covers the main behaviors: main content extraction, query filtering, section selection, start behavior, and pagination hint. An output schema exists, so return format details are likely covered there. Minor gap: max_chars behavior is not explicitly described, but it's in the schema with a default. Overall, the description is complete enough for an agent to use the tool correctly.

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 description coverage is 80% (4 of 5 params documented), so baseline is 3. The description adds significant meaning for query (filters passages) and section (selects from outline) beyond the schema's minimal descriptions. It also clarifies start behavior ('Otherwise from start') and mentions pagination via next_start, adding value beyond the schema.

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 ('Reads') and resource ('a URL') and immediately clarifies output format ('clean Markdown (main content only)'). It also distinguishes from siblings by explaining query, section, and start behaviors, making the tool's purpose unambiguous.

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?

The description explains how to use query, section, and start parameters but does not explicitly state when to use this tool versus siblings like find_in_page, page_links, or page_outline. The usage context is implied through the description of behavior, but no exclusions or alternative recommendations are given.

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