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

Annotations only declare the safety/idempotency profile; the description goes further, disclosing the one-vote-per-buyer-and-payment rule, the 24-hour window, that repeats are ignored, and the downstream consequence that multiple independent buyer reports trigger a paid re-test that alone can change a grade. This is real behavioral context beyond the structured fields and is consistent with idempotentHint=true and readOnlyHint=false.

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-loaded with the core action and tightly packed, with every clause carrying routing or behavioral information. It is dense enough that some nuance (single-use vs. per-payment vote) takes a second read, but there is little waste.

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, so return values need not be described. The description covers invocation timing, preconditions, exclusion conditions, deduplication semantics, and downstream effects, leaving no material gap for correct invocation.

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 meaning by specifying where the required receipt comes from (the allow decision / paid /v1/authorize API), which clarifies provenance beyond the schema's terse 'returned with the allow decision'. It does not elaborate on problems/httpStatus/tx, but those are well documented in 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?

States a specific verb+resource (report whether a paid x402 call delivered) and names the exact receipt source (Lumière PayCheck allow decision via /v1/authorize). It explicitly separates itself from siblings with 'Not for checking endpoints (use check_endpoint or check_payment).'

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 explicit when-to-use ('Use it once, right after paying, only when you have such a receipt') and when-not ('skip it if you paid without one, or if the user asked you not to report'), plus the alternative tools for the endpoint-checking case. Nothing is left to inference.

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