post_flights_bookings

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

The description explicitly labels the tool 'Idempotent' and describes returning the existing booking for a given prebookId, while the annotations declare idempotentHint=false. This is a direct contradiction between description and structured data, which forces the lowest score regardless of the otherwise rich behavioral detail (409/45035 concurrency handling, transient retries, payment flows).

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?

Organized into scannable Overview / When to Use / What You Get / Key Features / Quick Start sections with the required fields front-loaded at the end. It is long, but nearly every sentence carries actionable content; minor redundancy between the Overview and Key Features sections keeps it from a 5.

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 complex payment/finalization tool with nested objects and no output schema, the description covers the booking flow position, required fields, idempotency, concurrency errors, retry behavior, and all four payment paths. An agent has enough to invoke it correctly without opening sibling tools.

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, but the description adds genuine operational meaning beyond the schema: which payment methods map to which fields, that CREDIT_CARD details go through the secure PCI endpoint, and the tip to use the new transactionId from the services endpoint rather than the prebook one.

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+resource and scope: 'Complete a flight reservation by confirming a prebook and processing payment. This is the final step in the booking flow.' An agent can immediately distinguish this from read siblings like get_flights_bookings and the earlier post_flights_prebooks step.

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?

The 'When to Use' section gives clear triggering conditions (final confirmation, payment completion, after service selection) and references the prebook and services endpoints that precede this call. It does not explicitly name an alternative sibling to use instead, or state when not to call it, so it falls short of full routing guidance.

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