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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "property_id": "<property_id>",
      "dates": "<dates>",
      "guests": "<guests>"
    },
    "name": "check_property_availability"
  }
}

Input 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

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
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. Changed2 schema fields changed
    • removedOutput schema / properties / cluster_id
      Removed value: -{
      -  "type": [
      -    "string",
      -    "null"
      -  ]
      -}
    • removedOutput schema / properties / dedup_meta
      Removed value: -{
      -  "properties": {
      -    "confidence": {
      -      "type": "number"
      -    },
      -    "last_reconciled": {
      -      "type": "string"
      -    },
      -    "source_listings": {
      -      "type": "integer"
      -    }
      -  },
      -  "type": [
      -    "object",
      -    "null"
      -  ]
      -}
  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 `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."
  3. 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."
  4. 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."
  5. 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."
  6. 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."
  7. 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."
  8. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses the live-lookup nature of the call, the API-boundary rejection of past check_in dates, the currency fallback chain (currency → user_country → USD) with an explicit warning not to rely on the USD default, the ranking semantics of offers[0] (best value, not cheapest), and the critical constraint that deeplink_url is a tracked redirect that must be passed verbatim. These are non-obvious behaviors an agent could easily get wrong.

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

Conciseness3/5

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

Well front-loaded and sectioned, but long, and a substantial block restates the response shape even though an output schema already exists — the offers[]/price/availability_status field walkthroughs duplicate structured data. The deeplink-verbatim rule and the 'unavailable → suggest alternate dates' guidance each appear twice, which is avoidable bloat.

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 nested-schema, open-world, live-quote tool the description leaves nothing essential uncovered: required inputs, date normalization from natural language, guest composition, locale-driven pricing, availability semantics, scarcity and refundability signals to surface, and the booking handoff path. The only redundancy is response-shape detail that the output schema already carries.

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 adds value by framing the fallback chain for currency/user_country and by stressing 'pass user_country and/or currency whenever you know the user's location' rather than letting the USD default silently apply. It also restates that user_country/language are the user's locale, not the property's. This is largely reinforcement of the schema rather than new semantics, so it stops short of 5.

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?

States a specific verb and resource ('live availability and per-operator quote for a specific property over a stay window') and explicitly demarcates it from siblings: get_property_details answers 'what is this property like' via static facts while this tool answers 'can I book it for these dates at what price'. An agent can route between the two 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?

Gives explicit triggers ('user has specific dates in mind for a property they already identified — typically via search_stays or get_property_details'), names the alternative tools and their distinct purposes, and covers the follow-up-question case where a search_stays result's id should be reused. Exclusions and alternatives are both present.

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