put_bookings_bookingid

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description goes well beyond that: it explains that non-refundable bookings are still cancelled but charged (CANCELLED_WITH_CHARGES), that policies apply automatically, and that post-deadline cancellations incur fees. This is exactly the behavioral consequence detail an agent needs before invoking a destructive tool.

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 sectioned markdown is well front-loaded, but charges and refunds are restated across Overview, 'What You Get,' 'Cancellation Outcomes,' and 'Important Notes' — the same information three or four times for a one-parameter tool. It could be roughly halved without losing meaning.

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?

There is no output schema, and the description ably fills that gap by enumerating return content (cancellation status, charges, refunds, updated booking status). Behavior, outcomes, and side effects are covered; only the timeout parameter and sibling differentiation remain unaddressed.

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?

With two parameters and 50% schema coverage, the bookingId field has no schema description — but the description compensates by specifying that it is provided 'in the URL path.' The timeout parameter is undocumented in both schema and description. Adequate but not complete.

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 states a specific verb and resource: 'Cancel an existing confirmed booking,' which is unambiguous. However, it never differentiates itself from the closely related sibling put_bookings_bookingid_amend, which an agent could easily confuse with this cancellation endpoint.

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?

A dedicated 'When to Use' section gives clear scenarios (guest cancellation, administrative cancellation, policy enforcement), which is solid context. It stops short of exclusions or routing rules — it never says when to use amend instead, or when cancellation is NOT permitted.

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