Split-ticket itineraries

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses important behavior: packaged search runs first, then up to max_hubs hubs with 2 queries per hub (3 with allow_overnight), and it stops at a recorded rate limit without retrying. It also explains that each ticket is confirmed on its own google_flights_url, that missed connections are not rebooked, that bags may need re-checking, and that total is null unless all parts share one currency.

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 front-loaded with the core definition and route syntax, and nearly every sentence carries operational information. It is dense and somewhat clause-heavy, but given the tool's complexity and 37 parameters, the length is justified rather than padded.

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?

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. The description still supplies essential caveats about split ticketing, connection risk, currency aggregation, and rate limits. It is not fully self-contained for a 37-parameter tool, though, because many parameters are only indirectly covered and the description defers to get_guide for full rules.

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 description coverage is 0%, so the description must carry parameter meaning. It does well for the distinctive parameters: route formats, trip, max_hubs bounds/default, via/exclude_via hub behavior, allow_overnight query behavior, and min_connection_hours as a planning default. However, with 37 parameters, many key inputs such as top, fetch, proxy, max_stops, leg_max_stops, baggage_buffer, and most passenger/filter fields are left unexplained or only covered by broad category references, so it only partially compensates.

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 resource and scope: separately ticketed itineraries built from real one-way quotes, with route syntax and round-trip behavior. It distinguishes itself from packaged search by running packaged search first and by flagging split_ticket true / connection_protected false, so an agent can identify when this tool rather than search_flights or search_trip applies.

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?

Usage is clearly implied as opt-in split-ticket search, with explicit route formats for one-way and trip="rt", and an exclusion: 'Not for multi-city.' It also points to get_guide for full rules. It does not explicitly compare itself with search_flights/search_trip by name, so it stops short of a full when-to-use/when-not matrix.

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