hotels_rates

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

No annotations are provided, so the description carries the burden. It discloses that the tool returns date-bound rates and availability, and clarifies the property_id is the numeric global id from Search, distinct from the legacy URL id. However, it doesn't disclose potential failure modes, rate limits, or what happens if dates are invalid or property_id is not found. It also doesn't mention whether the response includes taxes/fees or just base prices.

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 a single paragraph of three sentences, front-loaded with the core purpose. It efficiently explains what the tool returns and clarifies the property_id semantics. The only slight inefficiency is the phrase 'the same normalized property card Search returns' which could be more direct, but it's still compact and informative.

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 tool has one nested parameter and no output schema, the description provides a reasonable overview but lacks details on the request object's structure and the exact response format. It explains the return type conceptually (normalized property card with prices) but doesn't specify required fields within the request, date formats, or how availability is represented. For a tool with a nested request object, more detail on the request structure would improve completeness.

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% but the only parameter is a nested 'request' object with a generic description 'Rates request'. The description adds meaning by explaining property_id is the numeric global id from Search's properties[].id and distinct from the legacy URL id, which is valuable. However, it doesn't detail the structure of the request object (e.g., how to specify dates, property_id field name), leaving the agent to infer the nested 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 description clearly states the tool gets Hotels.com rates for one property, with a specific verb ('Get'), resource ('one property'), and scope ('date-bound rates and availability'). It distinguishes itself from sibling tools like hotels_search and hotels_property by specifying it returns the same normalized property card with live per-night and per-stay prices for requested dates.

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 implies when to use this tool: when you need rates for a specific property and dates, and it references Search responses for the property_id. It doesn't explicitly state when not to use it or name alternatives like hotels_offers or hotels_property, but the context of needing live date-bound rates is clear enough for an agent to select it.

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