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

Annotations only declare the basic mutation profile (readOnlyHint=false, destructiveHint=false, non-idempotent, closed-world); the description adds substantial context beyond that – no platform arbitration ('Kula Labs does not decide'), a 7-day resolution window after which the order stands, the chargeback route remaining open, and the seller-side Word Pass consequence of a refund. It omits only edge behavior such as what happens if a dispute is already open or how duplicate calls (idempotentHint=false) are handled.

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?

The action and its precondition are front-loaded in the first sentence, followed by outcome and alternatives. It is dense and every clause conveys policy, though the parenthetical, telegraphic style ('your card issuer remains (a chargeback)') costs some readability.

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 two-parameter mutation with no output schema, the description covers timing, who decides, alternatives, and the default outcome if nothing happens – enough for an agent to call it correctly. It does not state the resulting order/dispute state or what the call returns, which would be the remaining useful additions.

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 100%: order_id is documented as coming from buy or my_orders and reason as a few sentences on promise versus delivery. The description reinforces the meaning of reason but adds no format, length, or sourcing detail beyond the schema, so the baseline 3 applies.

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 description names the actor (Buyer), the concrete action (tell the seller the delivery was not what the listing promised), and the trigger condition (14 days after delivery). It also explicitly separates this from settle_dispute and withdraw_dispute, so an agent can distinguish it from its closest siblings 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?

It states the precondition (delivery within 14 days, item not as promised) and names the alternatives: the seller settles via settle_dispute or answers, the buyer may withdraw via withdraw_dispute. It also spells out the fallback if no agreement is reached in 7 days, leaving nothing to inference.

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