DIDA Hotel MCPofficial
A
license-
qualityB
maintenanceEnables AI agents to search, compare, and book hotels with real-time pricing and availability, supporting multiple location types, star ratings, and price filters.
4
MIT
Blue Pillow Hotels & Stays
Ownership verified
Server Details
Neutral hotel & stay price comparison for AI agents: live prices from 16+ booking sites. No signup.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
MCP client
Glama
MCP server
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
100% free. Your data is private.
Tool Definition Quality
A4.4/5.0
Tool DescriptionsA
Average 4.8/5 across 6 of 6 tools scored.
Server CoherenceA
Disambiguation4/5
Tools are mostly distinct: resolve_destination and discover_destinations_near both produce destination IDs but differ in input (name vs coordinates/radius), which the descriptions clarify well. get_property_details and check_property_availability are explicitly differentiated (static 'what is it like' vs live 'can I book for dates'). Minor overlap only between the two destination-resolution tools.
Naming Consistency2/5
Naming is inconsistent. Most tools use verb_object pattern (resolve_destination, search_stays, check_property_availability, get_property_details), but b2a_get_key breaks this entirely with its obscure 'b2a' prefix and mixed capitalization, and discover_destinations_near is inconsistent with the others (verb_plural instead of verb_single). The b2a_get_key name is notably cryptic and doesn't convey its purpose.
Tool Count5/5
Six tools is well-scoped for a hotel search/booker MCP server. Each tool fills a distinct role: key acquisition, destination resolution, area discovery, search/comparison, property details, and availability/pricing. No redundancy and no bloat.
Completeness4/5
The core workflow (resolve → search → compare → get details → check availability → book via link) is well covered. Minor gaps: there's no explicit cancellation/form-fill tool (though booking handoff via deeplink covers this) and no pagination-specific helper beyond cursors. Overall the travel journey is complete for a search-and-compare server.
Available Tools
6 toolsb2a_get_keyGet an anonymous API key for Blue Pillow Hotels & StaysAInspect
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).
Clients that can persist configuration usually store the key in their connector settings, so the same key serves every conversation. Clients whose memory does not retain an opaque token end up issuing one key per conversation; that works and is not an error, but a stored key gives more consistent rate-limit headroom.
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.
Integrators who need higher limits, or who hit a problem worth reporting, can write to info@bluepillow.com.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent | No | Optional agent identifier recorded on the key — useful when an agent platform wants to attribute issuance to itself (e.g. 'claude-code', 'cursor-ide'). Free-form, max 64 chars. | |
| label | No | Optional free-form label recorded on the key for observability (e.g. 'claude-desktop' or a user handle). Not a secret, not validated for uniqueness. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| key | Yes | The anonymous API key (prefix 'pk_anon_'). Long-lived and reusable: pass it as the `api_key` argument on every subsequent tool call, and keep it across sessions. |
| rate_limit | No | Quota attached to this key, when the issuer reported one. |
Tool Definition Quality
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by explaining key safety traits: the key is not a sensitive secret, carries no personal data, never expires, and has a per-IP anti-abuse limit. It also clarifies that label/agent parameters are for observability only and do not affect rate limits—none of which is evident from the sparse annotations. There is no contradiction with annotations.
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?
The description is lengthy but intentionally so—it front-loads the core purpose and then covers key characteristics, usage instructions, persistence, parameters, and contact info, with each sentence earning its place. A slight trimming (e.g., the contact paragraph) could tighten it, but the structure is logical and scannable.
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?
Given that the tool has no required parameters and an output schema exists, the description fully covers the essential context: when to call, key properties, reuse guidance, rate-limit behavior, parameter semantics, and fallback contact for higher limits. It is complete even without describing the response format, since the output schema handles that.
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?
The schema already documents both optional parameters (label, agent) with examples, and schema coverage is 100%. The description adds value by explaining that these are 'free-form hints we record on the key for our own observability' and that they 'do not affect rate limits or capabilities,' which supplements the schema without repeating it.
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 description opens with 'Obtain a permanent anonymous API key for Blue Pillow Hotels & Stays,' a specific verb+resource that clearly defines the tool's function. It also distinguishes itself from all sibling tools by establishing itself as the prerequisite key-issuing tool that every other tool depends on.
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?
The description gives explicit when-to-use guidance: 'CALL THIS FIRST when you have no key: every other tool needs one' and instructs agents to reuse an existing key instead of issuing a new one. It also provides clear exclusion guidance (don't wait for a 401) and discusses persistence behavior across different client types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_property_availabilityCheck live availability and per-operator quotes for a stayARead-onlyInspect
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, 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.
ParametersJSON 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
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| 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). |
Tool Definition Quality
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint and openWorldHint, but the description adds substantial behavioral context: live date-aware lookup, availability_status semantics (available/unavailable/unknown), offers[0] ranking (best value not cheapest), deeplink_url tracked-redirect must be passed verbatim, currency fallback order (currency > user_country > USD), and per-night vs total pricing. No contradiction with annotations.
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?
The description is long but well-structured and front-loaded with the core purpose. It uses bold/emphasis for key warnings ('per-night', 'total', 'BluePillow tracked-redirect URL') and organizes content into a logical flow (purpose, usage, response shape, edge cases). Some redundancy with the schema descriptions exists, but for a complex tool with seven parameters and many behavioral nuances, the length is justified.
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?
Given the tool's complexity and the presence of an output schema, the description goes beyond what's strictly required: it details response shape, offers ranking logic, deeplink handling, scarcity signals, unavailable handling, and instructions for final booking confirmation. It covers edge cases (past dates rejected, USD default, null price when unavailable) and provides all necessary context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with rich descriptions. The tool description mostly reiterates schema information (property_id forms, natural-language dates, currency behavior, api_key necessity) rather than adding materially new parameter semantics. The few additions (e.g., 'never convert prices yourself') are marginal, so baseline 3 is appropriate.
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 description opens with a specific verb + resource + scope: 'Live availability and per-operator quote for a specific property over a specific stay window.' It clearly distinguishes from sibling get_property_details by contrasting static facts ('what is this property like') with live, date-specific booking data ('can I book it for these dates at what price').
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?
Explicitly states when to use the tool: 'Useful when the user has specific dates in mind for a property they already identified — typically via search_stays or get_property_details.' It also names the complementary sibling get_property_details and explains the division of labor. Required inputs are listed with guidance on natural-language dates and avoiding the USD default.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
discover_destinations_nearDiscover destinations near a pointARead-onlyInspect
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude of the centre point, decimal degrees (WGS84). Typically the coordinates of a city or region already known from world knowledge or from an earlier resolve_destination call. | |
| lon | Yes | Longitude of the centre point, decimal degrees (WGS84). Negative west of Greenwich. | |
| type | No | Optional filter; same semantics as resolve_destination. | |
| 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. | |
| language | No | Language of the returned destination names (2-letter lowercase). Pass the language the user is speaking; defaults to 'en'. | en |
| radius_km | No | Search radius in km from the point. Defaults to 5 km (city-center scope). |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| candidates | Yes | |
| total_matches | Yes | |
| total_matches_capped_at | No |
Tool Definition Quality
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint=true and openWorldHint=true annotations, the description adds meaningful detail: 'Returns up to 5 candidates ordered by distance', 'The radius defaults to 5 km; widens up to 50 km for broader queries', and explains the destination_id handoff. These behavior disclosures complement rather than contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact, well-structured paragraphs that front-load the core purpose ('Curated destinations within a radius... for use as a destination_id'), then address the fan-out use case, then behavior details (candidate count, ordering, radius defaults). Every sentence earns its place with zero filler.
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?
As a read-only discovery tool with 100% schema coverage, rich annotations, an output schema, and a clear handoff narrative to search_stays, the description is remarkably complete. It covers when, why, how (return format, defaults, ordering), and the integration with sibling tools. No meaningful gaps for an agent to trip on.
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 schema documents all parameters well. The description adds contextual value by explaining why each parameter matters (e.g., 'Typically the coordinates of a city or region already known from world knowledge'), and clarifies radius defaults versus widening behavior and the type filter's shared semantics with resolve_destination. Slight deduction since the description doesn't add param detail beyond what the rich schema already documents.
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 description uses a specific verb ('Discover curated destinations') with a clear resource (cities, neighborhoods, airports, POIs within a radius) and clearly states its downstream purpose (generating destination_id for search_stays). It distinguishes itself from siblings by explicitly framing 'as a fan-out entry point for region-level intents' and referencing resolve_destination semantics.
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?
Explicitly states when to use this tool ('when coordinates are already in hand' and 'when the agent needs to enumerate which curated destinations cover that area'), and covers the region-level fan-out scenario. It implicitly distinguishes from resolve_destination (which resolves by name) by framing this as coordinate-driven, giving clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_property_detailsGet property details — static facts, no live availabilityARead-onlyInspect
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. 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.
ParametersJSON 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
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| 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). |
Tool Definition Quality
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already marking readOnlyHint=true and openWorldHint, the description adds substantial behavioral context: the 0-5 rating scale, the fact that price is null and availability_status is 'unknown' without dates, the intentional capping of review texts with a reviews_meta block, and the localization fallback chain for currency. There is no contradiction with annotations.
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?
The description is well-structured with clear sections and front-loaded key information, but it is verbose and repeats similar points (e.g., no price without dates, the contrast with check_property_availability) multiple times. Each sentence ultimately earns its place, but tightening would improve conciseness.
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?
Given the tool's complexity (6 parameters, multiple include options, date-dependent price behavior, sibling tool relationship), the description covers every aspect: the need for an id, the opt-in review paths, the cap on review texts with meta details, the localization logic, and the explicit pointer to the live-availability sibling. With an output schema present, return values need no further explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema coverage is 100%, the description enriches the parameters significantly. It explains the include enum behavior in depth (reviews_aggregate vs sample vs extended, supersession, caps), clarifies that property_id accepts both opaque ids and URLs (auto-extraction), and details the interaction between user_country/currency/language for pricing and booking-link localization — all beyond the schema text.
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 description clearly states the tool returns a static record for a specific property by id, enumerates the exact fields (amenity list, photos, booking sources, dedup metadata, location, headline rating), and explicitly contrasts with check_property_availability. This gives a specific verb+resource+scope and fully distinguishes it from sibling tools.
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?
The description explicitly says when to use this tool ('when the user wants to inspect or compare a specific option in depth... without committing to dates'), when NOT to use it (for live availability/quote), and names the alternative (check_property_availability). It also prescribes the workflow to obtain a property id via search_stays. This is beyond the minimum required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
resolve_destinationResolve destination name to idARead-onlyInspect
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, written locally or in English. Names are matched against Blue Pillow's own place slugs, which exist for English, Italian, German and Spanish; in other languages the English name is the most reliable. Accents are optional — 'São Paulo' and 'Sao Paulo' resolve alike. A qualifier after the name is tolerated ('Austin, Texas'). 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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Destination name in English or canonical local form (not a translation). | |
| type | No | Destination kind. city: primary urban unit (default). neighborhood: quarter/borough. airport: airport as spatial reference for stays nearby. poi: point of interest as a spatial anchor for nearby-accommodation lookup — not a tourism/attraction database; narrowest match with partial coverage. When the agent already knows the POI's lat/lon from world knowledge, `search_stays` with coordinates is the more reliable path. | |
| 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. | |
| country | No | Country: ISO-3166 alpha-2 (preferred), alpha-3, or extended name in any supported language. Unrecognized values are silently ignored (fail-open). | |
| language | No | Render destination names + breadcrumbs in this language. | en |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| candidates | Yes | |
| total_matches | Yes | |
| total_matches_capped_at | No | |
| disambiguation_recommended | Yes |
Tool Definition Quality
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, and the description adds rich behavioral context beyond that: matching against Blue Pillow's place slugs, language-specific reliability, accent tolerance, qualifier handling, country-based disambiguation, and POI partial coverage. No contradiction exists between the annotations and the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries value: it front-loads the function and usage condition, then provides organized behavioral details and parameter-specific guidance. There is no filler or repetition of schema boilerplate; each addition clarifies matching behavior, language handling, or tool selection.
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?
Given the rich schema (100% coverage), an output schema, and annotations indicating read-only and open-world behavior, the description fully covers all necessary facets: return type, safety profile, parameter semantics, edge cases, and alternatives to other tools. No gaps remain for an agent to make an informed invocation decision.
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 adds meaning beyond the schema with concrete examples (São Paulo/Sao Paulo, Austin Texas, Springfield disambiguation) and explains the subtle behavior of the `type` parameter, particularly the POI caveat and the recommendation to use coordinates when possible. This exceeds the baseline but stops short of the highest level because the schema itself is already very detailed.
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 description uses a specific verb 'converts' and clearly specifies the resource: 'destination name into a destination id usable in `search_stays`.' It also differentiates from sibling tools by naming the consumer tool and positioning itself as the 'canonical entry point' for place-name resolution, distinguishing it from `discover_destinations_near` and `search_stays`.
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?
Explicitly states when to use (when user mentions a place name and coordinates are not already known) and when not to use (when coordinates are already in hand, pass them directly to `search_stays`). It also names the alternative path for POIs when the agent can geocode from world knowledge, satisfying the 'explicit when/when-not/alternatives' criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_staysSearch accommodation — compare offers across operatorsARead-onlyInspect
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.latandlocation.loncarry 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_urlcarries 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.imageson search results is capped to the first photo to keep the comparison payload compact; each item has aurlfield, andthumbnail_urlmirrorsimages[0].url. Callget_property_detailsfor a single property to retrieve its full photo gallery.web_urlis 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).
priceandoffers[]— 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 carriesamount(total stay),amount_per_night(per-night),currency,breakfast_included,refundable,rooms_left, anddeeplink_url.pricemirrorsoffers[0].With no dates (or when nothing is available)
priceis null andoffersis empty — surface the property without a price rather than inventing a starting figure.
availability_statusper result encodes the live state:available— bookable rooms confirmed at the operator level.offersandpricecarry the live date-specific quotes. Quote the rate viaoffers[i].amount_per_night(per-night) andoffers[i].amount(total stay) and use the deeplinks for the booking handoff.unavailable— no rooms reported for those dates.offersis empty andpriceis 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 usable answer for those dates: either the request carried no dates, or the operators returned nothing conclusive for them.offersis empty andpriceis null. This is the most frequent of the three states, and it is NOT evidence that the property is full — it means the availability was not established. Say "I could not confirm availability", not "it is unavailable".
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
availableproperties are in the results, the rate can be quoted androoms_leftsurfaces 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 includesota,amount,amount_per_night,currency,breakfast_included,refundable, and adeeplink_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.pricemirrorsoffers[0], which 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: passsort=price_ascfor pure price order, and compareoffers[]for the per-operator spread. When no dates were passed (or nothing is available)offersis an empty list andpriceis 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 anyoffers[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 tobreakfast_includedwhen it's true for some offers but not all.Prices in
offers/pricereflect the requested dates and guests; with no dates there is no price. For a final bookable confirmation, the correspondingdeeplink_url(or the property'sweb_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 underdistribution_by_ota, eachreviews_sample[*].score, and thefilters.min_ratinginput. A user asking "rating at least 8 out of 10" maps tomin_rating: 4.0; "at least 4 stars on Google" maps tomin_rating: 4.0.ratingis coarse in practice — upstream scores arrive rounded, so in the field it takes whole points, andmin_ratingbehaves like a filter with a handful of steps rather than a continuous threshold. Always readratingtogether withrating_count: a 4 from 6 reviews and a 4 from 2,803 are not the same judgement, and a rounded 4 can sit on either side of "good". Prefer properties with a substantialrating_countwhen recommending, and say how many reviews back the score. Note:rating,stars, andrating_countcome 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, callget_property_detailsto get the fullerreviews_aggregate. On the search path,reviews_aggregatecarries the top-linescore_0_5,rating_count(reviews backing the score) andcomment_count(readable review TEXTS available) when the comparator returned a non-zero review count;distribution_by_otais always empty on this path (per-OTA breakdown requiresget_property_details).rating_countandcomment_countare DIFFERENT magnitudes — most guests leave a rating, far fewer write text. Quoterating_countfor "how many reviewed it" andcomment_countfor "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 — callget_property_detailswithinclude=["reviews_extended"](and/orreviews_aggregate).comment_counton 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 thatbboxor a parent destination is the right shape).destination_id: opaque id obtained fromresolve_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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Pagination. `limit` caps results per page (1-100). To fetch the next page pass `cursor` with the `next_cursor` value from the previous response — cursors are opaque and are never constructed by hand. | |
| sort | No | Result ordering. score_desc (default) is the balanced relevance ranking and suits most requests; price_asc when the user asked for the cheapest; rating_desc when they asked for the best-reviewed; conversion_desc favours what comparable travellers actually booked. | |
| dates | Yes | Check-in and check-out dates (ISO 8601, YYYY-MM-DD). Natural-language references — 'tonight', 'this 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. The comparator only serves future stays: check_in is a date in the real-time calendar that is today or later. A reference like 'the weekend of June 2' resolves to the next occurrence after today, never a past anniversary; if the current year is unclear, confirm with the user before calling. Clock calibration: this schema was published in August 2026, so today is August 2026 OR LATER (likely later — schemas outlive their publish date). An assumed 'today' in 2024/2025 is a stale training-time clock; years before 2026 are always in the past. Past check_in values are rejected at the API boundary with a hint carrying the actual current date. | |
| guests | Yes | Party composition. `adults` is required; give `children_ages` (one age per child, 0-17) rather than a child count — operators price by age. `rooms` defaults to 1; raise it when the party needs separate rooms rather than one shared. | |
| 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. | |
| filters | No | Structured narrowing applied server-side, before ranking. Prefer these over filtering the results yourself: they run across the whole inventory, not just the page you received. Qualitative criteria that do not map here ("quiet", "great breakfast") are better served by include=['reviews_sample']. | |
| include | No | Optional enrichments, always a list — pass ["reviews_sample"], never the bare string. 'reviews_sample' attaches the 5 most recent individual reviews per property — use for qualitative queries (breakfast, service, ...). One extra Mongo round-trip per page; omit by default. | |
| 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, which may not be the user's. Prices come straight from the booking sources in this currency; never convert them yourself. Each offer reflects the currency its operator actually quoted. | |
| language | No | User's UI language (2-letter lowercase). Drives the booking link language and any server-rendered narrative content. Pass the language the user is currently speaking. Falls back to 'en' when omitted. | |
| location | Yes | Where to search, as a {type, value} pair. Use destination_id for a place resolved via resolve_destination, poi_id for a point of interest, coordinates for a known lat/lon, or bbox for an explicit map rectangle. A property is NOT a location — use get_property_details for a known property. | |
| user_country | No | User's country (ISO-3166 alpha-2 uppercase). Drives the booking-link locale (the landing page rendered when the user clicks `web_url`) AND, when `currency` is not set, the pricing currency (US->USD, CA->CAD, euro-area->EUR). Pass the user's own country, not the destination's. Falls back to 'US' when omitted. | |
| availability_mode | No | strict (default): return ONLY properties available for the requested dates. include_unavailable: also return properties with no availability (each tagged availability_status). Use strict unless the user explicitly wants to see sold-out options. | |
| include_overbudget | No | Opt-in. When few available results fit the budget, also return (in alternatives.overbudget) available properties in the same area just above price_max_eur. Requires filters.price_max_eur. | |
| include_out_of_bounds | No | Opt-in. When the requested area yields few available results, also return (in alternatives.out_of_bounds) properties just outside the area, within the original budget. Present these explicitly as alternatives, never mixed with primary results. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| page | Yes | |
| results | Yes | |
| metadata | Yes | |
| alternatives | No |
Tool Definition Quality
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the readOnlyHint and openWorldHint annotations, explaining live price semantics, availability_status meanings (including that 'unknown' does not mean unavailable), currency defaults, deeplink tracking redirects, rating-scale quirks, and the limitation that rating/stars may be absent. It also warns about client-side conversion and provides explicit user-facing phrasing guidance.
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?
The description is well-structured with clear sections, bullets, and bolded terms, but it is extremely long and repetitious (e.g., the availability_status semantics and price-null behavior are explained multiple times). While most content is useful, it could be trimmed without loss of information.
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?
Despite an output schema being present, the description thoroughly covers edge cases, alternative tools, parameter interactions, and user-facing output formatting. It addresses failure modes, currency defaults, review-rating scale, and pagination—comprehensive for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds some value by explaining currency/user_country fallback behavior and pagination cursors, but it also contains a contradiction: the description states 'Amenities filter is set-AND — each result has ALL listed codes', while the schema explicitly says amenities 'ranks, does not filter' and 'nothing is dropped'. This inconsistency could mislead an agent into treating amenities as a hard filter.
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 description clearly states the tool is a multi-operator accommodation comparator that returns a ranked list of properties with booking sources, live availability, and per-operator prices for given dates/guests. It differentiates from siblings by explicitly excluding property_id locations and directing to get_property_details for single-property deep dives.
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?
Extensive when-to-use guidance is provided, including explicit alternatives: 'get_property_details is the path for a known property', 'call get_property_details to get the fuller reviews_aggregate', and 'review-based reasoning is one extra round-trip per page and is typically reserved for fallback'. It also clarifies location modes, when to use include=['reviews_sample'], and how to handle availability states in user-facing output.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!
Related MCP Servers
Dida Hotel MCPofficial
Alicense-qualityBmaintenanceEnables AI agents to search and book hotels globally with real-time pricing and inventory from over 2 million properties.93MIT
RollingGo Hotel MCPofficial
Alicense-qualityBmaintenanceEnables AI agents to search, compare, and book hotels worldwide through natural language, with real-time pricing and availability, plus price monitoring and order management.4MIT- Alicense-qualityBmaintenanceBook hotels worldwide — search, price, prebook & book across 249 countries. 65 tools for hotel search, flights, loyalty, analytics. Zero API keys needed. at best prices for hotels 3 M+ property91MIT