web_fetch

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

With no annotations, the description discloses important behavioral details: full content extraction, Markdown conversion, 100% fidelity, limitations with dynamically loaded JavaScript content, and processing time for large pages. This adds significant value beyond the basic fetch operation and is more transparent than typical descriptions.

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 well-structured with clear sections and bullet points, making it scannable. It is appropriately sized for the complexity, but there is minor redundancy (e.g., URL accessibility is mentioned in both the schema and the description), which prevents a perfect score.

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 tool has one parameter and no output schema, the description covers key aspects comprehensively: what it extracts, how it converts, fidelity, edge cases (auth, dynamic content, page size). This is sufficient for an agent to understand when and how the tool behaves, including expected return format (Markdown).

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?

The schema description covers the single 'url' parameter 100%, so the baseline is 3. The tool description reinforces that the URL must be 'complete and accessible' but does not add new semantic details beyond what the schema already states. No ambiguity or missing parameter information.

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 ('Fetches and extracts complete content') and names the resource ('a URL') and the outcome (returning structured Markdown). This clearly distinguishes it from sibling tools like web_search (search) and web_map (map).

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 implies usage: fetching a specific URL's content. It provides edge cases and best practices but does not explicitly state when to use this tool over other siblings like web_search, nor does it mention exclusions or alternatives. The context is clear but not explicit about selection criteria.

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