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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds real behavioral context beyond that: `near` is resolved against both city and airport datasets, and the result carries a city code rather than an airport code. It stops short of describing distance ordering or pagination limits, which keeps it from 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 short paragraphs, each doing distinct work: what it does, when to use it versus the sibling plus the downstream handoff, and the input-mode selection. The scoping and routing guidance is front-loaded and no sentence is filler.

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 and annotations covering the safety profile, the description only needs to carry purpose, usage routing, and input-mode selection — all of which it does. An agent has everything required to choose and call this tool correctly.

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 already documents each parameter, including the override relationship ('latitude ... Overrides `near`'). The description restates the either/or selection of `near` versus a lat/long pair but adds no format, unit, or constraint detail beyond the schema, 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 airports closest to a place or coordinates) and immediately contrasts with the sibling lookup_airports, which only matches names. An agent can distinguish the two without opening either 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?

Gives an explicit trigger ('when the user asks which airport to fly into for a town, a resort, or a point on the map'), names the alternative tool and why it fails for this question, and routes the downstream step (feed the returned city code, not airport code, to search_flights). Nothing is left to inference.

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 readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds scope ('nearby airports and cities') but no extra behavioral detail such as caching, pagination, or result freshness. Adequate but not rich.

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, front-loading the purpose and then the routing guidance. No wasted text, though it is slightly denser than strictly necessary.

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 no explanation, and annotations cover safety. The description supplies the selection logic relative to siblings, making it complete enough for 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 description coverage is 100%, so all seven parameters (origin, destination, dates, currency, market, limit) are already documented. The description adds no meaning beyond the schema, 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 ('Get prices for nearby airports and cities around a chosen route') with clear scope. It is immediately distinguishable from search_flights (named city pair) and find_nearest_airports (airport discovery).

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?

Explicitly says when to use it ('when the traveller can fly from or into a different airport') and routes to alternatives: find_nearest_airports for discovery and search_flights for the exact city pair. Nothing is left to inference.

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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds useful context that results include fares and dates, but discloses nothing about pagination, result limits, or currency behavior beyond what's in the schema.

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, front-loaded with the core action and immediately followed by routing guidance. No filler or repetition of schema content.

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-value details need not be spelled out; the description covers action, scope, and sibling routing for a two-parameter read-only tool. Nothing an agent needs to select or call it 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 both parameters (origin IATA, currency) are already documented in the schema, including the pointer to lookup_cities. The description's 'from a city' adds no meaning beyond the schema's 'Origin city IATA code'.

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 ('List the cheapest destinations reachable from a city') plus scope ('with a fare and dates'), and explicitly distinguishes itself from the similarly-named siblings get_popular_directions and get_alternative_directions.

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?

Gives an explicit when-to-use condition ('user asks where they can fly from a city, or wants somewhere cheap without naming a destination') and routes to named alternatives (get_popular_directions for inbound, search_flights/get_prices_calendar for pricing a chosen route).

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 (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely useful scope context — roughly a week of dates around both outbound and return — which the annotations do not convey. It stops short of describing caching behavior or result volume, keeping it at a 4.

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, front-loaded with the action, then the usage trigger, then the alternatives. Every sentence earns its place with no redundancy.

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 carry the safety profile. For a read-only, fully-documented 10-parameter query tool, the description covers what an agent needs to select and call it correctly.

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 schema already documents all ten parameters including the adult/child/infant breakdown and date formats. The description only implicitly touches depart_date/return_date via 'days around', adding little beyond the schema. 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 ('Compare prices for the days around a departure and an optional return') and immediately contrasts itself with two named siblings. An agent can distinguish it from search_flights and get_prices_calendar 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?

Gives an explicit trigger ('user already has dates and asks whether shifting a day either way would be cheaper') and routes the two adjacent cases to the correct alternatives with their selecting conditions. Nothing is left to inference.

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 cover the read-only, idempotent safety profile, so the bar is lower, but the description adds real behavioral context: rows are cached v2-shape data naming an agency rather than an airline, lack flight numbers, and have reconstructed booking_links. The only thing not addressed is pagination/ordering of results, which is minor given the output schema exists.

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 paragraphs: purpose and scope first, the routing alternative second, the data-shape caveat last. Every sentence adds information an agent needs; nothing is redundant.

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 10-parameter read tool with full schema coverage, full annotations, and an output schema, the description fills the remaining gaps: routing to the correct sibling and warning about the legacy v2 row shape. Nothing material 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 coverage is 100%, so every parameter is already documented in the schema, and the output schema covers the response. The description adds only incidental parameter-relevant notes (per-adult pricing, passenger details encoded in booking_link), not syntax or format guidance beyond the schema. Baseline 3 is appropriate.

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?

Names a specific verb (get) and resource (latest flight prices from other travellers' searches), and explicitly contrasts itself with search_flights. An agent can disambiguate it from all twelve siblings 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?

Gives an explicit trigger ('when the user wants the latest fares that just appeared') plus a named alternative ('For a specific trip on chosen dates use search_flights instead'). Both the use and the when-not-to-use case are stated.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds the result shape (cities plus a fare) and the direction semantics (origins into the destination), which is real value beyond annotations, but it says nothing about rate limits, locale/currency defaults, or result volume.

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 paragraphs; the capability statement is front-loaded and the routing guidance follows with zero filler sentences.

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 the description plus annotations and full schema coverage give everything an agent needs to select and invoke it correctly.

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%, including the required IATA code and locale/currency defaults, so the schema carries the parameter burden. The description only reiterates that the request is keyed on the destination, adding no format or syntax detail beyond 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?

Specific verb+resource: lists origin cities for flights into a destination, with fares. It explicitly distinguishes itself from get_city_directions and search_flights, so the agent can route correctly without opening 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?

States when to use it ('where travellers reach a city from and what that costs'), the keying ('the request is keyed on the destination'), and names two alternatives with the condition that selects each ('where someone can fly from a city' vs 'prices on one known route').

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: prices are cached, quoted per adult, and passenger counts are encoded into the booking_link rather than affecting the returned fare. It stops short of describing coverage limits or freshness of the cache, so it is not 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 short blocks: what it returns, when to use it versus siblings, and pricing/param caveats. The routing rules are front-loaded before the caveats, and no sentence is redundant.

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 and rich annotations, the description does not need to explain return values, and it covers usage, code semantics, and pricing basis. The only mild gap is the absence of any note on cache staleness or result scope given the market parameter selects a cache.

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. The description goes one step further by telling the agent that the location fields are IATA codes and that lookup_cities must be used to resolve plain names first, plus clarifying that passenger parameters are baked into booking_link rather than the quoted price — details the schema does not spell out.

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 specific verb and resource ("Get grouped calendar prices for a route") and immediately clarifies the granularity of the result ("one fare per day or per month"), which maps directly to the group_by enum. It is clearly distinguishable from siblings like search_flights and get_flexible_date_prices 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?

It states the exact scenario for this tool ("which day or month is cheapest to fly a known route") and then names two alternatives with the conditions that select them: search_flights for one specific date, get_flexible_date_prices for a few days either side. It also routes to lookup_cities when codes must be resolved from a name.

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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered without description help. The description adds only routing context, disclosing nothing about result caps, dataset ordering, or locale-dependent output beyond what the schema states. Adequate but adds little behavioral value.

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 paragraphs; the capability statement is front-loaded and the sibling routing follows, with zero filler. Every sentence 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?

An output schema exists, so return values need not be explained, and the annotations carry the safety semantics. With all three parameters documented in the schema and clear routing, nothing an agent needs to invoke this correctly 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%: search (name substring or exact IATA), locale, and limit are all documented in the schema with examples and defaults. The description's mention of 'name or IATA code' restates the search parameter rather than adding syntax or edge-case guidance, 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 ('Look up airlines') plus the two lookup keys (name or IATA code), immediately telling the agent what entity this resolves. It is clearly distinguished from lookup_airports, lookup_cities, lookup_countries, and search_flights, all of which are named 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?

Gives the triggering condition ('user asks which airline a code belongs to, or wants the IATA code for an airline name') and routes the agent away from this tool for airports, cities, countries, and fares by naming the correct alternatives. Nothing about when-not-to-use is left to inference.

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 read-only, idempotent, open-world and non-destructive, so the safety profile is covered. The description goes further, disclosing dataset scale (~10k), the consequence of an unfiltered call (first `limit` in dataset order), and the ranking order with 'can't fly to' airports last. This is rich behavioral context beyond annotations; only return-shape detail is missing, and an output schema exists.

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?

Front-loads the core verb and keys, then the routing rule, then the operational caveat and ranking order. Four tight clauses, each earning its place with no filler.

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 three-parameter lookup with annotations and an output schema, everything an agent needs is present: when to call it, when to call the sibling instead, the mandatory search argument, and how results are ranked. Nothing material is omitted.

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 parameters are already documented. The description adds meaning beyond the schema by giving examples of each search key (name substring, exact IATA code, city code) and by stating that an unfiltered call behaves differently from a filtered one, which informs how to use `limit`.

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 clear verb and resource ('look up airports') and specifies the three lookup keys (name, IATA code, city code). It explicitly distinguishes itself from the sibling find_nearest_airports, so an agent can route correctly without opening either 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?

Provides explicit when-to-use ('user names an airport or code and needs city/country/coordinates') and when-not (redirects to find_nearest_airports for towns not sharing the airport's name). It even adds an operational constraint: always pass search. Nothing is left to inference.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the ~9.6k city dataset means search must always be supplied, and names are locale-bound ('searching "Мюнхен" needs locale="ru"'), which is a real failure mode an agent would otherwise hit.

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?

Front-loads the purpose, then routes to alternatives, then closes with the two operational constraints. Every sentence carries information; nothing is restated from the schema 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?

An output schema exists, so return values need no explanation. Combined with full annotation coverage and complete parameter descriptions, the description supplies exactly the missing pieces: sibling routing, dataset scale, and locale-dependent matching.

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 meaning beyond the schema: it explains why `search` should always be passed and that `locale` gates which name spellings will match. `limit` is left to the schema, which documents it fully, so no gap remains.

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 (look up) and resource (cities) plus the output contract: the IATA code flight tools expect. It explicitly distinguishes itself from lookup_airports and find_nearest_airports by name, so an agent can route correctly 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?

Gives an explicit when-to-use condition ('when the user names a city and a flight search needs its IATA code'), names two sibling alternatives with the conditions that select them ('for an airport code use lookup_airports', 'for the nearest airport to a place that is not itself a city, use find_nearest_airports'), and adds the imperative 'always pass search'.

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 carry readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured fields. The description adds only light behavioral value: the scope exclusion about flight prices and the fact that currency is returned. No pagination or locale behavior is disclosed.

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 with the primary capability front-loaded and the sibling routing in the second. No filler or restatement of the tool name.

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 and rich annotations, the description only needs to carry purpose, usage context and sibling routing, all of which it does. Nothing required for correct invocation 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 limit, locale and search are already documented in the schema. The description mentions the two accepted lookup forms but adds no format or constraint detail beyond what the schema provides; 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+resource ('Look up countries') and the two acceptable input forms (name or two-letter country code). It also names the sibling tools it is not (lookup_cities, lookup_airports), so an agent can distinguish it 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?

Explicit activation conditions are given ('when the user asks which country a code belongs to, or wants that country's code or currency'), plus named alternatives for the confusable cases and an explicit exclusion ('this tool does not search flight prices').

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?

Goes well beyond the annotations by disclosing that fares come from a cache, that pricing is per adult in economy, and — importantly — that a date argument is deliberately absent because the endpoint ignores one, verified empirically, with each result carrying its own `departure_at`. It doesn't mention result ordering, staleness windows, or rate limits, so it stops short of 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 short sentences with the core behavior front-loaded, followed by the usage router and then the non-obvious date caveat. Every sentence carries distinct information; no preamble or restatement of the title.

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 formatting is unnecessary, and the description covers what an agent needs to choose and call the tool: scope, routing to siblings, the intentional absence of a date param, and the interpretation of the price bounds. Nothing material is missing for a 7-param read-only search.

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 baseline is 3, but the description adds real meaning: omitting `destination` switches the tool to an anywhere/budget-driven mode, and price bounds are framed as per-adult economy fares in the active currency. These contextualize otherwise mechanical min/max fields.

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 flights whose cached fare falls inside a minimum and maximum price'), naming the exact retrieval mechanism (cached fare) rather than a generic search. It explicitly differentiates itself from `search_flights` and `get_prices_calendar`, so an agent can pick it 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?

Gives an explicit trigger ('when the user has a budget, including anywhere under a price with no destination named'), an explicit parameter rule ('Leave destination unset to let the budget pick the city'), and names the two sibling alternatives plus the condition that selects them. Nothing is left to inference.

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 readOnly/idempotent/non-destructive, so the bar is lower. The description still adds non-obvious behaviour: prices come from a cache of recent searches, are always PER ADULT in economy, and the party size/trip class are only encoded into the booking_link. That is a genuine gotcha an agent would otherwise mis-handle. It stops short of describing result-paging or no-results behaviour.

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?

Front-loaded and well-paragraphed: purpose, then sibling routing, then prerequisites, then caveats. Slight redundancy in the closing 'Durations' paragraph, which explains return fields already covered by the output schema, but every other sentence drives a routing or invocation decision.

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 15-parameter, open-world search tool this is complete: routing, prerequisites, passenger/pricing semantics, and multi-leg handling are all covered. Safety is carried by annotations, parameter detail by a 100%-covered schema, and return shape by the output schema, so nothing an agent needs to call it correctly 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 coverage is 100%, so baseline is 3, but the description adds real meaning beyond it: the passengers/trip_class parameters do NOT change the returned price, they only pre-fill the booking link and reveal the true total. The IATA-code constraint on origin/destination is also reinforced in prose. It adds semantics the schema's field descriptions do not convey.

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?

Opens with a specific verb+resource+scope: 'Search flight prices between two cities on a date or across a month.' It immediately distinguishes itself from four named siblings (get_prices_calendar, get_flexible_date_prices, search_by_price_range), so an agent can route 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?

Explicit when-to-use ('user names both ends of a route and wants fares, a booking link, or only departures inside a time window') plus named alternatives with the exact condition that selects each. Prerequisites are also stated: both codes must be IATA, call lookup_cities first, one call per leg for multi-city, get_alternative_directions for nearby airports.

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