Explore destinations

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, yet the description goes well past them: sequential per-airport execution for metro origins with merged cheapest fares, rate-limit truncation of remaining airports, top clamped to 30 with a warnings entry, and deadline_seconds producing error code deadline rather than an empty result. It loses a point for unexplained internal jargon (Viajante, not_loaded, provider_empty) that an outside agent cannot map to observable output.

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?

There is no filler and the first sentence is front-loaded, but the middle collapses into a dense run of semicolon-chained fragments ('A metro origin (MIL, NYC, and the rest of the owned table) runs one explore per member airport...') that is hard to parse on a first read. The trailing deadline_seconds paragraph is oddly indented and disconnected from the flow.

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?

An output schema exists, so return values need not be described, and the not_loaded/empty distinction is a genuine contribution. But for a tool with 38 parameters and zero schema descriptions, the description documents a small fraction of the input surface, so an agent cannot confidently set most filters.

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% across 38 parameters, so the description carries the full explanatory burden and largely does not. It clarifies only start/month mutual exclusivity, the top>30 clamp, and that origin_airport is populated on merged metro results; sort, cabin, max_stops, price_cap, layover bounds, exclude_* filters, passenger counts, and the rest get no meaning at all.

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 opening sentence names both the resource (destinations from one origin) and the two-stage shape (then a priced shortlist), which is more specific than the title alone. It never explicitly contrasts itself with search_flights or search_flex, though it borrows terminology (currency/country) from search_flights, so sibling differentiation stays implicit.

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?

There is real usage guidance: 'Give start (ISO date) or month, not both', 'Needs the browser extra', 'one adult in economy only'. Those are hard constraints an agent must know before calling. But there is no statement of when to choose this over search_flights or search_flex, and no exclusions pointing at alternatives.

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