Get property details — static facts, no live availability
get_property_detailsStatic 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. Supersedesreviews_samplewhen 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| include | No | Optional enrichments, always a list — pass ["reviews_aggregate"], never the bare string. reviews_aggregate = score + total count + per-OTA distribution (summarizes ALL reviews). reviews_sample = up to 5 recent review texts. reviews_extended = up to 20 recent review texts (supersedes reviews_sample). The text list is intentionally capped to save tokens; reviews_meta declares returned vs available. Prefer reviews_sample and the aggregate; use reviews_extended only when a deeper qualitative read is genuinely needed. | |
| 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 and server-rendered narrative; pass the language the user is speaking. 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). |