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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it states that money movement is out of scope so only the fact is recorded, defines the balance ceiling, and enumerates resulting state changes (unapplied balance reduced, credit_note.status -> settled when exhausted). That is exactly the consequence disclosure an agent needs before a destructive mutation.

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 verb and resource, then constraints, then effects in a clearly labelled 'Effects:' clause. It runs slightly long and the parenthetical aside plus 'like every other outbound act' are conversational, but every sentence carries actionable content.

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?

With no output schema, the description correctly compensates by spelling out the resulting state changes, and with 100% schema coverage plus full annotation coverage the remaining burden is small. An agent has everything needed to decide and call correctly.

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, and the description earns an increment by adding a constraint the schema lacks: the amount and source are bounded by the source instrument's unapplied balance. It doesn't add format or routing detail for method/reference, but the key semantic limit is supplied.

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?

Specific verb and resource ('Record money returned to the customer') plus a precise scope qualifier ('against an unapplied payment or credit note balance'). This cleanly separates it from inbound siblings like o2c_record_payment and from application siblings o2c_apply_payment / o2c_apply_credit without needing to open the 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?

Gives a real eligibility rule (bounded by the unapplied balance; you cannot refund what is already applied) and routes the excluded case to an explicit alternative ('reverse by credit note instead'). It stops short of a full when-to-use enumeration against o2c_create_credit_note or o2c_record_payment, so it's strong but not exhaustive.

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