Planificar viaje

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

The annotations provide readOnlyHint=true and destructiveHint=false, so the safety profile is already clear. The description adds useful behavioral context: it notes the RAPTOR algorithm and mentions integrated fare, which signals what kinds of output the agent can expect. It could add departure time handling detail, but the readOnly annotation lowers the bar and the description adds meaningful algorithmic context.

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 a single compact sentence that front-loads the core purpose (plan journey between coordinates via RAPTOR) and then lists the key parameter value mappings concisely. Every clause adds value — no filler or repetition. It could benefit from structured formatting for the parameter lists but is efficient overall.

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?

The tool is moderately complex (8 params, journey planning with multiple output types), and an output schema exists which can document return values. The description covers the algorithm and the two most complex parameters (day, fare_type with their enums). However, with 0% schema description coverage, several parameters (departure_time, max_transfers, coordinate formats) have no documentation anywhere — the description should have compensated further given the annotation and schema coverage context.

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 0%, so the description must compensate. It explains day (L/S/D) and fare_type (normal/estudiante/adulto_mayor) mappings, which adds real semantic value. However, it does not explain the from/to coordinates format, max_transfers semantics, or departure_time format, leaving 6 of 8 parameters partially undocumented. The description covers the enum-like values but the coordinate/latency parameters rely on schema titles alone.

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 verb+resource: planning a public transport journey between two coordinates using RAPTOR. It specifies exactly what outputs to expect (alternatives with transfers, times, integrated fare) and distinguishes it from siblings that search stops, routes, or arrivals — this is the only tool that plans complete journeys.

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 opens with the core use case ('planificar un viaje') and explains the day and fare_type parameter value meanings. It provides clear context for when to use this tool versus the other transit data tools (which query stops/routes/arrivals vs. computing full itineraries). However, it does not explicitly state when NOT to use it or name specific alternatives.

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