Get lowest hotel prices

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

Annotations already cover the safety profile (readOnly, non-destructive), so the description's additional value is in disclosing the return shape: minimum rate only, price/currency/availability, and an explicitly lighter/faster payload than the full rates call. It does not mention auth, rate limits, or error behavior, which is a minor gap for an openWorld tool.

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?

Five markdown sections for a single lookup endpoint, with heavy repetition: 'Perfect for displaying price comparisons,' 'Perfect for listings,' and 'ideal when displaying multiple hotels' all say the same thing. The Quick Start paragraph restates parameters already covered by the schema. Front-loading is decent but the padding is substantial.

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?

No output schema exists, but the description compensates by describing the returned fields (minimum rate, price, currency, availability), which is what an agent needs. Combined with 86% schema coverage and clear annotations, the definition is nearly sufficient, though it omits timeout usage and any error/empty-result behavior.

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 86%, so the schema already documents nearly every parameter including date format, currency, and occupancy structure. The description only restates 'hotel IDs, dates, and guest occupancy' and claims parameter parity with the main rates endpoint, adding minimal semantics beyond 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?

States a specific verb (get) and resource (cheapest available rate for each hotel) and explicitly scopes it against the fuller alternative, noting the same parameters as 'the main rates endpoint.' An agent can distinguish this from post_hotels_rates without opening either schema.

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 'When to Use' section gives concrete contexts (listing pages, quick comparisons, price sorting) and a when-not condition ('when you only need the lowest price, not all rate options'). It implies rather than names the sibling post_hotels_rates, so it falls just short of fully explicit routing.

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