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

Annotations already declare read-only, open-world, idempotent, and non-destructive hints. The description adds useful context: unique inventory, hard-to-find data, and the return of operational status and canonical URL. It does not contradict annotations and enriches understanding beyond the structured hints.

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 concise, front-loaded with the main action, and includes practical example queries in a natural way. Every sentence adds value without unnecessary fluff, making it easy to parse quickly.

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 8 parameters, rich annotations, and presence of an output schema, the description is fairly complete. It explains the domain, use cases, and key return fields. It does not elaborate on pagination or response formats, but the structured data covers those, and the examples make the tool's scope clear. Slight gap: no explicit comparison to list_bus_routes.

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 88% with detailed descriptions for most parameters. The description mentions filtering by origin, destination, date, or free text, which re-states obvious schema information but does not add deeper semantics about parameter relationships or edge cases. It does not explain offset behavior, but the schema already covers that.

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 'Search bus schedules' with a specific region (Carretera Austral / Coyhaique) and highlights the unique inventory. This distinguishes it from sibling tools like search_accommodations or search_unified, making the purpose 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 provides concrete example queries ('cómo llegar a Caleta Tortel', 'bus Coyhaique a Chaitén') and context (hard to find online), which helps the agent know when to use it. However, it does not explicitly mention when not to use it or compare with alternatives like search_unified or list_bus_routes.

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