whatevertrips

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds useful context that results come "from cached flights" (explaining why the tool is not open-world) and that output is price-sorted. It omits failure behavior (e.g., empty result handling) and any latency/cost notes, keeping it below a 5.

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?

Three tight sentences with no filler; the core operation and the from/from_cities choice are front-loaded, and the save_trip hand-off is correctly placed last.

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 an output schema present, return values need no explanation, and annotations cover the safety profile, so the description is nearly complete for a 12-parameter tool. It omits only edge-case behavior (empty results, include/exclude interaction) that an agent might wonder about.

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 100%, so the baseline is 3 and the schema carries the parameter load. The description largely restates schema content ("Give from or from_cities", the multi-city return rule) rather than adding syntax, defaults, or format details the schema lacks.

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 and resource ("Generate cheap round trips through several cities") plus scope ("from cached flights"), and explicitly differentiates itself from save_trip by naming it as the booking/sharing follow-up. An agent can tell this apart from search_flights/search_cities without opening a schema.

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?

Clear routing context: pass flight_ids to save_trip to share or book, and how from vs from_cities select departure behavior. It does not state when to prefer this over search_flights or what to do when no trips are found, so it stops short of full when/when-not guidance.

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

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

Annotations already declare this as a non-read-only, idempotent, non-destructive write. The description adds value beyond them: the saved trip becomes a PUBLIC page, the return includes a booking link on Kiwi.com, and prices are only confirmed on the booking site (i.e., prices here are not final). The public-page disclosure is a meaningful privacy signal absent from the annotations.

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?

Three short sentences, front-loaded with the action and its inputs, then the return behavior and the pricing caveat. Every sentence carries distinct information; nothing is redundant with the title or annotations.

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 an output schema present, the description need not enumerate return fields, and annotations cover the safety profile; the remaining behavioral notes (public page, booking link, price confirmation) are the ones an agent actually needs. It could say a bit more about the durability of the saved trip, but nothing essential 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 description coverage is 100%, so the single parameter is already fully documented in the schema (source tools, any order, 1–8 items). The description only restates the source of the ids, adding no new syntax or constraint, so the baseline 3 applies.

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?

Specific verb+resource ('Save a trip from flight ids') plus the outcome ('returns a public page with the trip and a booking link'). It also names the sibling tools that produce the required input (search_flights, plan_trips), so an agent can place it correctly in the workflow without opening any schema.

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?

Clearly implies the precondition: flight_ids must come from search_flights or plan_trips, so the agent knows this is a downstream step, not a standalone lookup. It gives no explicit when-not guidance (e.g., whether repeated saves create duplicates), which keeps it just short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false, idempotentHint=false), so the description needn't restate safety. It adds that results are limited to cities with flights, which is useful scope context, but says nothing about result count limits, empty-result behavior, or whether prefix matching is case-sensitive.

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?

Two short sentences, zero padding, with the what-is-it sentence front-loaded and the consequence sentence second. Every clause earns its place.

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 one-parameter read-only lookup with an output schema and full annotation coverage, the description is nearly sufficient. Minor gaps remain around prefix-length/case handling and result limits, but nothing blocks correct invocation.

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% and the schema itself gives the prefix semantics with examples ('Lond', 'Sev'). The description adds no syntax beyond the schema, aside from the downstream 'use the exact name' note, so the baseline 3 applies.

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 and resource ('Find city names') with a scoping constraint ('we have flights for'), so the agent knows this is a lookup of serviced cities rather than arbitrary place search. It implicitly distinguishes itself from search_flights, but never names it or the other siblings explicitly.

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?

'Use the exact name in the other tools' tells the agent this is a resolution step whose output feeds downstream calls, which is real usage context. It does not, however, say when this is unnecessary or contrast it with plan_trips/search_flights as alternatives, so it falls short of explicit when/when-not routing.

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

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

The annotations declare openWorldHint=false, i.e. a closed-world tool, yet the description states a destination is "checked against the airlines live when its prices are missing", which describes exactly the kind of external live lookup that openWorldHint=true covers. That is a direct conflict between the stated behavior and the supplied annotation, so the description cannot be credited for behavioral transparency even though it usefully explains the date-window and live-fallback semantics.

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?

Two tight sentences, front-loaded with what is returned (cheapest one-way flights) before the fallback behavior. No filler, though the live-check clause is dense and would read better as a separate sentence.

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 description covers fare criterion, trip shape, date window, and destination-omission. What is missing is the relationship to plan_trips/save_trip and any hint about freshness or caching of results, leaving the agent to guess about result provenance.

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 100%, so all five parameters are already documented and the baseline is 3. The description adds only the framing that date_from/date_to define a departure window rather than exact dates; `to`, `from`, and `limit` semantics are entirely carried by the schema.

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?

"Cheapest one-way flights between two cities, or from one city to anywhere" states a concrete resource, the fare criterion (cheapest), the trip type (one-way), and the two supported search shapes. It is clear on its own, but it never names or contrasts with siblings such as plan_trips, so an agent must infer the boundary between searching fares and planning a trip.

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 implied rather than stated: omitting `to` means "search anywhere", and the date fields are framed as a departure window, which tells the agent how to shape a query. There is no explicit when-to-use/when-not guidance and no named alternative (e.g. use plan_trips when you need a multi-leg itinerary), which is the main gap given the sibling set.

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