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

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: receipts exist only when requested ('never sent for every call'), required credential scope (price compute or billing read), and a concrete 403 failure mode for unclaimed workspaces with unclaimed sandbox keys. That is exactly the kind of operational context annotations cannot express.

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?

Purpose and key are front-loaded, then contents, then the format escape hatch, then auth requirements — a sensible ordering. It is slightly dense in long clauses but every sentence carries actionable information, with no filler.

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?

With no output schema, the description compensates by enumerating the returned fields (what was priced, function and agent, timing, amount, payment method, outcome). Combined with the auth/403 notes and the CSV/HTML alternative, an agent has everything needed to call it correctly and interpret failure.

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% and the single parameter is already documented, so the baseline would be 3. The description adds marginal provenance value by tying the value to two producers (list_usage_events returns it, report_outcome takes it), which helps the agent source a valid UUID.

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 ('Get the receipt for one of your workspace's priced calls') and pins the retrieval key to its producer ('by its usage event id (the id list_usage_events returns ...)'), which distinguishes it from the plural list_receipts sibling. It goes on to enumerate the receipt's contents, so an agent knows exactly what it gets back.

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 concrete routing information: get the id from list_usage_events, and use the REST endpoint with format=csv or format=html when CSV or a printable page is needed. It does not explicitly contrast with list_receipts, but the single-receipt-vs-list distinction is implied by the framing.

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