issue_refund

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

Annotations already declare the write profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the safety bar is lower. The description adds genuinely new behavior — that funds are credited to an account balance rather than reversing a payment, and that approval is required — but omits what happens if approval is denied, whether values are capped, and how the pending state is surfaced.

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?

A single front-loaded sentence plus a bracketed policy tag — no filler and the operational caveat comes first. Its brevity is efficient, though the same compactness is what leaves the parameters under-specified.

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?

An output schema exists so return values need not be explained, and annotations cover idempotency. But for a financial mutation gated by approval with three undocumented required parameters, the description should explain the approval mechanics and the meaning of 'reason' and 'amount'; neither is present.

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% for all three required parameters. The description only loosely implies 'amount' and 'customer_id' by mentioning 'an amount to a customer's account balance'; it says nothing about currency, sign, valid range, customer identifier format, or what 'reason' is used for.

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 ('Refund'), the resource being moved ('an amount'), and the destination ('a customer's account balance'), which is more precise than a bare name restatement. It does not name any sibling or scope boundary, but the sibling set (tickets, customers, approvals) is unrelated enough that confusion is unlikely.

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 '[policy: require_approval]' tag implies this call enters an approval flow rather than completing immediately, which is a meaningful usage cue pointing at list_pending/approval_status. However, it never says explicitly when to use this versus another path, nor what to do after the approval requirement is triggered.

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