issue_refund

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotent, so the safety profile is established structurally. The description adds value beyond that: it flags a financial action, defines the $250 approval threshold, and clarifies that approved_by is populated by the harness rather than the model — a behavioral detail no annotation conveys. It omits remaining behavior such as reversibility of an issued refund or what happens on retry, which keeps it from a 5.

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?

Three short sentences, front-loaded with the action and immediately followed by the risk warning and the approval constraint. The parenthetical about approved_by prevents a likely misuse and earns its space; nothing is filler.

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, non-idempotent financial mutation with no output schema and 20% parameter coverage, the description covers the most important risk (approval gating) but leaves gaps: whether partial refunds are supported, what reason should contain, whether the call is retryable, and what confirmation is returned. Adequate as a guardrail, incomplete as a full specification.

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 only 20%, with approved_by the sole documented parameter, so the description must carry weight — and it does partially, explaining both the amount threshold and the provenance of approved_by. However, reason, case_id, and order_id receive no semantic elaboration (accepted values, format, or relationship to the order/case), leaving half the required surface undocumented.

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?

"Issue a refund for an order" gives a specific verb plus resource, and no sibling (get_case, get_order, update_case, draft_customer_email) competes for this action, so differentiation is implicit. It stops short of stating scope details such as partial vs full refunds, but the core action is unmistakable.

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 supplies one concrete usage rule — amounts above $250 require a human approver — which is genuinely actionable gating information. It does not say when to prefer this over alternatives (e.g., escalation paths, or when a refund should instead be declined or drafted as an email to the customer), leaving the broader invocation context to inference.

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