Compare hotel prices, room options and booking providers with live HotelUse searches.
Scored across 3 tools
The three tools have genuinely distinct jobs: destination search, undated hotel facts, and dated room pricing. However, get_hotel and get_room_rates share large identical blocks of boilerplate about room groups, pagination, and follow-up handling, which blurs their boundaries and could lead an agent to pick the wrong one for a simple facts query. The first lines of each description do disambiguate, so it is workable but noisier than it should be.
All names follow a clear snake_case verb_noun pattern: search_hotels, get_hotel, get_room_rates. The get_* pair is consistent, and search_hotels fits the same convention. No camelCase or vague verbs are present.
Three tools map cleanly onto the core metasearch flow: find hotels, inspect a hotel, and price its rooms. It is lean but each tool earns its place. A small helper such as destination autocomplete would round it out without bloating the surface.
The surface covers the main lifecycle: search by destination or coordinates, retrieve static hotel facts, and fetch room-level rates with external booking links. Minor gaps exist, such as dedicated review retrieval or destination/name autocomplete, but agents can work around them via search results and the hotel tools.
Get undated facts for one identified or named hotel: address, photos, descriptions, star classification, sourced guest ratings, consecutive positive review count, facilities, pet/parking policies and timezone. Optional fee amounts may be absent in the catalog. Accepts the exact HotelUse hotel_id from a previous result, or hotel_name and destination. A unique, confident match is required. A full hotel name may be used without a destination; add the destination when ambiguous. No stay dates, availability, live prices or room-level offers are included. Supply exactly one hotel_id or hotel_name. Omit unknown optional values; do not send null. Resolve a hotel follow-up by name or position against the most recent relevant ordered search list. Copy its hotel_id exactly; if unavailable, use hotel_name and destination. Ask only if the hotel is ambiguous. For room options or current room prices call get_room_rates directly, passing search_quote_session_id from that search to preserve its stay and preferences. The first get_room_rates response includes all returned room groups and every provider minimum in room_groups. For all room options and prices, use that complete list after one call; do not paginate raw supplier offers or re-query the same stay. The raw_offer_page count describes supplier rate plans, not additional room types. Users can expand room cards locally without another price query. For undated amenities, policies or other hotel facts call get_hotel directly. Do not repeat a destination search before either hotel-specific tool. Existing returned prices may be explained without refreshing when no new search or current quote is requested.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No | Traveler BCP 47 language, such as en-GB, independent of the destination. | |
| region | No | ||
| country | No | ||
| hotel_id | No | Exact HotelUse hotel_id from a previous result. | |
| hotel_name | No | Hotel name when no exact hotel_id is available. A unique, confident match is required. A full hotel name may be used without a destination; add the destination when ambiguous. | |
| destination | No | City or region to disambiguate the hotel name. | |
| user_locale | No | Optional traveler locale from client context, such as en-GB. Independent of the hotel destination. | |
| user_location_country | No | Optional traveler country from client context, used for default currency and residency. Independent of the hotel destination. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered; the description adds genuine context beyond that: "A unique, confident match is required," optional fee amounts "may be absent in the catalog," and "do not send null." It stops short of describing what a failed/ambiguous match returns, which is the remaining gap.
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?
Front-loaded and purposeful in its first half, but the latter half drifts into lengthy instructions about get_room_rates pagination and raw_offer_page counts that belong to the sibling tool and dilute the call to action. Several sentences repeat the same idea (one call, don't re-query, expand cards locally).
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?
With 8 parameters, no output schema, and only 75% schema coverage, the description does the necessary work by enumerating the returned fact set and the match requirement. It is complete enough to call correctly; only the locale/region/country parameters and error behavior remain unexplained.
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 75%, and the description compensates by stating a cross-field constraint the schema cannot express: "Supply exactly one hotel_id or hotel_name," plus when destination is needed and to "Copy its hotel_id exactly." It does not explain the region/country/user_locale versus locale distinction, leaving part of the low-documented surface unaddressed.
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 and resource ("Get undated facts for one identified or named hotel") and enumerates the returned facts, immediately separating it from get_room_rates ("No stay dates, availability, live prices or room-level offers are included"). An agent can distinguish it from both siblings without opening a 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?
Explicit routing rules: use get_hotel for undated facts, call get_room_rates for room options/prices, "Do not repeat a destination search before either hotel-specific tool," and resolve follow-ups against the most recent ordered search list. It even specifies the fallback path (hotel_id, else hotel_name + destination) and when to ask the user.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one identified or named hotel’s room options and provider prices for explicit hotel-local dates (including today), or date_intent: tonight, and occupancy. Tonight is resolved server-side in the hotel time zone. Accepts the exact HotelUse hotel_id from search_hotels, or hotel_name and destination when the ID is unavailable; destination is optional but helps disambiguation. A unique hotel match is required. Returns server-grouped room types, rate terms and full-stay provider prices in a separate Room options view. Provider price links open external booking pages; no reservation is made. Providing search_quote_session_id inherits omitted dates, occupancy, currency, language, residency and rate filters from that exact search. Explicit itinerary changes create a new quote; the search device is preserved. Supply exactly one hotel_id or hotel_name. Supply check_in/check_out, date_intent, or an existing search_quote_session_id for room quotes. All returned room groups are included in the first response; no room pagination is needed. Omit unknown optional values; do not send null. Resolve a hotel follow-up by name or position against the most recent relevant ordered search list. Copy its hotel_id exactly; if unavailable, use hotel_name and destination. Ask only if the hotel is ambiguous. For room options or current room prices call get_room_rates directly, passing search_quote_session_id from that search to preserve its stay and preferences. The first get_room_rates response includes all returned room groups and every provider minimum in room_groups. For all room options and prices, use that complete list after one call; do not paginate raw supplier offers or re-query the same stay. The raw_offer_page count describes supplier rate plans, not additional room types. Users can expand room cards locally without another price query. For undated amenities, policies or other hotel facts call get_hotel directly. Do not repeat a destination search before either hotel-specific tool. Existing returned prices may be explained without refreshing when no new search or current quote is requested.
| Name | Required | Description | Default |
|---|---|---|---|
| rooms | No | ||
| device | No | Optional traveler device. Omission uses trusted client hints, then desktop. Room follow-ups inherit the effective search device. Mobile app rates require an approved native-app integration. | |
| locale | No | Traveler BCP 47 language, such as en-GB, independent of the destination. | |
| region | No | ||
| country | No | ||
| check_in | No | Hotel-local calendar date; today is allowed in the destination time zone, even after UTC midnight. | |
| currency | No | Requested display currency. Omission defaults to client visitor country, then locale, then USD. | |
| hotel_id | No | Exact HotelUse hotel_id from a previous result. | |
| check_out | No | ||
| providers | No | ||
| hotel_name | No | Hotel name when no exact hotel_id is available. A unique, confident match is required. A full hotel name may be used without a destination; add the destination when ambiguous. | |
| date_intent | No | A one-night stay resolved server-side in the destination or hotel time zone. Mutually exclusive with check_in/check_out. | |
| destination | No | City or region to disambiguate the hotel name. | |
| user_locale | No | Optional traveler locale from client context, such as en-GB. Independent of the hotel destination. | |
| rate_filters | No | ||
| residency_country | No | ||
| user_location_country | No | Optional traveler country from client context, used for default currency and residency. Independent of the hotel destination. | |
| search_quote_session_id | No | A search result’s search_session_id. Inherits omitted stay dates, rooms, currency, language, residency and rate_filters from that search. Its device is preserved even if current client metadata changes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, open-world, non-idempotent and non-destructive behavior, so the bar is lower. The description adds genuinely useful context: tonight is resolved in the hotel time zone, provider links open external booking pages with no reservation, a unique hotel match is required, and session inheritance preserves device and filters. However these points are restated repeatedly rather than expanded, so the marginal disclosure is thinner than the length suggests.
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, but the text is roughly twice the necessary length and loops: the 'all room groups are in the first response / do not paginate / do not re-query' point is made four or five separate times, and the hotel_id/hotel_name rule is stated twice. Sizeable chunks exist to repeat, not to add information.
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 an 18-parameter, nested, annotation-light tool with no output schema, this covers the essential decision inputs — date sourcing, hotel identification, session inheritance, and the shape of the return (room_groups, rate terms, provider minimums, raw_offer_page meaning). Gaps remain on occupancy/rooms and provider filtering, but nothing that would cause a wrong call.
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 61%, so the schema carries much of the load and a 3 baseline applies. The description clarifies the highest-risk parameters — hotel_id vs hotel_name exclusivity, destination as disambiguator, date_intent tonight, and full inheritance semantics for search_quote_session_id — but says nothing about providers, rooms/occupancy structure, region/country vs residency_country, or breakfast_included.
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?
Opens with a specific verb and resource — 'Get one identified or named hotel's room options and provider prices' — scoped to hotel-local dates or date_intent: tonight. It also explicitly partitions work against both siblings, routing undated amenities/policies to get_hotel and implying search_hotels as the source of the hotel_id.
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?
Gives concrete selection rules: supply exactly one of hotel_id or hotel_name, supply check_in/check_out, date_intent, or search_quote_session_id, use destination only for disambiguation, and ask only when the hotel is ambiguous. It also names the alternative tool for hotel facts and forbids redundant destination re-searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search a destination or latitude/longitude (with country) for explicit hotel-local dates (including today), or date_intent: tonight. Tonight is resolved server-side in the destination time zone, never UTC. Returns hotel summaries and the lowest eligible full-stay total from Expedia, Booking, Agoda and Brek, with direct provider booking links. Search starts at a 20 km core radius, expanding to 40 km then 60 km while fewer than 50 matching static candidates exist, within the same tool call and deadline. Explicit max_distance_km disables expansion. Providers are queried once after the final candidate scope is chosen. Default order is nearest 5 km distance bands first, then greatest Brek price advantage over the cheapest other provider in each band. The advantage uses comparable full-stay totals in the same currency; missing comparisons go last within their band. Preserve the returned hotel order unless the user requests another sort. Supports star ranges or exact stars, guest-review minimum and review count, facilities, property types, distance and full-stay price budgets. Hotel and rate filters can be combined; budgets cover all nights and requested rooms, including mandatory taxes and fees. Guest scores and hotel star classifications have separate filters. no_matching_offer means prices/terms failed the requested filters, not sold out. Room types and room-level rate plans are not included. No HotelUse account or API credits required. Device detection is automatic with a desktop fallback. For a fresh search supply destination or latitude/longitude with country, and either check_in/check_out or date_intent. Search pagination accepts only quote_session_id and cursor. Omit unknown optional values; do not send null. On follow-ups that change destination, dates, guests, hotel/rate filters or sort, call search_hotels again once with the updated criteria and preserve unchanged itinerary/preferences from the latest relevant search. Do not filter or reorder an earlier result page and present it as a new destination search: that page may omit matching hotels. For nearest, closest, or distance order use sort: distance_asc. The geographic_scope.radius_km value is the search radius, never any hotel’s distance. Per-hotel distance_meters is measured from the destination center. For cheapest hotels use sort: stay_total_asc. For "4-star only" use hotel_filters.star_ratings: [4]; for "4- and 5-star only" use [4,5], not star_rating_min: 4 (which includes 4.5). Never broaden explicit criteria silently. Omit providers unless the user requests specific providers; the server handles occupancy support. A successful partial response is the result of this search: show the returned prices and do not automatically repeat the search to fill missing provider quotes. An explicit user refresh calls the tool again. Pagination with quote_session_id/cursor is only for unchanged criteria.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | For nearest, closest, or sorting by distance use distance_asc (exact straight-line distance ascending). Default: nearest 5 km distance bands first (0–5, 5–10, 10–15, 15–20 km), then greatest Brek price advantage over the cheapest other provider within each band (other provider total minus Brek total, in context.currency). Only comparable full-stay totals including mandatory taxes and fees qualify. Missing comparisons are last within their band; ties use lowest total, distance and hotel ID. Unpriced hotels are last. distance_price_asc retains lowest-price ordering within the same bands. stay_total_asc sorts all matched hotels by total without distance bands. distance_asc uses straight-line distance; stay_total_desc uses descending whole-stay price; review_score_desc uses the displayed normalized guest score, then review count. Unpriced hotels remain last in every order. Sorting happens before pagination. | distance_brek_savings_desc |
| rooms | No | ||
| cursor | No | Copy the returned next_cursor exactly. Do not calculate an offset or mix new filters with a quote page. | |
| device | No | Optional traveler device. Omission uses trusted client hints, then desktop. Room follow-ups inherit the effective search device. Mobile app rates require an approved native-app integration. | |
| locale | No | Traveler BCP 47 language, such as en-GB, independent of the destination. | |
| region | No | ||
| country | No | ||
| check_in | No | Hotel-local calendar date; today is allowed in the destination time zone, even after UTC midnight. | |
| currency | No | Requested display currency. Omission defaults to client visitor country, then locale, then USD. | |
| latitude | No | Search center latitude. Supply together with longitude. Explicit coordinates take precedence over city/region. | |
| check_out | No | ||
| longitude | No | Search center longitude. Supply together with latitude. | |
| page_size | No | ||
| providers | No | ||
| date_intent | No | A one-night stay resolved server-side in the destination or hotel time zone. Mutually exclusive with check_in/check_out. | |
| destination | No | ||
| user_locale | No | Optional traveler locale from client context, such as en-GB. Independent of the hotel destination. | |
| rate_filters | No | ||
| hotel_filters | No | ||
| quote_session_id | No | Copy the exact quote_session_id from the result being paged. | |
| residency_country | No | ||
| user_location_country | No | Optional traveler country from client context, used for default currency and residency. Independent of the hotel destination. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only/open-world annotations, the description discloses radius expansion behavior, provider query timing, server-side timezone resolution, default ordering rules, partial response semantics, no_matching_offer meaning, and no account/API credit requirement. These are substantial behavioral details an agent needs before invoking the 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?
The description is long but information-dense and front-loads the core search behavior before detailed guidance. Some repetition exists around pagination and follow-up searches, and the single-paragraph structure makes it dense, but most sentences add actionable value for a complex 22-parameter tool.
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's complexity, nested filters, and lack of an output schema, the description provides enough context about returned hotel summaries, pricing, booking links, ordering, partial results, and pagination to use the tool correctly. No critical invocation behavior appears missing.
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 only 55% schema description coverage across 22 parameters, the description compensates heavily by explaining sort semantics, date_intent, quote_session_id/cursor pagination, star_ratings versus star_rating_min, max_distance_km disabling expansion, provider omission, and full-stay budget meaning. Some parameters such as rooms and page_size receive little explanation, but the critical search semantics are well covered.
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 opens with a specific verb and resource: searching hotels by destination or latitude/longitude for explicit dates or date_intent. It also clarifies that room types and rate plans are not included, which implicitly distinguishes it from get_room_rates and get_hotel.
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 gives extensive when-to-use guidance: fresh searches require destination plus dates or date_intent; follow-ups that change criteria should call search_hotels again; pagination is only for unchanged criteria; sort mappings are provided for nearest, cheapest, and star requests. It also states what not to do, such as filtering/reordering an earlier page or silently broadening explicit criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_hotelget_room_ratessearch_hotelsSearch hotels worldwide, compare live room rates, and create booking payment links.
Live hotel and flight prices compared across Booking.com, Agoda, Trip.com and Traveloka, in USD.
Search hotels & rentals: live prices & reviews across Booking.com, Airbnb, Vrbo & Google Hotels.
Search 650,000 hotels, get each hotel's direct price with full offer lists, match rooms, book.
Add one secure layer between your agents and this server.
