Blue Pillow Hotels & Stays

Live availability and per-operator quote for a specific property over a specific stay window. Performs a live date-aware lookup against the BluePillow search layer, returns date-specific prices, rooms-left scarcity signals, breakfast-included and refundable flags, and a per-operator deep link to complete the booking.

Useful when the user has specific dates in mind for a property they already identified — typically via search_stays or get_property_details. The complementary get_property_details tool answers "what is this property like" with static facts; this tool answers "can I book it for these dates at what price" with live, date-specific data.

Follow-up questions about a property from an earlier search_stays result — is it still available, what does it cost for other dates or guests — use that result's id as property_id.

Required input: property_id (the id from a search_stays result, opaque string starting with prop_), dates (check_in + check_out, ISO 8601), and guests (adults / children / infants composition). Without these the live lookup cannot proceed.

Natural-language date references — "tonight", "this weekend", "next weekend", "the weekend of July 4", "Memorial Day weekend", "long weekend in May" — translate to concrete check_in / check_out values at the call site; concrete ISO dates also work. check_in is a date in the real-time calendar that is today or later; past values are rejected at the API boundary.

user_country, currency, and language carry the user's locale, not the property's. Prices are returned in currency if set, else derived from user_country, else USD — pass user_country and/or currency whenever you know the user's location/currency so the quote matches what they'll pay; don't rely on the USD default. user_country and language also localize the web_url booking link.

Response shape:

• availability_status — available, unavailable, or unknown. Available means rooms confirmed at the operator level for the requested window; quote freely. Unavailable means no rooms for these dates — surface that explicitly to the user with a suggestion of alternate dates (there is no price for these dates).

• offers[] — per-operator quotes. Each carries amount (total stay), amount_per_night (per-night), currency, breakfast_included, refundable, rooms_left, and deeplink_url. offers[0] is the best value for money as Blue Pillow ranks it: price weighed against what is included (breakfast, free cancellation) and the operator's historical reliability, with a small commercial component. It is not necessarily the cheapest — the full per-operator list is always in offers[], and sort=price_asc gives pure price order. Each deeplink_url is a BluePillow tracked-redirect URL (bluepillow.com/…) that records the click and forwards the user to the operator's booking page — pass it verbatim, never reconstruct it or replace it with a raw OTA link.

• price — mirror of offers[0] for callers that just want the curated headline. null when unavailable (no price for these dates).

Per-night vs total — amount_per_night is per-night; amount on each offer is the total for the requested stay. Phrasings like "€X/night via Booking, breakfast included, €Y total" are unambiguous; bare numbers without a unit ("€192") get misread.

Scarcity signals: low rooms_left values (1-3) are useful cues — "1 room left at €X on Booking" reads naturally. Free cancellation (refundable=true) and breakfast-included are decision factors worth surfacing proactively when present on some offers but not others.

When all results across operators are unavailable, that's the signal to say so explicitly to the user and offer to widen the dates or look at alternatives.

For final booking confirmation, hand the user the corresponding deeplink_url (or the property's web_url) — booking URLs are not reconstructed by hand.

Curated destinations — cities, neighborhoods, airports, points of interest — within a radius of a geographic point, for use as a destination_id in subsequent search_stays calls. Useful when coordinates are already in hand (from world knowledge, from a previous tool result, or directly from the user) and the agent needs to enumerate which curated destinations cover that area before searching for properties.

Also useful as a fan-out entry point for region-level intents — broad areas such as 'Tuscany', 'Pacific Northwest', 'New England', or 'Central Europe' — where the agent can pass an approximate regional centroid and surface a list of sub-destinations the user may then narrow down to before a focused search.

Returns up to 5 candidates ordered by distance. The radius defaults to 5 km; widens up to 50 km for broader queries.

Issues a free anonymous key for Blue Pillow Hotels & Stays, with no account or sign-up. The other tools of this server take the key in their api_key argument. A key does not expire, so the same key can be used for later calls; calling this tool again issues a new one. Keys carry per-key rate limits and let Blue Pillow count usage and booking-link referrals per key, as described in the privacy policy (https://b2a.bluepillow.com/legal/privacy).

Optional label and agent (max 64 chars each) are stored with the key to name the client that requested it (e.g. 'claude-desktop', 'chatgpt', 'cursor-ide'); they should not contain personal data and do not affect rate limits or capabilities. Integrators who need higher limits can write to info@bluepillow.com.

Details and guest reviews for one specific property — hotel, B&B, hostel, apartment, villa — identified by its id. Answers questions such as what guests think of it, whether it is clean, quiet or comfortable, the most common complaints, how the breakfast is, which facilities it offers, where exactly it is, or how it compares with another option. It also serves follow-up questions about a property returned earlier by search_stays: the id of that result is the property_id here.

Returns the amenity list, photos, booking sources, location and the headline rating (rating + rating_count). Guest-review data is added through include:

• reviews_aggregate — score, total count and per-source breakdown; it summarizes all reviews.

• reviews_sample — up to 5 recent review texts.

• reviews_extended — up to 20 recent review texts for a deeper read; it supersedes reviews_sample. reviews_meta reports how many texts exist and that the cap is deliberate: the omitted texts are older, and the aggregate already reflects them.

It takes no dates and carries no price: a price only exists for a concrete stay window, which is what check_property_availability quotes. In the response price is null, offers is empty and availability_status is unknown.

Input: property_id is the id of a search_stays result (an opaque string starting with prop_) or a bluepillow.com property URL. For a property known only by name, resolve_destination and a targeted search_stays return its id.

user_country, currency and language carry the user's locale and localize the web_url link to the property page. Language default is "en"; country default is "US". All rating fields are on a 0-5 scale.

Converts a destination name into a destination id usable in search_stays. The canonical entry point when the user's request mentions a place name and coordinates are not already known from a prior call in this session. If coordinates are already in hand from an earlier tool result, passing them directly to search_stays skips this resolver step.

Accepts cities, neighborhoods, airports, points of interest, and named areas such as islands or districts ('Tenerife', 'Crete', 'Trastevere'), written locally or in English. Names are matched against Blue Pillow's own place slugs, which exist for English, Italian, German and Spanish; in other languages the English name is the most reliable. Accents are optional — 'São Paulo' and 'Sao Paulo' resolve alike. A qualifier after the name is tolerated ('Austin, Texas'). The country parameter disambiguates names that occur in multiple places (for example Springfield MA vs Springfield IL vs Springfield MO).

The type parameter narrows the kind of destination returned. poi is the narrowest match and has partial coverage on the comparator side; when the agent's own geographic knowledge can already geocode the POI to lat/lon, passing coordinates to search_stays is the more reliable path. An area candidate can be large: its location.default_radius_km says how far a search on its id reaches (an island's may include its neighbours); when the user wants one part of it, coordinates of that part are the tighter search.

Multi-operator accommodation comparator for a geographic area and a stay: dates (required), guests and optional filters. Returns a ranked list of properties — hotels, B&Bs, apartments, villas, hostels and more — with the booking sites that offer each one and their live availability and per-operator price for the requested dates. Questions about one property found here (guest opinions, facilities, a live re-quote) are served by get_property_details and check_property_availability with that result's id.

Dates: natural-language references ("this weekend", "the weekend of July 4", "long weekend in May") translate to concrete check_in / check_out values at the call site; ISO dates also work.

Locale: user_country, currency and language carry the user's locale, not the destination's. Prices come back in currency if set, otherwise in the currency of user_country (US→USD, CA→CAD, GB→GBP, euro-area→EUR), otherwise USD. Each offer is quoted by its operator in that currency; nothing is converted. user_country and language also localize the booking link.

Each result carries:

• location.lat / location.lon, suitable for plotting the results on a map.

• thumbnail_url (first photo, or null) and images, capped to one photo; get_property_details returns the full gallery.

• web_url, a link to the property page with the stay already encoded.

• price and offers[]: the live quote for the requested dates, present only when availability was confirmed. Each offer has ota, amount (total stay), amount_per_night, currency, breakfast_included, refundable, rooms_left and deeplink_url — a Blue Pillow tracked link that records the click and forwards to the operator's booking page; it is what attributes the booking to Blue Pillow, which a raw operator URL does not. price mirrors offers[0], Blue Pillow's best value for money (price weighed against breakfast, free cancellation and operator reliability, with a small commercial component), not necessarily the cheapest; sort=price_asc orders by price alone. There is no date-agnostic "from" price.

• availability_status: available (live quotes in offers), unavailable (no rooms for those dates) or unknown (the operators returned nothing conclusive — not evidence that the property is full). The default availability_mode=strict returns only available results; include_unavailable also returns the other two.

Reading the numbers: amount_per_night is per night and amount is the total stay, so a quote reads clearly with its unit ("€X/night via Booking, €Y total"). rooms_left signals scarcity; refundable and breakfast_included often separate otherwise similar options.

Ratings are on a 0-5 scale (rating, reviews_aggregate.score_0_5, review scores and filters.min_rating; "8 out of 10" is 4.0). Upstream scores arrive rounded, so rating is coarse and reads best together with rating_count. rating, stars and rating_count may be 0 or absent in this list even when the property has them; get_property_details returns the fuller reviews_aggregate. Here reviews_aggregate carries score_0_5, rating_count (reviews behind the score) and comment_count (review texts available) — two different magnitudes. include=["reviews_sample"] adds up to 5 recent review texts per property, useful for qualitative criteria ("great breakfast", "quiet area"); a deeper read on one property is get_property_details with reviews_extended.

Filters: filters.min_rating and filters.price_max_eur narrow the results; filters.property_types and filters.amenities rank rather than filter, so each result's property_type and amenities show what it actually is. Property type tokens: hotel, apartment, house, villa, bb, hostel, farmstay, holiday-home (common Italian and English synonyms are accepted). Common amenity codes: wi-fi, parking, pool, air-conditioning, kitchen, garden, pets-allowed, for-families, facilities-for-disabled, non-smoking-only.

Location modes:

• coordinates: a known lat/lon (default radius 5 km, up to 50 km; beyond that bbox or a parent destination fits better).

• destination_id: the opaque id from resolve_destination, passed verbatim.

• poi_id: the opaque id of a point of interest, from resolve_destination or discover_destinations_near.

• bbox: an explicit map rectangle. A property is not a location: get_property_details covers a known property.

Pagination: the next_cursor of a response goes into page.cursor for the next page.