Web scrape

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

The annotation readOnlyHint: true covers the read-only nature, and the description adds behavioral details like truncation (ending with '[truncated]') and the fact that cut-off content cannot be fetched later. It also mentions respecting robots.txt via the parameter description. This goes beyond the annotation, though it could be more explicit about side effects (or lack thereof).

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 overly verbose and repetitive, repeating the same pattern for max_chars and truncation ('each page separately... 5 links stay under the limit each...'). This could be condensed into a single statement about per-page behavior without the redundant numeric examples. The structure is not poorly organized, but the wordiness hurts usability.

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 the presence of an output schema, the description does not need to explain return values, so it is appropriately scoped. It covers key behaviors like batching, per-page limits, robots.txt, timeout, and link removal. Minor gaps exist (e.g., error handling), but overall it equips an agent with the necessary context to use the tool effectively.

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?

Every parameter is thoroughly described in the schema, with examples like 'default and maximum 20000' for max_chars and 'timeout for the whole call' for timeout_ms. The tool description reinforces these semantics, such as the per-page application of max_chars. No parameter lacks context.

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 states the tool's primary function: downloading pages and returning main text as markdown. It also specifies parallel fetching and batching, which is a distinctive capability. However, the repeated phrasing about per-page limits slightly detracts from the core purpose statement.

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 provides a clear batching instruction ('batch all links you need into one call instead of calling the tool per link'), which is a useful usage tip. However, it does not explicitly contrast with sibling tools like web_search or web_search_images, leaving some ambiguity about when to choose this over alternatives. It lacks guidance on when not 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.