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

With no annotations supplied, the description carries the full burden and does so: it flags money movement in caps, discloses the 1 CRD per-call cost that is charged even on rejection (but not on 429), explains idempotent_replay semantics on retry, and enumerates the failure modes with status codes and their side effects (e.g. 402 STRIPE_REFUND_FAILED = no credits changed). This is exactly the behavioral context an agent needs before invoking a destructive billing operation.

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?

It is front-loaded with the highest-stakes information ('MOVES MONEY') and organized by mode, cost, and errors. The error-code run is dense but each entry adds actionable signal rather than padding; a slightly tighter grouping of the 404/409/400 family would improve scanability.

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 12-parameter, high-risk financial tool with no annotations and no output schema, the description covers purpose, source selection, cost, idempotency, and error recovery including quoting request_id to support. Nothing an agent needs to call this correctly or interpret a failure is missing.

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 meaning the schema cannot express: the mutual-exclusivity constraint on source parameters, the 'default: all' semantics of amount, and the clarification that reference_id targets the latest matching transaction. Minor gap: reason, metadata, project_id, api_key, and x402_payment are left entirely to 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 'Refund or reverse credits' pairs a specific verb with the resource, and the following sentences enumerate the two distinct modes (purchase refund vs. ledger reversal) with the exact parameters that select each. An agent can distinguish this from sibling mutators like deduct_credits, issue_credits, and redeem_credits without opening any schema.

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 states the selection rule outright: 'Pass exactly one source,' then explains what each source does (purchase_id/stripe_payment_intent_id refunds the Stripe charge; transaction_id/reference_id reverses a ledger entry). It also specifies the exclusion behavior for reference_id ('latest matching transaction') and the partial-refund mode via amount, leaving no ambiguity about when to pick which path.

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