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

Annotations only tell the agent this is a non-read, non-destructive, non-idempotent write; the description adds substantive context beyond that: the data lands as an anonymous analytics event, it feeds route freshness, and stale reports trigger re-verification. It also carries a strong data-handling constraint (no personal data, credentials, order numbers, or the user's own spec). The gap is that non-idempotency is never surfaced — repeat reports presumably create duplicate events — and there is no mention of failure modes for an unknown slug.

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 tight sentences with the action and its trigger front-loaded and no filler. The param restatement ('plus the tool calls you spent and an optional ≤100-char note') mildly duplicates the schema, but it is folded into a single dense clause rather than inflated.

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 four-parameter reporting tool with no output schema, the description covers the essentials: what to send, why it matters downstream, and a privacy guardrail. Remaining gaps are the unexplained 'slug' and no statement of what a successful report returns or does on an invalid/unknown route.

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?

At 50% schema coverage the description needs to compensate, and it partly does: it maps 'the tool calls you spent' to steps_taken and restates the note's ≤100-char purpose with an example already in the schema. Critically, 'slug' is never explained — an agent must infer it is the route slug from find_routes/get_route — and the outcome values are only repeated, not defined (e.g. what distinguishes 'stale' from 'partly_worked').

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 ('report whether it held') and enumerates the exact outcome vocabulary (worked, partly_worked, stale, failed) plus the accompanying fields. An agent can immediately distinguish this mutation/reporting tool from the read-oriented siblings like find_routes, get_route, and get_execution.

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 explicit and front-loaded: 'After using a route, report whether it held.' The rationale ('keeps routes fresh and flags stale ones for re-verification') clarifies why an agent would call it. It stops short of stating when not to report or which sibling to consult first (e.g. get_route to obtain the slug), so it is clear context rather than complete routing guidance.

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