Места в поезде

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

The description goes beyond the annotations by stating that prices and availability are fetched fresh on every call and that a seat could have been taken a minute ago. This warns about stale data and a race with train_book(), while remaining consistent with readOnlyHint, idempotentHint, and destructiveHint.

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 three short, purposeful sentences: one states the resource, one explains parameters and the internal seat format needed for booking, and one discloses freshness. Every sentence earns its place, with no repetition or 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 the output schema present and the workflow positioned between train_search() and train_book(), the agent gets the essential context for correct use, including the leading format '03/10,03/12'. The main missing piece is the semantic meaning of limit, and the defaults of car_type/max_price as 'no filter' are only implied.

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 input schema has 0% description coverage, so the description compensates: it explains train_id's origin, enumerates car_type values ('плац', 'купе', 'сид'), and defines max_price as an upper price bound. The only parameter not explained is limit, which is a real but minor gap given its default and optional nature.

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 states the resource (train carriages and free seats) and the expected output format ('carriage/seat'), and distils it from siblings by linking the input to train_search() and output to train_book(). It lacks an explicit verb like 'list' or 'get', but the intent is 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?

It explicitly places the tool in a workflow: train_id comes from train_search() and the seats format is what train_book() expects. There is no direct exclusion of alternatives such as train_calendar or flight_seats, but the upstream and downstream relationships are clear enough for an agent to know when to call it.

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