Оформление и оплата авиабилета

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

Annotations already mark the tool as destructive and non-idempotent, but the description adds much more: real money is spent in one step, a payment confirmation button appears, the client is refused without explicit elicitation, and the payment may be declined due to the unavailable travel session. The caveat that the signature was reconstructed but live payment was never executed is unusually explicit.

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 front-loaded with the most important safety facts and is structured in useful blocks. It is still long and contains engineering detail not needed for selecting or invoking the tool, such as key reconstruction details, HmacSHA256, and X-Detach-Key/Timeout headers, with repeated warnings that money will not move.

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 description covers the full flow of a high-stakes booking: confirmation, refusal, child exclusion, no refund, force retry, and fallback to the app. An output schema exists, so return values do not need to be described, but account_id semantics are missing and the description does not point agent to flight_seats() as the source for seat selection.

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 0% schema description coverage, the description compensates well: offer_id, fare, passengers, seats, and force are all explained with run behavior. However, account_id is never explained, leaving one of six parameters semantically unclear.

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 'КУПИТЬ авиабилет' and immediately states that the call is a single step that both books and debits money. It is clearly scoped to flight purchase, explains the distinction from separate booking/refund flows, and references flight_search() and flight_offer() as input sources.

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 explicit usage context: use the tool after offer_id and fare are known, show the final price and rules to the client, and let confirmation happen via the button. It explicitly excludes child bookings, refunds via MCP, and defines when force=True may be used after checking trips() and the app.

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