Fetch indexed page or section

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

With no annotations, the description carries the full burden. It discloses caching behavior and a strict character cap, which go beyond the schema. However, it omits details about authentication, rate limits, error handling, and return format. It partially compensates but leaves gaps.

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, front-loaded with the action, and every phrase earns its place. The first sentence states the core function, the second adds practical guidance without unnecessary detail.

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 tool with 4 parameters, no output schema, and no annotations, the description gives the essential idea and usage guidance. Yet it leaves sourceId's role and edge-case behavior unaddressed. It is adequate but not fully comprehensive.

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 0%, so the description must compensate. It explains 'heading' (exact heading/anchor) and 'maxChars' (strict character cap), but sourceId and url are not semantically elaborated beyond their names. This is partial compensation, adequate but with clear gaps.

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 uses a specific verb ('Returns') and clearly identifies the resource ('one cached page or exact heading/anchor') with a distinct constraint ('strict character cap'). It distinguishes from sibling tools like search_pages_index (search vs retrieval) and fetch_pages_content (likely full content vs capped sections).

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?

It provides direct usage context with 'Prefer a heading returned by search_pages_index to minimize tokens', indicating when to use this tool and how to choose the best input. However, it does not explicitly state when not to use it or directly contrast with the full-page fetching alternative.

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