Skip to main content
Glama

Check live availability and per-operator quotes for a stay

check_property_availability
Read-only

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
datesYesStay 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.
guestsYesGuest composition. Adults is required; children and infants default to zero.
api_keyNoAnonymous key for this server (format 'pk_anon_…'), as returned by `get_anonymous_key`. Required by this tool; the same key works for every call.
currencyNoCurrency 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.
languageNoUser's UI language (2-letter lowercase). Drives the booking link language; falls back to 'en'.
property_idYesOpaque 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_countryNoUser'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

TableJSON Schema
NameRequiredDescriptionDefault
idYes
nameYes
brandNo
chainNo
priceNo
starsNo
imagesNo
offersNo
ratingYes
web_urlNo
featuresNoStructured feature/facility tags (e.g. HouseFacilities, PropertyTypes). Populated alongside description when available.
locationYes
amenitiesNo
cluster_idNo
dedup_metaNo
descriptionNoFree-text property description, when the source provides one. Usually null on search results.
ota_coverageYes
rating_countNo
reviews_metaNoProvenance 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_typeYes
thumbnail_urlNo
reviews_sampleNo
reviews_aggregateNorating_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_statusNoavailable = live bookable quotes in offers for the requested dates (price is the curated best); unavailable = no rooms reported for these dates (offers=[], price=null); unknown = availability not established, either because the call carried no dates or because the operators returned nothing conclusive (offers=[], price=null).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / api_key / description
      Previous value: -"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 `get_anonymous_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."New value: +"Anonymous key for this server (format 'pk_anon_…'), as returned by `get_anonymous_key`. Required by this tool; the same key works for every call."
  2. Changed1 schema field changed
    • changedInput schema / properties / api_key / description
      Previous value: -"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."New value: +"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 `get_anonymous_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."
  3. Changed3 schema fields changed
    • changedOutput schema / properties / availability_status / description
      Previous value: -"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)."New value: +"available = live bookable quotes in offers for the requested dates (price is the curated best); unavailable = no rooms reported for these dates (offers=[], price=null); unknown = availability not established, either because the call carried no dates or because the operators returned nothing conclusive (offers=[], price=null)."
    • changedOutput schema / properties / description / description
      Previous value: -"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."New value: +"Free-text property description, when the source provides one. Usually null on search results."
    • changedOutput schema / properties / features / description
      Previous value: -"Structured feature/facility tags (e.g. HouseFacilities, PropertyTypes). Populated alongside description when the endpoint path is active."New value: +"Structured feature/facility tags (e.g. HouseFacilities, PropertyTypes). Populated alongside description when available."
  4. Changed1 schema field changed
    • changedInput schema / properties / dates / description
      Previous value: -"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."New value: +"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."
  5. Changed3 schema fields changed
    • changedInput schema / properties / api_key / description
      Previous value: -"Your anonymous Blue Pillow Hotels & Stays API key (format 'pk_anon_…'). If you do NOT already have one — check your MCP client configuration, your persistent memory, and earlier in this conversation first — call `b2a_get_key` to obtain one before calling this tool (do not wait for a 401). PRIMARY way to authenticate: pass the key here on every call. Clients able to attach an HTTP 'Authorization: Bearer <key>' header may do that instead and omit this field — but passing it here always works and is the recommended path for tool calls. The key is not a sensitive secret: it carries no account, payment, or personal data; reuse the same key on every call."New value: +"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."
    • addedInput schema / properties / currency
      Added value: +{
      +  "description": "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.",
      +  "pattern": "^[A-Z]{3}$",
      +  "type": "string"
      +}
    • changedInput schema / properties / user_country / description
      Previous value: -"User's country (ISO-3166 alpha-2 uppercase). Drives the booking link locale; pass the user's own country, not the property's home country. Falls back to 'IT' when omitted."New value: +"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."
  6. Changed1 schema field changed
    • changedInput schema / properties / api_key / description
      Previous value: -"Your anonymous b2a Bluepillow API key (format 'pk_anon_…'). If you do NOT already have one — check your MCP client configuration, your persistent memory, and earlier in this conversation first — call `b2a_get_key` to obtain one before calling this tool (do not wait for a 401). PRIMARY way to authenticate: pass the key here on every call. Clients able to attach an HTTP 'Authorization: Bearer <key>' header may do that instead and omit this field — but passing it here always works and is the recommended path for tool calls. The key is not a sensitive secret: it carries no account, payment, or personal data; reuse the same key on every call."New value: +"Your anonymous Blue Pillow Hotels & Stays API key (format 'pk_anon_…'). If you do NOT already have one — check your MCP client configuration, your persistent memory, and earlier in this conversation first — call `b2a_get_key` to obtain one before calling this tool (do not wait for a 401). PRIMARY way to authenticate: pass the key here on every call. Clients able to attach an HTTP 'Authorization: Bearer <key>' header may do that instead and omit this field — but passing it here always works and is the recommended path for tool calls. The key is not a sensitive secret: it carries no account, payment, or personal data; reuse the same key on every call."
  7. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover the safety profile (readOnly/openWorld/non-destructive); the description adds substantial behavioral context beyond them: live date-aware lookup, past-date rejection at the API boundary, the currency fallback chain and its USD default, the tracking nature of `deeplink_url` ('pass verbatim, never reconstruct'), and the curated ranking semantics of `offers[0]` (not necessarily cheapest, sort=price_asc for pure price order). It also prescribes explicit handling of the `unavailable` terminal state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded — purpose, then routing, then inputs, then response shape — with headers that make it skimmable. It is nonetheless long, and a few points are stated twice (booking URLs must not be hand-reconstructed appears in both the deeplink bullet and the closing line; the 'surface unavailable explicitly' instruction appears twice), so it is not maximally tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter, nested-object, availability-driven tool with an output schema, this covers everything an agent needs: required inputs, the three availability states and what each implies for the user, per-night vs total disambiguation, scarcity and refundability as decision factors, and the fallback behavior when all operators are unavailable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description nonetheless reinforces interpretively non-obvious points — that `user_country`/`currency`/`language` are the USER's locale and not the property's, that omitting both currency inputs silently yields USD, and that `property_id` may be a raw prop_ id or a pasted bluepillow.com URL. It doesn't add much beyond the schema text, but the locale-vs-property framing and the 'don't rely on the USD default' instruction carry real selection value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb (live lookup) and resource (availability + per-operator quotes for a stay), with the exact scope of the window. It explicitly distinguishes itself from the sibling `get_property_details` — 'what is this property like' (static) vs 'can I book it for these dates at what price' (live) — so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the triggering condition ('user has specific dates in mind for a property they already identified — typically via search_stays or get_property_details') and names the alternative tools and follow-up scenarios (checking other dates/guests, reusing a prior `id`). This is explicit when-to-use plus when-to-use-something-else.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources