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

Annotations already cover readOnly and idempotent safety, and the description adds substantial behavioral context: it explains that the tool aggregates from multiple reservation systems, prices trains per class when train_class is omitted, adjusts departure day with arrive_by, and ranks modes together by default. It discloses that it includes government buses and that they may be the only through service. No contradictions with annotations; the description meaningfully extends beyond the structured metadata.

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 longer than typical but well-structured: purpose first, then bus-specific rationale, then parameter guidance. Every sentence contributes value, and it is front-loaded with the core function. While slightly verbose, it is not padded and reads coherently as a complete usage guide.

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?

For a read-only tool with 10 parameters and no output schema, the description covers all essential usage decisions: what results are returned, when to include buses, how to handle train class, modes, arrival-based timing, and the meaning of limit. It also directs the user to find_place for IDs. No critical context is missing for an agent to call the tool correctly.

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 90%, so the schema already documents most parameters. The description adds semantic depth for train_class (explains pricing behavior), modes (restriction semantics), and arrive_by (date interpretation), and clarifies that limit applies per kind. However, the quota parameter has no schema description nor any mention in the tool description, leaving a minor gap that the description does not compensate for.

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 the verb and resource: it plans a journey by enumerating all practical modes (direct trains, one-change journeys, flights, mixed, government buses). It explicitly contrasts with sibling tools by framing itself as the comprehensive 'whole answer in one call', and even references find_place for IDs, making its purpose distinct and 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 explicit when-to-use guidance, including a dedicated paragraph for bus questions and a concrete example (Mysuru–Mangaluru) where buses are the only through service. It also instructs when to pass train_class, modes='trains_only', and arrive_by, and even states not to ask the traveller to choose modes because the planner is designed to avoid that. This leaves no ambiguity about when to prefer this tool over siblings.

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