execute_booking_cancellation

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

Far beyond what annotations declare: it discloses the internal sequence (recheck reservation, at most one standard request, reconcile with fresh reads), the non-idempotent late-credit-loss outcome that returns a new pending reference, and an explicit anti-retry policy. Annotations already flag destructive/non-idempotent, and the description adds the operational detail that makes those hints actionable.

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?

Five short sentences, front-loaded with the action and its caveats, and each carries distinct operational content (sequence, retry policy, confirmation gate, scope exclusion). Dense but no filler; the ordering could be slightly tighter with the confirmation gate placed earlier.

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, open-world, non-idempotent mutation with an output schema (so returns need no explanation), the description covers the confirmation gate, the retry prohibition, the pending-warning state, and what the action does not affect. Nothing an agent needs to call it safely 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 0%, so the description must compensate, and it does partially: it pins 'confirmed: true' and implies actionReference is the token from the prepare step ('exact prepared booking'). It says nothing about gymId's role or the 64-hex reference format, leaving one of three parameters unexplained.

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 sentence gives a specific verb and resource with a tight scope constraint ('one exact prepared booking'), which tells an agent this is the execution half of a prepare/execute pair rather than a general cancellation tool. It does not explicitly name the sibling execute_late_booking_cancellation or the prepare_booking_cancellation prerequisite, so sibling differentiation is inferred rather than stated.

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?

Strong guidance: 'Always show the exact full preview and obtain separate account-holder confirmation before execution with confirmed: true' defines a precondition and the required call shape, and 'do not retry automatically' plus the pending late-credit-loss warning state when not to act. It stops short of naming the specific alternative sibling tools for the late-cancellation path.

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