Booking.com Hotel Search (Live Prices)

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

The description goes well beyond annotations by disclosing critical behavioral traits: 'Rates go stale within minutes: never reuse an earlier result.' This is a time-sensitive constraint not captured by readOnlyHint or other annotations. It also explains the semantic of price_as_seen_from, which is not in the schema. No contradiction with annotations.

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 front-loaded with the core purpose in the first sentence. It is structured into clear paragraphs covering usage, special parameter, and staleness warning. It is slightly verbose but each sentence adds value. Could be tightened by removing redundant phrases like 'Input: the hotel name a person would type' but overall efficient.

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 7 parameters (3 required), an output schema, and a sibling tool, the description covers the main workflow: how to input hotel name, dates, and the special price_as_seen_from parameter. It omits explanation of optional parameters adults/children/currency, but these are less critical. The staleness warning is a key completeness element. Mostly sufficient for correct agent usage.

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?

With 0% schema description coverage, the description compensates by explaining the meaning of hotel_name (adding city helps), checkin/checkout dates, and price_as_seen_from (country-specific pricing). It lacks explicit explanation for adults, children, and currency, but these are optional and partially inferable. The description adds significant value 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?

The description clearly states the tool's purpose: 'Get availability and pricing for one named property.' It specifies it handles a single hotel, distinguishes from the sibling 'search_hotels' by emphasizing 'one specific hotel' vs. general search. The verb 'get' and resource 'availability and pricing for one hotel' are precise.

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 provides clear usage context: 'Use it to check one specific hotel, or to track a single property's price over time.' It hints at when to use it versus alternatives by mentioning the sibling tool 'search_hotels' in the sibling list, though it does not explicitly state 'do not use for broad searches.' The guidance on adding city names for disambiguation adds practical value.

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

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

The description adds behavioral value beyond annotations by warning that rates go stale within minutes and advising against reuse. Annotations already mark readOnlyHint true and destructiveHint false, so the description complements this with lifecycle and data freshness info. No contradictions.

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 moderately concise: three short paragraphs. The first paragraph front-loads core purpose, inputs, and outputs. The second adds a unique parameter. The third warns about staleness. Each sentence adds value; no redundancy. Could be slightly tighter but is well-structured.

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 9 parameters and an output schema, the description covers the essential use case: searching by destination/date, highlights the unique geo-pricing parameter, and warns about data staleness. It describes output fields adequately. While it omits details on some optional parameters (filters, budget), the schema and output schema fill partial gaps. Overall sufficient for primary use.

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?

With 0% schema description coverage, the description must compensate. It explains destination (free-text), checkin/checkout dates, and the special price_as_seen_from parameter (two-letter country code). However, it does not explain adults, children, currency, filters, or budget_per_night, leaving gaps for those optional but potentially important parameters.

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's function: searching live hotel availability and nightly prices by destination and date range. It explicitly distinguishes from the sibling 'find_hotel_by_name' by implying this is for general searches and by highlighting a unique capability (price_as_seen_from) that no other tool has.

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 provides clear context on when to use the tool (for live hotel searches), input format (free-text destination), and important caveats (rates go stale, do not reuse). It does not explicitly say when not to use it (e.g., for specific hotel names), but the sibling tool name provides some implicit guidance.

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