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

With no annotations, the description carries the full burden, and it does well: it states the return value ('an official API or open dataset for the same data... plus a log id'), the explicit non-capability (no CAPTCHA or bot-protection bypass), and cost/latency ('Free, takes seconds'). It omits that a report is stored/logged by default unless the private flag is set, and says nothing about rate limits or auth, which is the remaining gap.

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 dense sentences with zero filler: trigger first, then what you get back, then the honest limitation and cost. Every clause carries information an agent needs before calling.

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 6-parameter tool with no output schema and no annotations, the description covers the two things an agent most needs — when to call it and what it returns. It does not explain that reports persist by default (only the schema's private flag hints at this) or note any auth/rate-limit constraints, leaving a modest gap.

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 67%, and the description meaningfully compensates by translating real-world symptoms into values for failure_type ('empty page that needs JavaScript', 'PDF-only content', 'a page that has gone'), which goes well beyond the schema's terse 'e.g. 403, 429, captcha...' list. It also touches the private/matching semantics. It adds more than schema-only baseline but still leaves agent_name and error_message purely to 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 gives a concrete verb+resource ('report_failure', called right after a fetch/scrape/API call fails) and enumerates the exact failure conditions it covers (403, 429, CAPTCHA, Cloudflare, login wall, JS-only, PDF-only, dead page). This is clearly distinguishable from the sibling tools request_action and request_data, which are for making requests rather than reporting their failure.

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 trigger condition is stated precisely and front-loaded ('Call this right after a fetch, scrape or API call fails and stops your task'), with a detailed list of qualifying failure modes. It stops short of a true 5 because no alternative is named (e.g. when to use request_data again instead) and the when-not condition ('does not bypass CAPTCHAs') is a capability limit rather than routing guidance.

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