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

Goes well beyond the annotations (readOnly=false, destructive=true): it discloses that funds are actually spent, that a stale price is refused with 409 price_changed and nothing is charged, that re-buying the same traders/days returns the earlier order without a second charge, and that 402 means insufficient balance/no paid plan while 409 plan_exhausted means the allowance is gone. Note the no-double-charge rule is effectively idempotent behavior even though idempotentHint=false, but the description is the more informative of the two, not a misleading claim.

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 ('Buy an export...'), and every sentence carries operational weight (spend source, price ceiling, consent, idempotency, error codes). It is a dense single block rather than scannable bullets, but it is not padded.

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 money-spending mutation with no output schema, the description covers prerequisites, consent, failure codes and repeat-call behavior thoroughly; the only real gap is the shape of a successful order response, which the agent must infer.

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 real meaning: maxPriceCents is defined as the export_quote price the user agreed to and acts as a hard ceiling, and viaPlan is described as removing the from/to/maxPriceCents requirement that the schema leaves purely optional. That conditional-requirement relationship is not derivable from the schema alone.

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 with its exact semantics: 'Buy an export: a permanent grant over these traders' daily files, usable at once.' The bounded scope (entityIds, day range, 25-trader cap) and the contrast with export_quote (which supplies the price) separate it cleanly from siblings like export_files, export_options and export_quote.

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?

It names the two mutually exclusive funding paths and their conditions ('from the balance... from, to and maxPriceCents required' vs 'with viaPlan... no from/to/maxPriceCents'), gates invocation on the user's explicit yes, and points to export_quote as the source of maxPriceCents. That is explicit when/when-not guidance an agent can act on without opening the schema.

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