Compare hotels by travel time

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so safety is covered; the description adds genuinely new behavior: prices are carried over from the originating search with source, fetch time and dates (staleness disclosure), and no fresh pricing call is made. It stops short of describing rate limits or failure behavior when a place name fails to resolve.

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?

Three dense sentences with no filler, front-loaded with purpose before inputs, then outputs, then the pricing caveat. Slight redundancy in restating the return payload ('time and distance to every place, total minutes, ... rank by total minutes') when a full output schema already exists.

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?

Inputs, output contents, price provenance and the boundary against get_hotel_rates are all covered, and return-shape detail is backed by an output schema. Nothing an agent needs in order to call it correctly 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%, so the baseline is 3, but the description adds real semantics beyond the schema: the either/or rule for hotels (hotel_id from search_hotels vs name + lat/lng) and the accepted place identifier forms (lat+lng, station code, IATA, place name). It does not explain the drive/walk traffic allowance beyond what the enum description already says.

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?

States a specific verb and resource ('Compares up to 10 hotels by travel time to a set of labelled places') and enumerates the input forms, so an agent can distinguish it from search_hotels and travel_times without opening a schema. The scope (max 10 hotels, max 6 places) is explicit.

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?

Gives clear context for use: hotel_ids come from search_hotels, and it explicitly says 'Does not fetch new prices; get_hotel_rates does,' naming the alternative and the condition that selects it. It does not, however, contrast itself with the travel_times sibling, which could plausibly be confused for the same job.

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