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

The description adds substantial behavioral context beyond the readOnly/openWorld annotations: suspended legs are included and flagged rather than excluded, seasonal/charter legs have no dates and no frequency data, matches should be treated as unverified for travel dates, and responses include Kiwi.com book links with referral ids and a default one-way search two weeks out. Nothing in the description contradicts 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?

The description is dense but tightly organized: purpose first, then response shape, then caveats, then parameter constraints, then link behavior. Every sentence carries distinct operational information and none is filler or repetition of the schema.

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 no output schema, the description carries the burden of explaining return contents (airport paths, per-airline alliance and kind, book deep links) and the limitations of the data (unverified dates, capped stops in country searches). For an 8-parameter, read-only discovery tool, this is a complete and actionable description.

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?

Even though the schema documents all 8 parameters, the description adds meaning the schema cannot convey: destination and to_country are mutually exclusive, exclude_kinds is the way to drop suspended legs, and depart_date/return_date only affect book links, with a default one-way search when depart_date is absent. This materially helps an agent set parameters correctly.

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 opens with a precise statement of what the tool does: it finds multi-stop itineraries from an origin to either a specific destination airport or any airport in a country, and returns airport paths with airline/alliance/kind details. This is specific enough to distinguish it from sibling tools such as airline_routes or route_details without needing to inspect their schemas.

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 gives clear context for when the tool applies (multi-stop itineraries, destination-or-country goal) and states the crucial mutual-exclusion rule: provide exactly one of destination or to_country. It also explains how to drop suspended legs with exclude_kinds. It does not explicitly name alternatives or say when not to use this tool, but the use case is unambiguous.

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