hotels_search

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

No annotations are provided, so the description carries the burden. It explains the output structure (normalized property cards with per-night and per-stay prices, review score, etc.), which is useful. It also states prices are live rates for the requested dates. However, it doesn't mention pagination behavior, default page size, or other response details beyond what's listed. The schema already covers inputs; the description adds some behavioral context but not exhaustive.

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 compact yet information-dense. It front-loads the core purpose, then details output and input constraints. Every sentence adds value: first states what it does, second describes the output fields, third explains the dual-input mechanism, fourth clarifies price behavior. No filler.

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 schema covers parameter structure and the description explains usage semantics, the tool is well-specified for an agent. Potential gaps: no explicit guidance on pagination (page and page_size), no mention of default locale/currency, and no example values for check_in format. However, the tool is a search endpoint, and the output schema is absent (the description lists return fields, which suffices). Overall, it's quite complete but could add a sentence on optional parameters like page_size.

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 100% (the schema has a nested 'request' object with a description 'Search request'), but the description adds crucial semantics: the constraint of exactly one of query or region_id, the meaning of region_id (skips typeahead), and the date-bound nature. It also clarifies that check_in and check_out are required (though schema shows required within request). Since the description elevates the schema's flat property list into a coherent usage model, this is high value.

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 the tool searches Hotels.com hotels, with specific details on input methods (query or region_id) and output (property cards with prices, review scores, etc.). It distinguishes itself from sibling tools like hotels_property and hotels_rates by focusing on date-bound search results.

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 explicitly instructs to provide exactly one of query or region_id, and explains the advantage of region_id (skips destination typeahead). It does not name alternatives but the sibling tools like hotels_property suggest a clear separation of concerns (search vs. specific property).

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