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

The description adds behavioral context beyond the annotations: it discloses that the tool re-shops the itinerary rather than trusting a provider-native offer, and that it may return an unavailable or reconfirmation state. It also explicitly states it does not book or charge the traveler, which is important since readOnlyHint=false suggests possible side effects. This clarifies the non-booking nature while acknowledging the re-shop behavior, though it does not detail potential price changes or holds.

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 description is three sentences and efficiently front-loads the purpose. Each sentence adds distinct value: the source and action, the re-shop behavior and return capability, and the non-booking/charging note. While concise, the phrase 'instead of trusting a provider-native offer' is slightly wordy but informative; overall, no waste.

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?

With a single parameter, an output schema present, and annotations covering read/write and destructive hints, the description covers the essential context: the token source, the re-shop behavior, possible return states, and the non-charging guarantee. It does not mention error handling, but the output schema likely covers that. It also doesn't explicitly link to the next step (book_flight), but this is a minor gap for a preparation tool.

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 schema already documents the selection_token parameter. The description adds critical semantics: it must be passed unchanged and not constructed or modified from flight details or provider offer IDs. This prevents misuse and clarifies the opaque, signed nature of the token, which goes beyond the schema's basic type description.

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 clearly states a specific action ('Prepare a flight for booking') with a specific resource (a signed selection_token from an eligible search_flights row). It distinguishes this tool from booking by explicitly stating it does not book or charge, and from direct provider offers by noting it re-shops instead of trusting a provider-native offer. This gives an agent a precise understanding of the tool's role.

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 description clearly indicates the prerequisite: the selection_token must come from an eligible search_flights row, so it must be used after search_flights. It also implies this is a pre-booking step by stating it does not book or charge. However, it does not explicitly name book_flight as the subsequent step or exclude cases where this tool should not be used, such as when a provider-native offer is already confirmed. The context is clear but lacks explicit exclusions.

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