Поиск авиабилетов

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

Beyond the readOnly/idempotent annotations, the description discloses authentic operational details: fast first-batch behavior on the default path, a slow stream of thousands of partner offers when only_bookable=False, an experimental payment path that may fail, and an odd X-Travel-Context header not observed in normal traffic. This is unusually candid and behaviorally useful.

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 core purpose is front-loaded in the first sentence, and the rest is parsed into compact sections: code resolution, offer policy, booking/payment recommendation, and endpoint caveat. Every paragraph carries decision-relevant info; there is 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?

The search workflow is well covered: how to obtain codes, how to interpret only_bookable, and how the tool fits with flight_test, flight_offer, flight_seats, and flight_book. The return value is presumably covered by the output schema. The remaining gap is max_batches/limit not being connected to the described batch/stream behavior, which could confuse an agent when it wants to limit the result flow.

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?

The description adds meaning beyond the schema for from_code, to_code, date, and only_bookable, which are the most critical fields. However, the schema has 0% description coverage and 5 of 9 parameters (limit, adults, children, infants, max_batches) are left undocumented in both schema and description, forcing the agent to infer from titles and defaults.

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+resource pair (Поиск авиабилетов) and defines the core inputs: IATA codes and date format. It also distinguishes the flight workflow roles by naming flight_offer, flight_seats, and flight_book as sibling steps, so an agent can tell which tool does what.

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 explicitly tells the agent not to guess city-derived IATA codes and to take them from flight_history() instead. It also explains when only_bookable=True vs False should be used, and it clarifies that booking/payment belongs to flight_book and that reliable purchase goes through the app.

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