Места в самолёте

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

The annotations already mark the tool as read-only and idempotent, and the description adds important behavior: seats are paid but optional, skipping them does not prevent booking, and selected seats must be passed one per passenger in the same order. This is useful beyond what the structured annotations alone provide.

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 compact and front-loaded: the seat map purpose comes first, then input provenance, then the one critical workflow detail. There is no filler or repetition of what the schema and annotations already state.

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 output schema and annotations cover return values and safety, and the workflow context is well described. The main gap is the lack of detail around the limit and max_price parameters, which limits full completeness for an agent trying to use all available inputs.

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 explains offer_id and fare, which helps because the schema has no property descriptions. However, limit and max_price are left unexplained, and max_price's default of 0 is ambiguous without more context, so the description does not fully carry the parameter-semantics burden.

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 name and first phrase clearly identify a seat map for a flight with prices ('Карта мест в салоне с ценами'). It ties the tool to flight_search() and flight_offer(), which distinguishes it from siblings like train_seats and cinema_seats while making the resource unambiguous.

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 the exact workflow placement: take offer_id from flight_search(), take fare from flight_offer(), and pass selected seats into flight_book(). It also gives an implicit when-not-to-use by noting seats are optional and a row will still be assigned at check-in.

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