Compare direct Shinkansen trains

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral note that it does not provide a subjective recommendation, which is useful context not present in annotations. However, it doesn't describe what happens to the input (e.g., whether it returns a new sorted list or modifies in place), though given readOnly and idempotent hints, this is largely implied. The description adds value but not deeply.

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?

Two sentences with no wasted words. The intent is front-loaded, and the clarifying statement about not making subjective recommendations is succinct and adds value without bloat. This is an appropriately concise description.

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?

Given the tool has 10 parameters (3 required) and schema coverage is only 20%, the description is far from complete. It doesn't explain what input structure is expected (though it says 'structured direct-train candidates'), how the tool integrates with siblings like search_trains, or the meaning of most parameters. While an output schema exists, the input semantics and usage context are inadequately described for an agent to call it correctly without additional information.

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 only 20%, meaning the description must compensate for the many undocumented parameters. The description explains the sort criteria (departure, arrival, duration, total fare) which maps to the sortBy enum, but it fails to explain other critical parameters like fromStationId, toStationId, date, limit, offset, operators, serviceTypes, and time filters. With 10 parameters and such low coverage, the description does not help an agent understand how to construct a valid request beyond the sort field.

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 clearly states a specific action: sorting structured direct-train candidates by departure, arrival, duration, or total fare. It distinguishes itself from recommendation tools by explicitly noting it does not make a subjective recommendation. However, it doesn't clarify whether the tool expects a pre-fetched list or fetches its own candidates, leaving some ambiguity about its exact role relative to search tools.

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 implies that the tool should be used when you have structured direct-train candidates and want to sort them, but it does not explicitly state when to use it versus alternatives like search_trains or search_journeys. It would benefit from a note like 'After search_trains returns candidates, use this to sort them' or an explicit exclusion of other tools. The note about not making a subjective recommendation gives a hint of what it does not do, but not when to choose it.

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