LastBilet — flight search

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the description's added value is provenance and reliability: data comes from a cache of user-found fares from recent days and prices are explicitly approximate. That is exactly the kind of behavioral context annotations cannot express. Minor gap: nothing about result caps via limit or what an empty result looks like.

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?

Four compact sentences ordered by importance: what it is, the no-destination variant, the accuracy caveat with the alternative, then use cases. Zero filler and no repetition of the 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?

For an 8-parameter read-only lookup with no output schema, the description covers everything an agent needs to call it correctly: accepted date granularity, the two modes, approximate pricing, and the route to a precise alternative. Remaining per-parameter details are adequately carried by the schema.

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 75%, so the schema already carries most parameter meaning. The description adds real semantics beyond it by explaining that omitting destination switches the tool into a destination-ranking mode — a behavioral effect the schema only hints at via 'для подборки направлений'. It leaves direct_only (no schema description) and limit unaddressed.

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 — cached minimum prices from LastBilet for a date or month — and immediately explains the two operating modes (with destination = route price, without destination = 'where to fly cheaply' ranking). It also explicitly contrasts itself with search_flights for exact/baggage-inclusive prices, so an agent can distinguish it from 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 clear when-to-use triggers ('гибких дат, бюджета, вдохновения') and an explicit alternative for the exact-price case ('точные и с багажом даст search_flights'). It does not differentiate from price_calendar, which is arguably the closest sibling for date-flexible browsing, and gives no guidance on when the cached data is too stale to trust.

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=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful return behavior beyond that: it returns the city's airports plus nearby airports within a 250 km radius, which is genuine behavioral context.

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 with the core purpose, then the fuzzy-match capability, then the radius/use-case note. Two clauses with no page-filler; the parenthetical examples are brief and earn their place by clarifying the 'nearest airport' behavior.

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?

There is no output schema, so the description carries the burden of explaining returns (city airports + airports within 250 km), and it does so adequately. It leaves finer details like result ordering or result count unspecified, but nothing critical to invoking the tool 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?

With 100% schema coverage the baseline is 3, but the description adds real semantics the schema lacks: the query tolerates typos and accepts both Russian and English input. That materially expands how an agent can phrase the 'query' parameter beyond the schema's bare 'Название города или аэропорта'.

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 ('найти город или аэропорт и его код IATA') plus the lookup key ('по названию'). Clearly distinguishes itself from flight-search siblings like search_flights, cheapest_prices, and get_booking_link, which operate on routes rather than place resolution.

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 concrete usage context: useful when the city has no airport (Паттайя, Анапа зимой) or when a neighboring airport is cheaper. It stops short of explicitly naming an alternative sibling for comparison, but the when-to-use conditions are clear and actionable.

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new behavior: the link lives ~15 minutes after the search, and on expiry a fresh search link at lastbilet.ru is returned instead — useful TTL and fallback semantics. It says nothing about auth or rate limits, hence 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 sentences with no filler, ordered purpose → lifetime/fallback → trigger, so the most decision-relevant facts come first.

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?

There is no output schema, and the description does explain what comes back (a link to the agency/airline site, or a fallback search link). Combined with the explicit call trigger and annotations, an agent has enough to invoke it, though the two required IDs remain unexplained.

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 both parameters, and it does not. It only hints that offer_id/search_id derive from a 'выбранного варианта из search_flights', leaving the exact meaning and pairing of the two required IDs to inference.

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: it returns a purchase link for the variant the user selected, and it names search_flights as the source of that variant, which separates it from siblings like cheapest_prices or price_calendar. An agent can tell what this tool produces without opening the 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?

The trigger is explicit: 'Вызывай, когда пользователь выбрал вариант' (call it once the user has picked an option). It also implicitly chains from search_flights, but it states no exclusions or what to do when the user has not yet selected, so it stops short of a full when/when-not/alternatives statement.

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, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds real value beyond them by disclosing the data source ('Данные из кэша LastBilet'), implying cached, possibly stale results, and by noting flexible-date (±) behaviour in day mode.

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?

A single dense sentence that front-loads the resource and then splits into the two modes; nothing is wasted. It is compact rather than padded, though the mode split could be slightly more scannable.

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 read-only, cache-backed lookup with no output schema and no nested objects, the description covers both output granularities and the data source. The only meaningful omission is the undocumented direct_only flag, which no other structured field explains.

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 75%, with origin/destination and month documented in the schema. The description reinforces the meaning of the month switch and adds flexible-date semantics for day mode, but the 25% gap (direct_only) is undocumented in both schema and description. Baseline 3 for good schema coverage plus marginal added meaning.

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 resource and output shape: a minimum-price calendar by route, with two distinct modes (day-level with month, month-level without). It does not differentiate itself from the sibling cheapest_prices, so an agent cannot tell from this text alone which of the two price tools to pick.

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 two operating modes are spelled out (pass month for per-day prices; omit it for a year of monthly prices), which is useful conditional guidance. However there is no when-to-use vs when-not-to-use framing and no pointer to alternatives such as cheapest_prices or search_flights.

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, destructiveHint=false, openWorldHint=true), but the description adds genuinely non-obvious behavior: a 10–30 second latency expectation, 15-minute result caching, and the ability to change filters without triggering a new search. That is meaningful operational context beyond the structured fields, though it omits anything about rate limits or failure modes on no-results.

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 purpose, then usage routing, then return shape and caching in a single dense paragraph with no filler sentences. It is on the long side and could be broken up, but every clause carries distinct information.

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 compensates by describing the response structure (summary of min price / direct / with-baggage / fastest, plus variants each carrying offer_id) and the caching/change-filters behavior. Combined with the readOnly annotation, an agent has everything needed to invoke and interpret this call.

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 89% across 18 parameters, so the schema already documents nearly every field (dates, pax counts, stops, transfer exclusions, time windows). The description does not add format or semantic detail beyond that, so the baseline of 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?

States a specific verb and resource ('Живой поиск LastBilet на конкретные даты') and frames it as the live search form for fixed dates, which immediately separates it from calendar/price-comparison siblings. The description also enumerates the richness of offers returned (baggage, transfers, payment), so an agent knows exactly what class of operation this is.

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 gives the when-to-use condition ('когда известны даты') and names the two alternatives for flexible dates ('для «когда дешевле» и гибких дат сначала price_calendar или cheapest_prices'). It even routes the agent forward to get_booking_link for the resulting offer_id, leaving nothing 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=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine non-obvious context: the forecast horizon is capped at 16 days, climate values are 5-year averages, sea temperature is included, and the FX rate is the Central Bank rate — real behavioral limits the annotations do not express.

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?

A single front-loaded sentence that opens with the subject (destination reference for a Russian tourist) then lists the payload items. Dense but with no filler; a short second sentence about limits or output shape would have helped, but nothing here is wasted.

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 describing returns, and it does so item-by-item (visa, weather, time zone, currency/FX). It stops short of stating the response structure or behavior for unknown destinations, but an agent has enough to 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 baseline is 3. The description goes further by explaining the semantics behind the parameter choice: date_from/date_to yield a forecast (limited to 16 days) while month yields 5-year climate averages, which tells the agent why the month fallback exists and when each 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?

The description names a specific resource (destination reference data) and enumerates the exact payload: visa requirements for RF citizens, weather forecast or monthly climate, time difference with Moscow, local currency and CB exchange rate. This is clearly distinguishable from siblings like search_flights, cheapest_prices and find_city, which are transactional rather than informational.

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 only implied: the forecast-vs-climate wording hints that exact dates select a forecast and a bare month selects averages, but there is no explicit when-to-use statement or named alternative. Siblings are adjacent (city lookup, pricing) yet no routing guidance is offered.

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