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

Annotations already declare destructive=true and readOnly=false, but the description goes well beyond them: it enumerates the concrete effects (status CANCELLED, cancelled ledger entries, cancellation settlement, marketplace sync when applicable), the two-step preview/approval protocol, the financial consequence of retained_amount versus refund due, and the fact that refunds are only confirmed later in finance. It also flags the tool as currently unavailable under this authorization, which an agent needs before attempting the call.

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 action and its financial consequence, then a scannable scope/risk/effects block. Dense but each clause carries operational information. Slightly heavy for a 5 — the 'INDISPONÍVEL nesta autorização' status is appended as a trailing conditional that reads like runtime state rather than tool semantics.

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 5-parameter mutation with no output schema, the description covers permissions, approval gating, side effects, financial settlement semantics, and an availability caveat. Only the return value of the preview step and the behaviour when the settlement cannot be computed are unaddressed, which is a modest gap.

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 60%, so the baseline is 3. The description reinforces the meaning of the two behavioural parameters (a reason is required; retained_amount drives the retained-vs-refundable split) beyond the schema's one-liners, but `id` and the exact role of approval_id vs. preview flow are left entirely to the schema.

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 and resource — cancel a stay (reservation) — and immediately names the side effect that distinguishes it: the Neural cancellation financial settlement (retained amount vs. refund due). It also carves out contract-backed stays as belonging to a different flow. It does not explicitly separate itself from the sibling update_reservation_status, which could plausibly also set status CANCELLED, so the differentiation is good but not complete.

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?

Explicit preconditions are given: requires approval and payments permission, requires a preview plus mandatory user approval, and contract stays must be cancelled through the contract instead. That is clear when-to-use and one concrete when-not. It falls short of 5 because the closest sibling (update_reservation_status) is never named as the alternative for the no-settlement case.

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