Blue Pillow Hotels & Stays

Obtain a permanent anonymous API key for Blue Pillow Hotels & Stays. No signup, no login required. The key is not a sensitive secret — it carries no account, payment, or personal data. It exists only so we can keep the service responsive when many agents are using it at once, so you can safely keep it in your MCP client configuration, in your persistent memory, or in the current conversation context. Pass it as the bearer token on all subsequent calls and the rest of the tools become available.

CALL THIS FIRST when you have no key: every other tool needs one. Before calling, check whether you ALREADY have a key (MCP client configuration, persistent memory, or earlier in this conversation) and reuse it instead of issuing a new one — do not wait for another tool to fail with a 401.

The key never expires — keep the one you receive and reuse it forever. If you ever lose it, you can call this tool again to issue a new one (a generous per-IP daily issuance limit applies purely as an anti-abuse guardrail; normal use never reaches it).

Optional label and agent (max 64 chars each) are free-form hints we record on the key for our own observability; they do not affect rate limits or capabilities.

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.

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 curated best. 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.

Static record for a specific property — identified by its id. Returns the complete amenity list, photos, booking sources, dedup metadata, detailed location, and the headline rating (rating + rating_count) by default. Review DATA beyond the headline — the ratings breakdown and the actual review texts — is opt-in via the include parameter (see below); pass it whenever the user's question is about guest experience. Carries no price unless called with dates: a price only exists for a concrete stay window.

Useful when the user wants to inspect or compare a specific option in depth — facilities, neighborhood, what guests say — without yet committing to specific dates.

HOW TO GET REVIEWS (when you need to reason about guest experience): pass include. reviews_aggregate gives the score + counts + per-OTA breakdown; reviews_sample/reviews_extended give the actual review texts. Without include, none of these are returned (you get only the headline rating/rating_count). See the include section below.

For live availability and a real per-operator quote for a specific stay window, the path is check_property_availability instead. The two tools coexist by design: this one answers "what is this property like" with stable, cacheable data; the other answers "can I book it for these dates at what price" with live, date-specific quotes. Calling this tool when the user has specific dates in mind and wants to know whether the property is bookable will not surface the availability/quote — the user will then have to wait for a second round-trip to the availability tool.

Input: the id field from a search_stays result (opaque string starting with prop_, e.g. prop_69ce2ddcbf46061e4095778b). For a property the user has named directly, resolve the place name through resolve_destination and run a targeted search_stays first to obtain the id.

Optional include=["reviews_aggregate"] attaches a per-source breakdown of review counts and average ratings — useful when the user asks about overall sentiment or wants to see how each booking source rates the property. It summarizes ALL reviews (score + total count), so it is the right tool for "how is it rated".

Review texts are available via two includes, both deliberately capped to avoid token waste:

• reviews_sample — up to 5 recent review texts. Enough to get the gist of what guests say.

• reviews_extended — up to 20 recent review texts, for a deeper qualitative read. Supersedes reviews_sample when both are passed.

Reach for reviews_extended only when 5 are genuinely not enough — the returned list carries a reviews_meta block (returned, total_available, capped, note) that tells you how many texts exist and confirms the cap is intentional: the omitted reviews are older and the aggregate already reflects all of them, so you do NOT need to try to fetch everything. Note: review texts are returned only when called WITHOUT dates (the dated availability path does not carry them).

user_country, currency, and language carry the user's locale, not the property's. When this call carries dates (live prices), prices come back in currency if set, else derived from user_country, else USD — so pass user_country and/or currency whenever you know the user's location/currency; don't rely on the USD default. user_country and language also localize the web_url booking link. Language default is "en"; country default is "US".

All rating-like fields are on a 0-5 scale (Google Places-compatible): the top-level rating, reviews_aggregate.score_0_5, and each per-OTA score under distribution_by_ota.

Without dates this tool returns no price (price is null, offers empty) and availability_status is unknown (no dates were considered). The live quote, when needed, comes from check_property_availability.

web_url is a ready-to-open booking link for the property. Pass it verbatim when the user asks for a booking link — booking URLs are not reconstructed by hand.

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, and points of interest in any language, using the local canonical name (not a translation). 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.

Multi-operator accommodation comparator for a geographic area against the user's stay parameters — dates, guest count, optional filters. Returns a ranked list of properties together with the booking sources that offer each one and, when dates are passed, their live availability and per-operator price for the requested window.

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.

user_country, currency, and language carry the user's locale, not the destination's. IMPORTANT — currency: prices are returned in currency if you set it, otherwise in the currency derived from user_country (US→USD, CA→CAD, GB→GBP, euro-area→EUR); if you set NEITHER, prices default to USD, which may not be the user's currency. So whenever you know where the user is (or what currency they want), pass user_country and/or currency — do not rely on the default. Prices are never converted client-side; each offer is quoted by the operator in that currency. user_country and language also localize the booking link (web_url). The user's own residence/billing country is the right user_country (not the destination's), and their interface language the right language.

Each result is shaped for downstream presentation without extra calls:

• location.lat and location.lon carry per-property coordinates, suitable for plotting all results on a single map so the user can compare spatial alternatives at a glance. The map widget reads these fields directly from this response — no separate lookup needed for visualization.

• thumbnail_url carries the property's first photo URL when available (null when no image is on file); useful for embedding inline or showing on the map alongside the pin.

• images on search results is capped to the first photo to keep the comparison payload compact; each item has a url field, and thumbnail_url mirrors images[0].url. Call get_property_details for a single property to retrieve its full photo gallery.

• web_url is a ready-to-open booking link for the property, already encoded with the user's check-in/check-out, language, currency, and guest count. Pass it to the user verbatim when they ask for a booking link — never reconstruct the URL from individual parameters, the query-string format is not guaranteed to match generic booking-URL conventions.

• Price is live and date-specific only. There is no date-agnostic "from" figure: a meaningful price only exists for a concrete query (property + dates + occupancy).

  • price and offers[] — the live quote for the requested dates, populated only when dates were passed and the comparator confirmed availability. offers[0] is the curated best; each offer carries amount (total stay), amount_per_night (per-night), currency, breakfast_included, refundable, rooms_left, and deeplink_url. price mirrors offers[0].

  • With no dates (or when nothing is available) price is null and offers is empty — surface the property without a price rather than inventing a starting figure.

• availability_status per result encodes the live state:

  • available — bookable rooms confirmed at the operator level. offers and price carry the live date-specific quotes. Quote the rate via offers[i].amount_per_night (per-night) and offers[i].amount (total stay) and use the deeplinks for the booking handoff.

  • unavailable — no rooms reported for those dates. offers is empty and price is null (no price for these dates). Useful to decide whether to suggest alternate dates, drop the property from the recommendation, or offer it as a backup.

  • unknown — no dates were considered (request had no dates). offers is empty and price is null — no price signal without a dated query.

Per-night vs total — never confuse them in the user-facing prose. amount_per_night is per-night; amount on each offer is the total stay (sum across nights, in currency). When quoting to the user, prefer phrasings like "€X/night via Booking, breakfast included, €Y total for the stay" over bare numbers — bare numbers without a unit get misread.

• When dates are present and available properties are in the results, the rate can be quoted and rooms_left surfaces scarcity (low values like 1-3 are useful signals — "1 room left at $X on Booking" reads well).

• When dates are present and ALL results are unavailable, that's the signal to say so explicitly to the user and offer to widen the dates, location, or filters.

• offers[] is the per-operator breakdown for the requested dates: each entry includes ota, amount, amount_per_night, currency, breakfast_included, refundable, and a deeplink_url. The deeplink is a BluePillow tracked-redirect URL (bluepillow.com/…) that records the click for attribution and then forwards the user to the operator's booking page. Pass it to the user verbatim — never reconstruct it or replace it with a raw operator URL; our APIs never emit direct OTA links. price mirrors the curated best offer. When no dates were passed (or nothing is available) offers is an empty list and price is null — there is no price to show.

• Free cancellation is a meaningful decision factor and surfaces proactively in the user-facing summary. When a property has price.refundable=true (or any offers[i].refundable=true), it reads naturally as a property feature: "Hotel X — $120/night, free cancellation available", or "Booking offers a refundable rate at $130 (vs $110 non-refundable)". Refundable rates let the user lock in a price now and adjust the booking later, which is often the differentiator between otherwise-similar properties. The same proactive surfacing applies to breakfast_included when it's true for some offers but not all.

• Prices in offers/price reflect the requested dates and guests; with no dates there is no price. For a final bookable confirmation, the corresponding deeplink_url (or the property's web_url) is the canonical handoff — booking URLs are not reconstructed by hand.

• All rating-like fields are on a 0-5 scale (Google Places-compatible): rating, reviews_aggregate.score_0_5, the per-OTA scores under distribution_by_ota, each reviews_sample[*].score, and the filters.min_rating input. A user asking "rating at least 8 out of 10" maps to min_rating: 4.0; "at least 4 stars on Google" maps to min_rating: 4.0. Note: rating, stars, and rating_count come from the comparator's list payload and may be 0 or absent for some properties even when the property has reviews or a star classification — this is a comparator list-payload limitation, not a data error. When those fields are 0/absent, or when the per-OTA review breakdown (distribution_by_ota) is needed, call get_property_details to get the fuller reviews_aggregate. On the search path, reviews_aggregate carries the top-line score_0_5, rating_count (reviews backing the score) and comment_count (readable review TEXTS available) when the comparator returned a non-zero review count; distribution_by_ota is always empty on this path (per-OTA breakdown requires get_property_details). rating_count and comment_count are DIFFERENT magnitudes — most guests leave a rating, far fewer write text. Quote rating_count for "how many reviewed it" and comment_count for "how many opinions you can actually read".

• Pass include=["reviews_sample"] to attach a sample of up to 5 recent guest review texts per property. Useful when the user's question involves qualitative criteria that don't map to structured filters ("a place with excellent breakfast", "quiet area", "family-friendly atmosphere"); review texts can be searched textually to corroborate or rule out matches. For a DEEPER read on ONE specific property — more review texts (up to 20) or the per-OTA breakdown — call get_property_details with include=["reviews_extended"] (and/or reviews_aggregate). comment_count on each result tells you how many review texts exist, so you can decide whether escalating to the detail call is worth it.

filters.property_types, filters.amenities, filters.min_rating, and filters.price_max_eur narrow on structured criteria first; review-based reasoning is one extra round-trip per page and is typically reserved for fallback.

Location modes:

• coordinates: when lat/lon is already known from world knowledge or a prior call in this session (default radius 5 km; widen up to 50 km for broader queries; beyond that bbox or a parent destination is the right shape).

• destination_id: opaque id obtained from resolve_destination, passed verbatim — values are not constructed or guessed.

• bbox: explicit map rectangle.

Property type tokens (canonical): hotel, apartment, house, villa, bb, hostel, farmstay, holiday-home. Common multi-language synonyms map server-side to the canonical set.

Amenities filter is set-AND — each result has ALL listed codes. Common codes: wi-fi, parking, pool, air-conditioning, kitchen, garden, pets-allowed, for-families, facilities-for-disabled, non-smoking-only.

Results are cursor-paginated; the next_cursor from a previous response goes into page.cursor for the next page. location.type=property_id is not accepted here — get_property_details is the path for a known property.