Search hotels

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

With readOnlyHint/idempotentHint already supplied by annotations, the description still adds substantive behavior: price_from is the lowest room price per night and often a single-bed room, stay_total applies when nights > 1, and status distinguishes available / min_stay / sold_out. The note that guests only adds price_for_guests for the first 12 cards is a genuine partial-result caveat an agent could not infer elsewhere.

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?

Purpose is front-loaded in the first sentence, followed by examples, then field semantics, then sibling routing - a sensible order. It is dense but nearly every clause carries information; only the parenthetical about the site showing the same figure is slightly redundant.

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?

For a 19-parameter search with no output schema, the description covers the essentials: what a result card contains (hotel, price_from, stay_total, status) and how to chain into the detail tools. It does not address the limit/pagination cap (max 60) or the kind=stay path, which are the remaining gaps.

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 84%, so the baseline is 3; the description earns more by explaining the price fields that the schema leaves ambiguous (price_from vs stay_total vs price_for_guests, Toman, per night) and by illustrating sort, min_stars, facilities and area with real values. Some parameters (kind, beds, board, name, max_price) are left entirely to the schema.

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 a specific verb (search), resource (hotels), scope (a city, given dates) and the return shape (cards with the lowest price). It is clearly separable from eg_rooms, eg_hotel and eg_reviews, which are named later in the text.

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 maps concrete user questions to parameter combinations ("cheapest 4-star in Kish" -> sort=price_asc, min_stars=4; "with a pool near the shrine" -> facilities, area), which tells the agent exactly when this tool fits. It also explicitly routes follow-ups: eg_rooms for room prices, eg_hotel for facilities/rules, eg_reviews for opinions.

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