Search Best Western hotels worldwide: descriptions, addresses, contacts, amenities and photos.
Scored across 4 tools
Each tool targets a plainly distinct resource: search_hotels (discovery), get_hotel_details (full record), get_hotel_photos (gallery), get_amenities (amenity catalogue or per-hotel amenities). The descriptions explicitly cross-reference one another (call search_hotels first, use get_hotel_details for the full record) and reinforce the boundary between list-level and detail-level retrieval.
All four names follow a uniform snake_case verb_noun pattern (search_hotels, get_hotel_details, get_hotel_photos, get_amenities) with a consistent get_ prefix for single-resource lookups. No deviations or mixed conventions.
Four tools is a tight, well-scoped set for a descriptive hotel-information API where each tool earns its place. It is at the thin end of the reasonable range, but the narrow scope (no rates/booking) justifies not having more.
The surface covers the full lookup lifecycle: search, full details, photos, and amenity discovery. The obvious gap is availability/rates/booking, but the descriptions explicitly declare those out of scope and direct users to page_url or hotel contacts, so agents have a workaround rather than a dead end.
Return the amenities of one hotel, or the chain's global amenity catalogue when hotel_id is omitted.
Call it without hotel_id to discover the valid amenity IDs to use in search_hotels.
No availability, rates or booking: this tool only returns descriptive information.| Name | Required | Description | Default |
|---|---|---|---|
| hotel_id | No | Hotel ID from search_hotels. If omitted, returns the chain's full amenity catalogue. | |
| language | No | Language of the labels. Accepted values: fr, en, de, it, es. A text missing in the requested language is returned in French. | fr |
| amenity_id | No | Restrict to one amenity ID, uppercase (e.g. POOL, WIFI_INTERNET, PARKING, RESTAURANT, FITNESS). Unknown IDs raise an error listing the valid ones; with hotel_id, an empty list means the hotel does not have this amenity. |
| Name | Required | Description |
|---|---|---|
| language | Yes | Language of the returned texts |
| amenities | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds meaningful scope framing by explicitly ruling out availability/rates/booking and clarifying that only descriptive information is returned, though it says nothing about error or fallback behavior (that lives in the schema).
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?
Three short paragraphs, front-loaded with the core purpose, then discovery usage, then the exclusion note. No sentence is filler and each adds a distinct constraint.
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 an output schema present, return values need no explanation, and the description covers both invocation modes plus the negative scope. Nothing an agent needs to call this correctly is 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?
Schema description coverage is 100%, so hotel_id, language and amenity_id are fully documented in the schema, including enum values, the French fallback, and the unknown-ID error. The description only restates the hotel_id omission semantics, adding no syntax or format detail beyond the structured data, so baseline 3 is appropriate.
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 (return) and resource (amenities), and crisply splits the two modes: one hotel's amenities vs. the chain's global catalogue when hotel_id is omitted. An agent can distinguish it from get_hotel_details and get_hotel_photos immediately.
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 explicit when-to-use guidance ('Call it without hotel_id to discover the valid amenity IDs to use in search_hotels'), naming the sibling that consumes the output. It also draws a clear negative boundary: no availability, rates or booking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the complete details of one hotel (descriptions, address, location, contacts, policies, page URL, amenity IDs).
Requires a valid hotel_id: call search_hotels first if you only know the hotel name or city.
No availability, rates or booking: for those, give the user the page_url or the contact details of the hotel.| Name | Required | Description | Default |
|---|---|---|---|
| hotel_id | Yes | Hotel ID as returned by search_hotels (e.g. PAR-87155) | |
| language | No | Language of the texts. Accepted values: fr, en, de, it, es. A text missing in the requested language is returned in French. | fr |
| Name | Required | Description |
|---|---|---|
| name | No | |
| brand | No | |
| stars | No | |
| status | No | |
| address | No | |
| contact | No | |
| hotel_id | Yes | |
| language | Yes | Language of the returned texts |
| location | No | |
| page_url | No | |
| policies | No | |
| amenities_ids | No | |
| description_long | No | |
| description_short | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine scope information the annotations cannot convey — that availability, rates and booking data are NOT returned — which prevents the agent from overselling what this tool provides. It stops short of describing volume/size of the response, so not a 5.
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?
Three short blocks, each front-loaded with its key point: what is returned, what is required, what is excluded. Zero filler, and the exclusion note is placed last where it is easy to scan.
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?
Annotations cover safety, an output schema documents the return shape, and 100% schema coverage handles parameters. The description's remaining job — scope, prerequisite, and explicit exclusions — is fully discharged, leaving no ambiguity for an agent invoking this tool.
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%: hotel_id carries a format example (PAR-87155) and language enumerates values plus the French fallback. The description reinforces the hotel_id origin ('as returned by search_hotels') but adds no new syntactic or semantic detail beyond the schema, so the baseline 3 applies.
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 ('Return the complete details of one hotel') and enumerates the payload fields, which distinguishes it from siblings get_hotel_photos and get_amenities that cover subsets. An agent can tell immediately this is the full-record retrieval tool.
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 an explicit precondition ('Requires a valid hotel_id') plus the alternative to run when the ID is unknown ('call search_hotels first'). It also states a clear when-not: no availability, rates or booking, and redirects the agent to page_url/contact details instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the photo gallery of a hotel (URLs and captions), optionally limited to the cover photo.
No availability, rates or booking: this tool only returns descriptive information.| Name | Required | Description | Default |
|---|---|---|---|
| hotel_id | Yes | Hotel ID as returned by search_hotels (e.g. PAR-87155) | |
| language | No | Language of the captions. Accepted values: fr, en, de, it, es. A text missing in the requested language is returned in French. | fr |
| cover_only | No | If true, return only the cover photo |
| Name | Required | Description |
|---|---|---|
| photos | Yes | |
| language | Yes | Language of the returned texts |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful scope context ('only returns descriptive information') but says nothing about ordering, pagination, or how many photos are returned beyond what the output schema likely provides.
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?
Two tightly written sentences; the purpose is front-loaded and the scope exclusion follows as a guardrail. Nothing is wasted or redundant.
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 an output schema, full schema coverage and rich annotations, the description only needs to establish purpose and scope, which it does. Minor gap: no hint about result size or ordering, though that is a small omission for a read-only gallery tool.
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%, so the schema already documents hotel_id, language (with enum and French fallback) and cover_only. The description only gestures at the cover limitation and captions, adding little beyond what the schema provides – baseline 3 applies.
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 ('Return the photo gallery of a hotel') and even names the payload ('URLs and captions'), which clearly separates it from get_amenities, get_hotel_details and search_hotels. It stops short of explicitly naming siblings or contrasting them, so it lands just below the top band.
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 second sentence gives a clear scope exclusion ('No availability, rates or booking'), which tells the agent when this tool is not the right one and implicitly routes booking intent elsewhere. It does not explicitly name alternative siblings for the photo case, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the chain's hotels (worldwide, several thousand) by location, stars, brand, status and amenities, with pagination.
All filters are optional and combined with AND. Always pass `country` (ISO code, e.g. "FR") together with `city`
when the country is known or implied: a search on "Paris" alone returns Paris (Kentucky, US) and
Paris (Ontario, CA) before Paris (France).
Returns {"language", "total", "offset", "limit", "count", "next_offset", "hotels"}: `total` is the number of matching hotels,
`next_offset` is null on the last page. Each hotel is a summary (hotel_id, name, brand, city, country, state,
stars, status, lat, lng, cover_photo); use get_hotel_details for the full record.
Geographic search: give a center (lat + lng, or near_hotel_id) and radius_km. Results are then sorted by
distance, each hotel gets a `distance_km` field and the response a `center` field. Coordinates you supply
for a landmark are approximate, so prefer a generous radius. Hotels without coordinates are excluded.
No availability, rates or booking: this tool only returns descriptive information.| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude of the search center (-90 to 90). Use with `lng` and `radius_km`. | |
| lng | No | Longitude of the search center (-180 to 180). Use with `lat` and `radius_km`. | |
| city | No | City name, partial match ignoring case, accents, hyphens and St/Ste abbreviations (e.g. 'Saint-Étienne' = 'saint etienne' = 'St Etienne'; 'Saint' matches every city containing 'Saint'). If no city matches, the response lists close city names in `city_suggestions`. City names are ambiguous worldwide: combine with `country` whenever the country is known. | |
| brand | No | Partial match on the sub-brand, ignoring case and accents (e.g. 'Plus', 'Premier', 'Signature Collection') | |
| limit | No | Maximum number of hotels to return (1-100) | |
| offset | No | Number of matching hotels to skip, for pagination. Pass the `next_offset` value of the previous response. | |
| status | No | Hotel status | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (FR, US, CA, DE...). Strongly recommended together with `city` to avoid homonyms (Paris FR vs Paris US/CA). | |
| language | No | Language of the multilingual fields of the results. Accepted values: fr, en, de, it, es. A text missing in the requested language is returned in French. | fr |
| min_stars | No | Minimum star rating (1-5). Hotels without a star rating are excluded when set. For an exact rating, filter the results on their `stars` field. | |
| radius_km | No | Search radius in kilometres (up to 200). Required with lat/lng or near_hotel_id. | |
| near_hotel_id | No | Use this hotel's coordinates as the search center (instead of lat/lng) to find other hotels around it; the hotel itself is excluded. Use with `radius_km`. | |
| required_amenities | No | Amenity IDs the hotel must ALL have, uppercase (e.g. ["POOL", "PARKING"]). Unknown IDs raise an error listing the valid ones; the catalogue is also available via get_amenities without hotel_id. |
| Name | Required | Description |
|---|---|---|
| count | Yes | Number of hotels in this page |
| limit | Yes | |
| total | Yes | Number of hotels matching the filters |
| center | No | Center of a geographic search: {lat, lng, radius_km}, plus near_hotel_id if used |
| hotels | Yes | |
| offset | Yes | |
| language | Yes | Language of the returned texts |
| next_offset | Yes | Offset of the next page, null on the last page |
| city_suggestions | No | When `city` matches no hotel: close city names to retry with |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive/closed-world, so the description's job is to add behavior. It does: distance-sorted results with an added `distance_km` field, hotels lacking coordinates being excluded, approximate landmark coordinates warranting a generous radius, and unknown amenity IDs raising an error listing valid ones. This is well beyond what the annotations convey.
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?
Four tight paragraphs, each with a distinct job (filters/disambiguation, return shape, geographic mode, capability boundary), front-loading the most actionable guidance. Despite the length, no sentence is redundant with the schema or annotations.
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?
The tool has 13 optional parameters and an output schema; the description still summarizes the response envelope (total, next_offset, hotel summary fields) and names the companion tool for detail. For a search tool of this complexity, an agent has everything needed to call it correctly on the first attempt.
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%, so the baseline is 3, but the description adds real semantics: the country+city homonym rule, the city-fallback `city_suggestions` behavior, and that min_stars excludes unrated hotels rather than acting as an exact-match filter. The only gap is it never mentions the lat/lng/radius_km vs near_hotel_id mutual exclusivity beyond the schema text.
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 ('Search the chain's hotels'), scopes the corpus ('worldwide, several thousand'), and enumerates the filterable dimensions plus pagination. An agent immediately knows what this tool does and can distinguish it from get_hotel_details, which is explicitly named as the full-record alternative.
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 explicit when-to-use guidance ('Always pass country together with city when the country is known or implied') with the concrete disambiguation example (Paris KY/ON vs Paris FR). It also states exclusions up front: 'No availability, rates or booking' and 'use get_hotel_details for the full record', routing the agent to the right sibling.
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_amenitiesget_hotel_detailsget_hotel_photossearch_hotelsLive hotel rates worldwide: search stays, property detail, all-in room prices, human phone desk.
Live hotel and resort prices (taxes included) and secure booking links for travelers. Since 1993.
Travel search: 1.3M hotels and apartments, owner homes, tours, flights, taxi, car rental.
Search and book 3M+ hotels in 200+ countries. Agents pay per reservation in USDC on Base over x402. Hosted, no auth.
Add one secure layer between your agents and this server.
