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

Goes well past the annotations: it discloses that reports land in a human-read queue, that the email is never shown but receives the founder's answer, that the endpoint is public with no key but subject to the anonymous rate limit, and it gives concrete semantics for idempotency ('the same report sent twice within a day answers the first id with duplicate true'). That last point turns the abstract idempotentHint into observable behavior.

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?

Front-loads the triggering condition before the parameter walkthrough, and every clause carries information. It is a single dense paragraph with stacked parentheticals, though, which makes the required-vs-optional split harder to scan than a short bulleted structure would.

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 an 11-parameter mutation with no output schema, the description covers the essentials an agent cannot get elsewhere: no auth required, the rate limit, the human-queue consequence, and the duplicate-response shape. The undocumented remaining parameters are all explained in the schema itself.

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 100%, so the baseline is 3, but the description adds genuine value: it tells the agent where `product_slug` comes from (find_best_price or search_products), that `offer_id` comes from the card's offers and is optional, and restates the 1000-character `message` limit alongside guidance on what to say. It leaves `locale`, `page_url`, `shop_slug`, `ip_hash`, and the `website` spam trap to the schema, which is acceptable.

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 ('file a report' about a wrong offer on a product page) and immediately bounds the scope with the enumerated `kind` values price | variant | category | shop | other. An agent can tell this is the complaint-filing tool, not a data-read tool, 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?

Gives a rich set of triggering conditions ('the shop's page shows another price, the offer is another variant or product, the link leads to the wrong shop or page'), which is far more than most tools offer. It does not, however, route the agent away from the similar sibling `report_illegal_content`, leaving the boundary between 'wrong' and 'illegal' for the agent to infer.

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