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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds real behavioral context: required credential scopes ('price compute or billing read scope'), the workspace-claim prerequisite with the exact 403 failure mode for sandbox keys, the fact that receipts are generated on demand ('Receipts are made only when you ask'), and the per-agent value-signal accounting. These are things an agent cannot learn from annotations or schema.

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 purpose and the two modes, then progressively adds constraints, output alternatives, and auth prerequisites. It is dense but almost every clause carries new information; the auth/claims sentences at the end are long but justified for a tool that 403s on unclaimed workspaces.

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?

No output schema exists, and the description gives only a partial picture of the return shape ('one statement with totals'), which is the main remaining gap. Otherwise it covers paging limits, defaults, auth scopes, workspace prerequisites, and the CSV/HTML escape hatch, which is enough for an agent to call it correctly.

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; the description goes modestly beyond it by framing the ids-vs-period choice, restating period defaults and the 366-day cap, and explaining what the agent filter means ('A period statement also counts, for each agent, the value signals set up in Settings, Value receipts'). It does not discuss limit/offset paging in prose, so it is not fully additive.

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 receipts for many of your workspace's priced calls at once, as one statement with totals') and the two selection modes, which implicitly separates it from the single-record get_receipt sibling. It never names a sibling tool explicitly, so an agent must infer the boundary rather than being told it.

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 when-to-use conditions: either up to 50 event ids or a period, 'Send ids or a period, not both', with the period defaulting to this calendar month and capped at 366 days, plus optional narrowing by function or agent. It also routes the agent elsewhere for non-JSON output ('For CSV or a printable page, call GET /api/receipts with format=csv or format=html'). No explicit when-not-to-use versus list_usage_events or get_receipt, but the context is clear.

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