web_fetch

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

With no annotations present, the description carries the full behavioral burden and does so well: it discloses the confirmation gate, the rejection policy (executable/archive/document extensions, non-text content types), the sanitisation rules (scripts, forms, iframes, event handlers, unsafe links stripped), and the SSRF guard (private/loopback blocked). It also states the return contract (file path only), which is the single most important thing an agent needs to avoid mis-consuming the output.

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?

Four dense, front-loaded sentences with zero filler: action, return contract, rejection rules, then sanitisation and network restrictions. Each sentence adds distinct operational information.

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?

An output schema exists, yet the description still usefully clarifies that only a path is returned, and it covers safety, sanitisation, and the confirmation prerequisite. The one material gap is the destination/filename behavior of `output_dir`, which leaves an agent unable to predict where the markdown file will be written.

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 and largely does not. `url` is inferable from 'web page', but `output_dir` (default 'fetched') is never mentioned or explained — the agent cannot learn from the description where the file lands or how to control it.

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 a specific verb and resource (download a web page, sanitise, save as local markdown file) and distinguishes itself from http_request by declaring it returns only a file path rather than a response body. The agent can tell exactly what artifact the call produces without opening the schema.

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?

Explicitly requires user confirmation before calling and instructs the agent to follow up with read_file to consume the result, which is real usage guidance. It does not, however, contrast itself with http_request for API/JSON endpoints or explain when to prefer a direct fetch over raw HTTP, so the alternative-selection guidance is implicit.

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