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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description goes far beyond them: it discloses the two-phase confirm/apply flow, the confirmation_required preview return, routeToken lifecycle and validity scope, entryDate/procDate defaults, conditional VAT field sending, and counterparty-confirmation scoping. No contradiction with annotations; the prose substantially enriches the safety profile.

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?

Eight dense sentences, front-loaded with the purpose line, and each following sentence covers a distinct safety- or behavior-critical point. There is mild redundancy among the confirmation warnings ('does not bypass preview', 'preflight is not confirmation'), but for a destructive two-phase write that repetition is justified. Length is proportionate to the transactional complexity.

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 destructive tool with no output schema, the description covers the phase-one return (confirmation_required plus payload preview), all prerequisites, token handling, and the confirmation scoping. The success-path response shape is undisclosed and no alternative-routing guidance exists, but every constraint an agent must respect before posting is stated.

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?

With 32 parameters and only 16% schema description coverage, most fields are undocumented, and the description cannot fully compensate. However, it adds real meaning by explaining the dual calling convention (raw payload object vs common flat fields), the date defaults, and the conditional VAT behavior. The three flow-critical params (routeToken, confirmWrite, confirmCounterpartyExplicit) are also restated in prose, though slightly redundant with their schema descriptions.

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?

The opening sentence 'Creates a BRC cash receipt' states a specific verb and resource, immediately differentiating the tool from the update/get/delete/list cash receipt siblings and from create_cash_payment. The singular 'a' also separates it from brc_batch_cash_receipts without requiring schema inspection.

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 description gives exceptionally clear procedural context: routeToken must come from the matching brc_route_request workflow, confirmWrite:false returns a preview, confirmWrite:true applies only after explicit confirmation, preflight is not confirmation, and confirmCounterpartyExplicit must be true. What is missing is any explicit mention of alternatives — e.g., use brc_batch_cash_receipts for multiple receipts or brc_create_cash_payment for payments — so there are no exclusions or alternative routing.

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