Check live availability and per-operator quotes for a stay
check_property_availabilityLive 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, orunknown. 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 carriesamount(total stay),amount_per_night(per-night),currency,breakfast_included,refundable,rooms_left, anddeeplink_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 inoffers[], andsort=price_ascgives pure price order. Eachdeeplink_urlis 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 ofoffers[0]for callers that just want the curated headline.nullwhen 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dates | Yes | Stay window. Natural-language references such as 'tonight', 'this weekend', 'the weekend of July 4', 'Memorial Day weekend' translate to concrete check_in / check_out at the call site. check_in is a date in the real-time calendar that is today or later — past values are rejected at the API boundary. Clock calibration: this schema was published in August 2026, so today is August 2026 OR LATER; an assumed 'today' in 2024/2025 is a stale training-time clock. | |
| guests | Yes | Guest composition. Adults is required; children and infants default to zero. | |
| api_key | No | Your anonymous Blue Pillow Hotels & Stays API key (format 'pk_anon_…'). Pass it in THIS field on every call — this is how the tool authenticates. If you don't have a key yet, first check your MCP client configuration, your persistent memory, and earlier in this conversation; otherwise call `b2a_get_key` to get one instantly (do not wait for a 401). Reuse the same key on every subsequent call. It is not a sensitive secret: no account, payment, or personal data is attached. | |
| currency | No | Currency of the returned prices (ISO-4217, 3-letter uppercase, e.g. 'USD', 'EUR', 'GBP', 'CAD'). SET THIS (or `user_country`) to price in the user's currency — if you set NEITHER, prices default to USD. Prices come straight from the booking sources in this currency; never convert them yourself. | |
| language | No | User's UI language (2-letter lowercase). Drives the booking link language; falls back to 'en'. | |
| property_id | Yes | Opaque property id (e.g. 'prop_69ce2ddcbf...') OR a bluepillow.com property page URL (e.g. 'https://www.bluepillow.com/search/68d1a2...') — the id is extracted automatically. Use the URL form when the user pasted a bluepillow.com link. | |
| user_country | No | User's country (ISO-3166 alpha-2 uppercase). Drives the booking-link locale AND, when `currency` is not set, the pricing currency (US->USD, CA->CAD, euro-area->EUR). Pass the user's own country, not the property's home country. Falls back to 'US' when omitted. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| name | Yes | ||
| brand | No | ||
| chain | No | ||
| price | No | ||
| stars | No | ||
| images | No | ||
| offers | No | ||
| rating | Yes | ||
| web_url | No | ||
| features | No | Structured feature/facility tags (e.g. HouseFacilities, PropertyTypes). Populated alongside description when the endpoint path is active. | |
| location | Yes | ||
| amenities | No | ||
| cluster_id | No | ||
| dedup_meta | No | ||
| description | No | Free-text property description from the canonical source. Only populated when the endpoint path is active (use_bp_single_property_endpoint=True) and dates are present. | |
| ota_coverage | Yes | ||
| rating_count | No | ||
| reviews_meta | No | Provenance for reviews_sample on property detail: how many review texts were returned vs available, and that the cap is deliberate (token efficiency). null on search or when reviews were not requested. | |
| property_type | Yes | ||
| thumbnail_url | No | ||
| reviews_sample | No | ||
| reviews_aggregate | No | rating_count = reviews backing the score (OTA aggregate, e.g. 156). comment_count = readable review TEXTS available (e.g. 53), fetchable via reviews_sample/reviews_extended. They differ: most guests rate, fewer write text — do not conflate them. | |
| availability_status | No | Per the dates passed in the request: available = live bookable quotes in offers (price is the curated best); unavailable = BP reported no rooms for these dates (offers=[], price=null); unknown = no dates considered (no price exists without a dated query). |