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

Annotations already declare this as a non-read-only, idempotent, non-destructive write, and the description adds genuinely useful semantics beyond that: the order retains its full price and only the cash remainder is charged, and the same idempotency key should be resubmitted on retry. It doesn't say whether the applied rebate can be reclaimed or what a partial failure looks like, which matters for a money-moving tool.

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?

Four dense sentences with zero filler, ordered from what the tool does to the branch decision to the domain side effect to the retry rule. Every sentence carries distinct information.

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 7-parameter mutation with no output schema and no annotation detail on rebate accounting, the description covers the critical domain facts (full price preserved, cash-only charge, idempotency, fx prerequisite). Remaining gaps are the meaning of quote_version and any hint about what the agent should expect afterwards (remaining rebate balance, next payment step).

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 description coverage is 0%, so the description carries the full burden; it explains amount_minor (part or all), currency (1:1 when matching), fx_quote_id (must come from evuun_preview_rebate_conversion) and idempotency_key reuse. quote_version is completely undocumented despite being required, and there is no stated relationship between amount_minor's currency and the rebate's currency.

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 (apply part or all of the buyer's unlocked rebate to one of their own orders) plus a timing constraint (before payment starts). It partially routes between siblings by naming evuun_preview_rebate_conversion for cross-currency, but never distinguishes itself from evuun_release_rebate or evuun_get_rebates, which are the obvious confusables.

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?

"Before payment starts" is an explicit precondition, and the cross-currency branch tells the agent exactly which sibling to call first for an fx_quote_id. It stops short of an explicit when-not rule (e.g. use release_rebate to give the rebate back), so the apply-vs-release choice 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.