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

Annotations already declare readOnly/idempotent/closed-world, but the description adds behavior the annotations cannot express: an unknown or invalid slug returns a "no route was found" error, and price tiers are indicative 'from' prices pending team confirmation. The data caveat on pricing is exactly the kind of trust context an agent needs before quoting numbers to a customer.

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?

Front-loaded with purpose and prerequisite before the return-value inventory, and every sentence carries information. The long enumeration of returned fields (price tiers, travel time, border crossings, car-change steps, capacities, inclusions, FAQs, booking links) is slightly list-heavy but substitutes for a missing output schema, so it largely earns its space.

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?

There is no output schema, so the description carries the return-value burden and does so thoroughly, including pricing caveats, error behavior, and the booking handoff. For a single-parameter read tool with full schema coverage, nothing material is missing.

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 coverage is 100% and the single parameter is already documented with an example, so the baseline is 3. The description adds provenance (the slug must come from search_routes) and failure semantics for a bad slug, which is real meaning beyond the schema, though it does not add format or normalization guidance beyond the schema's example.

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?

Opens with a specific verb+resource ("Returns full details for one route") and immediately scopes it to a single route identified by a slug, which cleanly separates it from search_routes (many results) and create_inquiry (booking). An agent can identify the tool's job without reading the schema.

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?

States the prerequisite explicitly ("Needs a slug from search_routes") and gives a fallback instruction ("If you do not have a slug, call search_routes first"). It also names the downstream sibling with its trigger condition: "Call create_inquiry when the customer wants to book." Both when-to-use and when-to-switch are covered.

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