Live hotel search and booking for AI agents in DACH, the UK and 10 US cities.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Book a hotel room. Works for ANY offer `list_hotels` gave you an `offerId` for — there is no separate check to make first, so pass the offer the guest chose. Pass that offer’s `offerId` exactly as you were given it — it names the hotel, room, rate, stay and price, which is why none of those are separate arguments. It expires after 30 minutes; if it has expired or the hotel has raised the price since, nothing is booked — get a fresh one by calling `list_hotels` with that same `offerId`, which re-prices just that room rather than showing the guest the whole property again. TWO OUTCOMES, and the reply tells you which. `confirmationNumber` means the room is booked: give the guest the number and tell them they pay the hotel at the desk — nothing has been charged. `paymentUrl` means the room is NOT held yet: give the guest that link to pay, their card is HELD rather than charged, and the booking is placed once they have paid. Set `acceptedTerms` only after the guest has agreed to book this rate. Show them that rate’s cancellation terms where `list_hotels` gave any; where its `cancelTerms` was null we hold none, so say so and that the hotel’s own terms apply, then set it once they agree on that basis — a blank is NOT a reason to refuse the booking. Ask the guest for their own phone number and billing address — the hotel puts them on the reservation and uses them to reach the guest. Never invent them. If a call comes back ambiguous, do NOT call again — a reservation may already exist.
The `offerId` of the exact room and rate the guest chose, copied from `list_hotels` unchanged. It names the hotel, the room, the rate, the stay, the party and the price the guest was shown, so none of those are passed separately. It is valid for 30 minutes — if the guest takes longer to decide, call `list_hotels` with this same `offerId` to get a fresh one: it re-prices that one room and nothing else, so the guest is not shown the whole property a second time. Never edit it or build one yourself.
The hotel sends its confirmation here. It is the guest's own address, never yours. An example or placeholder address such as [email protected] is refused and nothing is reserved: ask the guest for the address they actually use.
The guest's phone number, in any format the guest gives it.
Postal code.
Street and house number.
Two-letter country code, e.g. DE, AT, CH. The country the guest lives in, not the one they are travelling to.
TRUE only when the guest has agreed to book this rate. Where `list_hotels` gave that rate cancellation terms, show them first and get the agreement to those. Where its `cancelTerms` was null WE HOLD NONE — tell the guest plainly that we do not have this rate’s cancellation terms and that the hotel’s own terms apply and reach them with the hotel’s confirmation, then set this once they have said to go ahead knowing that. Never assume it on their behalf, and never treat a blank as a reason not to book.
House number, when the guest gives it separately from the street.
How the guest is addressed, in their own words. Only pass what the guest told you; never guess from a name.
The server marks this tool as destructive. Running it may delete or overwrite data on the server or in any account you connected with your headers.
Pick your client. Values in capitals, like YOUR_TOKEN, are yours to fill in.
Run in a terminal
claude mcp add --transport http hotels https://402.bluerails.com/mcp
Book a hotel room. Works for ANY offer `list_hotels` gave you an `offerId` for — there is no separate check to make first, so pass the offer the guest chose. Pass that offer’s `offerId` exactly as you were given it — it names the hotel, room, rate, stay and price, which is why none of those are separate arguments. It expires after 30 minutes; if it has expired or the hotel has raised the price since, nothing is booked — get a fresh one by calling `list_hotels` with that same `offerId`, which re-prices just that room rather than showing the guest the whole property again. TWO OUTCOMES, and the reply tells you which. `confirmationNumber` means the room is booked: give the guest the number and tell them they pay the hotel at the desk — nothing has been charged. `paymentUrl` means the room is NOT held yet: give the guest that link to pay, their card is HELD rather than charged, and the booking is placed once they have paid. Set `acceptedTerms` only after the guest has agreed to book this rate. Show them that rate’s cancellation terms where `list_hotels` gave any; where its `cancelTerms` was null we hold none, so say so and that the hotel’s own terms apply, then set it once they agree on that basis — a blank is NOT a reason to refuse the booking. Ask the guest for their own phone number and billing address — the hotel puts them on the reservation and uses them to reach the guest. Never invent them. If a call comes back ambiguous, do NOT call again — a reservation may already exist.
| Argument | Type | Description |
|---|---|---|
| offerId* | string | The `offerId` of the exact room and rate the guest chose, copied from `list_hotels` unchanged. It names the hotel, the room, the rate, the stay, the party and the price the guest was shown, so none of those are passed separately. It is valid for 30 minutes — if the guest takes longer to decide, call `list_hotels` with this same `offerId` to get a fresh one: it re-prices that one room and nothing else, so the guest is not shown the whole property a second time. Never edit it or build one yourself. |
| guestCity* | string | |
| guestEmail* | string | The hotel sends its confirmation here. It is the guest's own address, never yours. An example or placeholder address such as [email protected] is refused and nothing is reserved: ask the guest for the address they actually use. |
| guestPhone* | string | The guest's phone number, in any format the guest gives it. |
| guestPostal* | string | Postal code. |
| guestStreet* | string | Street and house number. |
| guestCountry* | string | Two-letter country code, e.g. DE, AT, CH. The country the guest lives in, not the one they are travelling to. |
| acceptedTerms* | boolean | TRUE only when the guest has agreed to book this rate. Where `list_hotels` gave that rate cancellation terms, show them first and get the agreement to those. Where its `cancelTerms` was null WE HOLD NONE — tell the guest plainly that we do not have this rate’s cancellation terms and that the hotel’s own terms apply and reach them with the hotel’s confirmation, then set this once they have said to go ahead knowing that. Never assume it on their behalf, and never treat a blank as a reason not to book. |
| guestLastName* | string | |
| guestStreetNo | string | House number, when the guest gives it separately from the street. |
| guestGivenName* | string | |
| guestSalutation | string | How the guest is addressed, in their own words. Only pass what the guest told you; never guess from a name. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"offerId",
"guestGivenName",
"guestLastName",
"guestEmail",
"guestPhone",
"guestStreet",
"guestPostal",
"guestCity",
"guestCountry",
"acceptedTerms"
],
"properties": {
"offerId": {
"type": "string",
"maxLength": 2000,
"minLength": 1,
"description": "The `offerId` of the exact room and rate the guest chose, copied from `list_hotels` unchanged. It names the hotel, the room, the rate, the stay, the party and the price the guest was shown, so none of those are passed separately. It is valid for 30 minutes — if the guest takes longer to decide, call `list_hotels` with this same `offerId` to get a fresh one: it re-prices that one room and nothing else, so the guest is not shown the whole property a second time. Never edit it or build one yourself."
},
"guestCity": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"guestEmail": {
"type": "string",
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"maxLength": 200,
"description": "The hotel sends its confirmation here. It is the guest's own address, never yours. An example or placeholder address such as [email protected] is refused and nothing is reserved: ask the guest for the address they actually use."
},
"guestPhone": {
"type": "string",
"maxLength": 40,
"minLength": 3,
"description": "The guest's phone number, in any format the guest gives it."
},
"guestPostal": {
"type": "string",
"maxLength": 20,
"minLength": 1,
"description": "Postal code."
},
"guestStreet": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Street and house number."
},
"guestCountry": {
"type": "string",
"maxLength": 2,
"minLength": 2,
"description": "Two-letter country code, e.g. DE, AT, CH. The country the guest lives in, not the one they are travelling to."
},
"acceptedTerms": {
"type": "boolean",
"description": "TRUE only when the guest has agreed to book this rate. Where `list_hotels` gave that rate cancellation terms, show them first and get the agreement to those. Where its `cancelTerms` was null WE HOLD NONE — tell the guest plainly that we do not have this rate’s cancellation terms and that the hotel’s own terms apply and reach them with the hotel’s confirmation, then set this once they have said to go ahead knowing that. Never assume it on their behalf, and never treat a blank as a reason not to book."
},
"guestLastName": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"guestStreetNo": {
"type": "string",
"maxLength": 20,
"description": "House number, when the guest gives it separately from the street."
},
"guestGivenName": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"guestSalutation": {
"type": "string",
"maxLength": 40,
"description": "How the guest is addressed, in their own words. Only pass what the guest told you; never guess from a name."
}
}
}Search hotel properties in Germany, Austria, Switzerland, the United Kingdom and the United States, and price them for a stay in the same call. ASK BEFORE YOU SEARCH. Four things are required and this tool answers nothing without them: `checkIn`, `checkOut`, `adults` and `maxPricePerNight`. "Hotels in Berlin for a couple" is not yet a search — it names a place and a party and nothing else, so ask which nights they want, who is coming — adults AND any children, by age — and roughly what they want to spend, in ONE message, and search once they answer. Never fill these in for them: dates you chose are not their dates, and a budget read off "cheap" or off a star rating hides the very hotels they could have afforded. A call missing any of them comes back with no rows and a `hint` naming what is still to be asked. PLACES. Pass `city` with any place name we cover to get properties around it, nearest first, each with `distanceKm` — despite the name it takes a place of any size, so a village, a resort or a borough ("Silvaplana", "Wals", "Zell am See", "Brooklyn") works as well as a city. `radius` is a value with its unit — {"value": 10, "unit": "mi"} — so you never have to convert; it defaults to 20 km and may not exceed 100 km. Prefer `city` over `query` for place-based searches: it understands about 151,800 places and returns neighbouring towns, whereas `query` only matches words in a name or description. An unresolvable place name returns `placeNotRecognised` — that means the NAME was not understood, not that the place has no hotels. When a radius returns nothing you get `nearestBeyondRadiusKm` so you can widen deliberately rather than guess. SOMEWHERE SMALLER THAN A TOWN — A STREET, A LANDMARK, A STATION, A DISTRICT — GOES IN `coordinates`, NOT `city`. Sent as a `city`, such a name is either refused or resolved to a different place of the same name, which comes back as a confident answer about somewhere else. Estimate the point yourself, pair it with a small `radius`, and tell the guest you estimated it. A STAY. `checkIn`, `checkOut` and `adults` are required, and when you ask how many adults, ASK WHETHER ANY CHILDREN ARE COMING TOO and send their ages in `childrenAges` — ages, not a count. A child left out is priced as though they are not coming, so the guest can book a room that will not sleep them. The moment the guest mentions a child, put it in `childrenAges` even if you do not yet know the age — send `null` for that entry: THE SEARCH IS THEN REFUSED until you replace it with the real age, which is what stops a family being quoted as a couple. With those, the answer comes back in TWO groups. `priced` holds the hotels we read real rates for: every room and rate plan with its own `price` for the WHOLE stay, in the `currency` you sent, its `cancelTerms` where we hold any and null where we do not, its photos where we have them, a `bookingUrl` carrying the guest's dates WHERE THIS ENDPOINT PUBLISHES ONE — read that field's own description rather than assuming it is there, because an endpoint that can book the room for you publishes no link for it — and `stayTotal` / `pricePerNight` for the cheapest offer. EVERY PRICE IS IN THE `currency` YOU SENT. They come back in a deliberate order that is NOT nearest first and NOT cheapest first — show them in the order you are given. Show all the rooms you are handed, not just the cheapest. `unpriced` holds everything else: hotels that do not publish rates anywhere we can read, that did not answer us, or that were past the read ceiling. Those are the same thing to you — NONE of them carries a booking link of any kind. What a row carries instead is `websiteUrl`, the property's own site, or an EMPTY `websiteUrl` when we hold no site either and there is nothing to open at all. WHEN YOU RECOMMEND A HOTEL, RECOMMEND A PRICED ONE. We hold no rate for anything in `unpriced`, so you cannot say what it costs and it may be well over what the guest wants to spend; naming one as your suggestion answers their budget with a number nobody has. Bring one up only as "I could not get a rate for X, here is their website". Offer that site as the property's website and NEVER as a way to book or check rates, since we do not know it sells rooms online — and where it is empty, say we have nowhere to send them rather than going looking for a page of your own. AN EMPTY `priced` IS NOT "SOLD OUT", AND CHECK `aboveBudget` BEFORE CALLING IT UNREADABLE. With a `maxPricePerNight`, an empty `priced` means every hotel we priced costs more than that, and those hotels are in `aboveBudget` with real prices — quote them. Only when `aboveBudget` is empty too does an empty `priced` mean no rates could be read, and even then we get the same empty answer for a connection that failed, a party the property will not sell to, and a genuinely full hotel, and it never says which — so report the price as unknown and hand over the links, NEVER that a property is full. No ROW in this response can tell you a hotel has no space. One thing can: the `hint`, which says how many properties were left out because they told us outright that they are full — that is why they are in no group at all, and it is the only "full" this tool ever reports. It is never about a hotel you can see. A BUDGET IS A FILTER, NOT A LABEL — AND IT IS THE GUEST'S NUMBER, NEVER YOURS. `maxPricePerNight` is required, so ask them for a figure before searching rather than sending one of your own. Words like "budget", "cheap" or "affordable" are not amounts: read as one they filter out the very hotels the guest wanted, and the answer then tells them their limit was missed when they set no limit. A guest who says they have no limit still has a most-they-would-pay — ask for that and send it. `maxPricePerNight` decides what you are handed, at both levels. `priced` holds ONLY the hotels at or under it, each carrying ONLY its rooms at or under it — so every price you read out is one the guest already agreed to, and `priced` may be shorter than the `limit` you asked for. Dearer hotels are NOT in `priced`, NOT in `unpriced`, and not returned at all while any hotel fits: do not tell the guest this is every hotel in the area, and read the `hint`, which says how many were left out. Only when NOT ONE hotel fits do they come back, in `aboveBudget` — then say what the nearest options actually cost, never "nothing is available". A room in `priced` keeps ALL of its rate plans, including one dearer than the budget, so a breakfast or flexible rate is still there to offer as an upgrade. The comparison is `pricePerNight`, the stay total divided by nights — a stay AVERAGE, not a rate charged on every night, so say it that way. HOW MUCH ONE SEARCH RETURNS. `limit` is the ceiling across BOTH groups, priced first — an answer can be shorter when properties were dropped as full, defaulting to 10 and capped at 20. `unpriced` carries AT MOST 5 however large a `limit` you ask for, so raising `limit` buys you more PRICED hotels and never a longer list of names we hold no price for. THERE IS NO PAGING: one search returns one set of rows and there is no second page to ask for, so to reach anything past 20 properties, narrow the search — a nearer `city`, a smaller `radius`, a `query`, `country` or `starRating`. Calling again with the same filters returns the same rows. No count of the whole match comes back either, so do not tell the guest how many properties exist in a place — say what you can show them. Also supports country (de, at, ch, us, gb), starRating (1-star, 2-star, 3-star, 4-star, 5-star) and style (boutique), which are independent of one another. Some place names exist in more than one of those countries, and `city` alone resolves them to THE MOST POPULOUS of them — "Cambridge" is England, not Massachusetts; "Bellevue" and "Salem" stay European. It is a proxy for the place a guest means, and it is sometimes wrong: "Kendal" resolves to the Kendall in Miami, not the Cumbrian town. Pass `country` alongside whenever you know which you mean, and ALWAYS when the guest named the country — it overrides the contest outright. Returns public fields only. BOOKING A ROOM FROM THIS ANSWER. Every priced room carries an `offerId` and NO booking link, because we can book it for the guest ourselves — call `hotel_reserve` with the `offerId` rather than sending them to a website. It needs the guest's full name, email, phone and address, so ask for those once they have chosen a room. It answers one of two ways: a `confirmationNumber` means the room is booked and the guest pays the hotel at the desk, and a `paymentUrl` means the room is not held yet and that link is where the guest pays to get it booked. Where a room's `cancelTerms` is null we hold no cancellation terms for it: say so plainly, say the hotel's own terms apply and come with its confirmation, and book once the guest agrees on that basis — a blank is not a refusal.
We read every tool's name, description and inputs the way the model will, looking for instructions hidden from you. A clean result means no warning signs, not a guarantee. Scanned Nov 5, 2026.
A very long tool description (over 4,000 characters) is hard to review and easy to hide instructions in.
Fix: Keep the description to what the tool does and when to use it; move reference material to resources or docs.
| Argument | Type | Description |
|---|---|---|
| city | string | Place to search around — any place name we cover, not just a city: a town, a village or a resort works, e.g. "Salzburg", "Munich", "Silvaplana", "Wals". Pass the place name ALONE, not a phrase: "Salzburg", never "10 miles from Salzburg" — say the distance in `radius` instead. Accents are folded away before lookup, so "München" is looked up as "munchen" and can collide with a smaller place of that same folded name — where a city has a common English name, prefer it: "Munich", not "München". Anything smaller than a town — a street, a landmark, a station, a district — belongs in `coordinates`, not here. Returns properties nearest first. |
| limit | integer | How many results to return. Defaults to 10, and may not exceed 20; a larger value is rejected, never quietly reduced. |
| query | string | Free-text match over a property’s NAME, short description and tags. It is NOT a natural-language request: EVERY word you pass must appear on the same property, so each extra word narrows the result and a whole sentence almost always matches nothing. Pass "spa munich", never "find me a nice spa hotel in Munich". Words match close to as written — the index is stemmed for English, so a German compound or inflection needs the form that actually appears on the listing. A place belongs in `city`, dates in `checkIn`/`checkOut`, a budget in `maxPricePerNight`; none of those are searched here, and a date or a price in `query` only empties the result. When a search that set `query` comes back empty, the reply carries a `hint` saying whether the text or the other filters emptied it. |
| style | string | Filter by how the property presents itself: boutique. Independent of starRating — combine them to ask for both. |
| adults | integer | Adults in the party. REQUIRED — ask how many people are travelling. Properties price by party size, so a number you assumed prices a stay nobody asked for. "A couple" is two; anything vaguer is a question. |
| radius | object | How far around `city` — or around `coordinates`, when you sent a point — to search, as a value and its unit: {"value": 10, "unit": "mi"}. Defaults to 20 km. May not exceed 100 km once converted; larger values are rejected, never quietly reduced. |
| checkIn | string | Arrival date, YYYY-MM-DD. REQUIRED — ask the guest for their dates before you search. Without them nothing can be priced and the answer would be a list of property names with no rooms, no prices and no results card. NEVER choose dates yourself, and do not read them out of a vague phrase: "next month" is not a date, it is a question to ask. |
| country | string | Filter by country: de=Germany, at=Austria, ch=Switzerland, us=United States, gb=United Kingdom |
| offerId | string | An `offerId` from an earlier answer, to get a fresh price for THAT room rather than searching again. Pass it when the guest has already chosen and you need a current handle — after `hotel_reserve` said the offer expired, or before asking them to confirm. The answer comes back as that one property carrying that one room with its rate plans, each with a new `offerId`, so you never have to work out which of several rooms was theirs. An offer older than 30 minutes still works here — this call is what refreshes it. EVERY OTHER SEARCH FIELD IS IGNORED when you pass this: `city`, `coordinates`, `radius`, `query`, `country`, `starRating`, `style`, `limit` and `maxPricePerNight` describe a search, and this is not one. `language` still applies. The stay comes from the handle, so leave the dates out to re-price the same nights; pass `checkIn`, `checkOut` and `adults` together to ask for the same room on different nights. THIS IS THE ONE CALL THAT NEEDS NO DATES AND NO BUDGET: a plain search is refused without them, but a handle already carries the stay it was quoted for, and a budget here could filter out the very room the guest chose. |
| checkOut | string | Departure date, YYYY-MM-DD. REQUIRED, on the same terms as `checkIn` — ask the guest, never choose. |
| currency | string | THE CURRENCY OF `maxPricePerNight`, AND THE ONE THE ANSWER IS QUOTED BACK IN. ISO 4217 — `EUR`, `CHF`, `GBP`. REQUIRED on every search: send `EUR` when the guest gave you a euro figure, which is most of the time. USE THE ONE THEY ALREADY NAMED and do not re-ask — "200 euros" is `EUR`, "CHF 165" is `CHF`. Ask them only when they gave a bare number and you genuinely cannot tell which currency they meant; guessing it is the thing this field exists to stop. IT ALSO CHOOSES THE CURRENCY THE ANSWER COMES BACK IN: every `price`, `stayTotal` and `pricePerNight` is in what you send here. It exists because a budget with no currency was read as euro, so a guest who said "CHF 165" was filtered at €165 and the hotels they could actually afford were not marked dear, they were absent. PASS THE GUEST’S OWN NUMBER and name its currency here; never convert it yourself. Quote them their own figure back; the prices you are handed are already in it. A currency we cannot get a rate for is REFUSED rather than assumed to be euro. |
| language | string | The language to render the results card in — pass the language the guest is WRITING in, unless they have asked for another. A bare language code or a full BCP 47 tag both work ("de", "de-AT", "en-GB"); only the language part is read, so a region suffix is harmless and case does not matter. German and English are rendered; any other value falls back to English rather than failing the search. Omit it and the card follows the guest’s own app language, then English. It changes ONLY the labels WE write on the card — never a room name or a rate plan, which stay in the property’s own words. A cancellation term carries the property’s own figures, but the sentence around them is written in English whatever language the card is in. |
| amenities | array | Facilities and house rules the property must ALL have — a hotel missing one is excluded, so every extra value narrows the result. Prefer this to naming an amenity in `query`: these are exact, while `query` matches only the words we happen to store. Naming one in `query` in either language ("swimming pool", "Schwimmbad") also works and resolves to these same values. |
| starRating | string | Filter by star rating: 1-star, 2-star, 3-star, 4-star, 5-star. A property can hold stars AND be a boutique hotel; ask for the two separately. |
| coordinates | object | A point to search around, for anywhere smaller than a town: a street, a landmark, a station, a junction, a named district. ESTIMATE IT YOURSELF for the place the guest named — `city` takes town names only, and a smaller name sent there is either refused or resolved to a different place of the same name, which comes back as a confident answer about somewhere else. Same shape as the `coordinates` on a hotel in the answer, so you can search around one you were just given. TAKES PRECEDENCE over `city` when both are sent: the point decides what is searched and which row leads, and `city` only names the place in the answer. Use `radius` to say how far around the point to look, and keep it small for a street or a venue. Tell the guest you estimated the point, so they can correct you. |
| childrenAges | array | ONE ENTRY PER CHILD — their age, or `null` when you do not know it yet. Not a count: properties price a child by its age, and none may be invented. ASK WHETHER ANYONE UNDER 18 IS TRAVELLING, in the same message as `adults`. The moment the guest mentions a child, put it here: send `[null]` if you have not asked the age yet and the search is REFUSED until you replace it with the real age, which is what stops a family being quoted as a couple. A child you leave out altogether is priced as though they are not coming — the quote is for the adults alone, and the room the guest books may not sleep them, which they find out at the desk. Leave the field out when there are no children — an EMPTY ARRAY says the same thing and is read as none. An age of 0 is a real age — an infant is a child, not nobody. |
| maxPricePerNight | integer | Budget per night, in the `currency` you send alongside it — BOTH ARE REQUIRED. TAKEN FROM A FIGURE THE GUEST GAVE YOU AND NOWHERE ELSE. Ask them roughly what they want to spend a night before you search: "a budget hotel", "somewhere cheap", "nothing too pricey" and a star rating are not amounts, and a figure you inferred hides every hotel they could have afforded behind a limit they never set. If they say they have no limit, ask for the most they would still pay and send that. PASS THE NUMBER THEY SAID AND NAME ITS CURRENCY — do not convert it yourself, and do not pass a euro figure you worked out from one they gave in francs or pounds. It FILTERS rather than labels. `priced` comes back holding ONLY the hotels at or under it, each carrying ONLY its rooms at or under it — so it can be shorter than `limit`, and it is not every hotel in the area. A kept room keeps all of its rate plans, including one dearer than the budget, so a breakfast rate is still there to offer. Dearer HOTELS are returned only when not one fits, in `aboveBudget`. Read the `hint`, which says how many were left out. Compares the stay average, not a nightly rate. |
{
"type": "object",
"anyOf": [
{
"required": [
"offerId"
]
},
{
"required": [
"checkIn",
"checkOut",
"adults",
"maxPricePerNight",
"currency"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"city": {
"type": "string",
"maxLength": 120,
"description": "Place to search around — any place name we cover, not just a city: a town, a village or a resort works, e.g. \"Salzburg\", \"Munich\", \"Silvaplana\", \"Wals\". Pass the place name ALONE, not a phrase: \"Salzburg\", never \"10 miles from Salzburg\" — say the distance in `radius` instead. Accents are folded away before lookup, so \"München\" is looked up as \"munchen\" and can collide with a smaller place of that same folded name — where a city has a common English name, prefer it: \"Munich\", not \"München\". Anything smaller than a town — a street, a landmark, a station, a district — belongs in `coordinates`, not here. Returns properties nearest first."
},
"limit": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "How many results to return. Defaults to 10, and may not exceed 20; a larger value is rejected, never quietly reduced."
},
"query": {
"type": "string",
"maxLength": 200,
"description": "Free-text match over a property’s NAME, short description and tags. It is NOT a natural-language request: EVERY word you pass must appear on the same property, so each extra word narrows the result and a whole sentence almost always matches nothing. Pass \"spa munich\", never \"find me a nice spa hotel in Munich\". Words match close to as written — the index is stemmed for English, so a German compound or inflection needs the form that actually appears on the listing. A place belongs in `city`, dates in `checkIn`/`checkOut`, a budget in `maxPricePerNight`; none of those are searched here, and a date or a price in `query` only empties the result. When a search that set `query` comes back empty, the reply carries a `hint` saying whether the text or the other filters emptied it."
},
"style": {
"enum": [
"boutique"
],
"type": "string",
"description": "Filter by how the property presents itself: boutique. Independent of starRating — combine them to ask for both."
},
"adults": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Adults in the party. REQUIRED — ask how many people are travelling. Properties price by party size, so a number you assumed prices a stay nobody asked for. \"A couple\" is two; anything vaguer is a question."
},
"radius": {
"type": "object",
"required": [
"value",
"unit"
],
"properties": {
"unit": {
"enum": [
"km",
"mi"
],
"type": "string",
"description": "\"km\" or \"mi\" — state the unit the guest used; do not convert it yourself."
},
"value": {
"type": "number",
"maximum": 100,
"exclusiveMinimum": 0
}
},
"description": "How far around `city` — or around `coordinates`, when you sent a point — to search, as a value and its unit: {\"value\": 10, \"unit\": \"mi\"}. Defaults to 20 km. May not exceed 100 km once converted; larger values are rejected, never quietly reduced."
},
"checkIn": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Arrival date, YYYY-MM-DD. REQUIRED — ask the guest for their dates before you search. Without them nothing can be priced and the answer would be a list of property names with no rooms, no prices and no results card. NEVER choose dates yourself, and do not read them out of a vague phrase: \"next month\" is not a date, it is a question to ask."
},
"country": {
"enum": [
"de",
"at",
"ch",
"us",
"gb"
],
"type": "string",
"description": "Filter by country: de=Germany, at=Austria, ch=Switzerland, us=United States, gb=United Kingdom"
},
"offerId": {
"type": "string",
"maxLength": 2000,
"minLength": 1,
"description": "An `offerId` from an earlier answer, to get a fresh price for THAT room rather than searching again. Pass it when the guest has already chosen and you need a current handle — after `hotel_reserve` said the offer expired, or before asking them to confirm. The answer comes back as that one property carrying that one room with its rate plans, each with a new `offerId`, so you never have to work out which of several rooms was theirs. An offer older than 30 minutes still works here — this call is what refreshes it. EVERY OTHER SEARCH FIELD IS IGNORED when you pass this: `city`, `coordinates`, `radius`, `query`, `country`, `starRating`, `style`, `limit` and `maxPricePerNight` describe a search, and this is not one. `language` still applies. The stay comes from the handle, so leave the dates out to re-price the same nights; pass `checkIn`, `checkOut` and `adults` together to ask for the same room on different nights. THIS IS THE ONE CALL THAT NEEDS NO DATES AND NO BUDGET: a plain search is refused without them, but a handle already carries the stay it was quoted for, and a budget here could filter out the very room the guest chose."
},
"checkOut": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Departure date, YYYY-MM-DD. REQUIRED, on the same terms as `checkIn` — ask the guest, never choose."
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3,
"description": "THE CURRENCY OF `maxPricePerNight`, AND THE ONE THE ANSWER IS QUOTED BACK IN. ISO 4217 — `EUR`, `CHF`, `GBP`. REQUIRED on every search: send `EUR` when the guest gave you a euro figure, which is most of the time. USE THE ONE THEY ALREADY NAMED and do not re-ask — \"200 euros\" is `EUR`, \"CHF 165\" is `CHF`. Ask them only when they gave a bare number and you genuinely cannot tell which currency they meant; guessing it is the thing this field exists to stop. IT ALSO CHOOSES THE CURRENCY THE ANSWER COMES BACK IN: every `price`, `stayTotal` and `pricePerNight` is in what you send here. It exists because a budget with no currency was read as euro, so a guest who said \"CHF 165\" was filtered at €165 and the hotels they could actually afford were not marked dear, they were absent. PASS THE GUEST’S OWN NUMBER and name its currency here; never convert it yourself. Quote them their own figure back; the prices you are handed are already in it. A currency we cannot get a rate for is REFUSED rather than assumed to be euro."
},
"language": {
"type": "string",
"maxLength": 64,
"description": "The language to render the results card in — pass the language the guest is WRITING in, unless they have asked for another. A bare language code or a full BCP 47 tag both work (\"de\", \"de-AT\", \"en-GB\"); only the language part is read, so a region suffix is harmless and case does not matter. German and English are rendered; any other value falls back to English rather than failing the search. Omit it and the card follows the guest’s own app language, then English. It changes ONLY the labels WE write on the card — never a room name or a rate plan, which stay in the property’s own words. A cancellation term carries the property’s own figures, but the sentence around them is written in English whatever language the card is in."
},
"amenities": {
"type": "array",
"items": {
"enum": [
"24h-reception",
"accessible-parking",
"adults-only",
"air-conditioning",
"airport-shuttle",
"allergy-free",
"bar",
"bbq",
"beachfront",
"breakfast",
"conference-facilities",
"cycling",
"elevator",
"ev-charging",
"family-rooms",
"games",
"garden",
"golf",
"gym",
"hammam",
"hiking",
"hot-tub",
"kids-facilities",
"laundry",
"massage",
"minimarket",
"parking",
"parking-free",
"parking-none",
"parking-paid",
"parking-private",
"pets-allowed",
"pool",
"restaurant",
"room-service",
"sauna",
"ski-school",
"ski-storage",
"skiing",
"solarium",
"soundproof",
"spa",
"tennis",
"terrace",
"water-park",
"wheelchair-accessible",
"wifi"
],
"type": "string"
},
"maxItems": 6,
"description": "Facilities and house rules the property must ALL have — a hotel missing one is excluded, so every extra value narrows the result. Prefer this to naming an amenity in `query`: these are exact, while `query` matches only the words we happen to store. Naming one in `query` in either language (\"swimming pool\", \"Schwimmbad\") also works and resolves to these same values."
},
"starRating": {
"enum": [
"1-star",
"2-star",
"3-star",
"4-star",
"5-star"
],
"type": "string",
"description": "Filter by star rating: 1-star, 2-star, 3-star, 4-star, 5-star. A property can hold stars AND be a boutique hotel; ask for the two separately."
},
"coordinates": {
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lon": {
"type": "number",
"maximum": 180,
"minimum": -180
}
},
"description": "A point to search around, for anywhere smaller than a town: a street, a landmark, a station, a junction, a named district. ESTIMATE IT YOURSELF for the place the guest named — `city` takes town names only, and a smaller name sent there is either refused or resolved to a different place of the same name, which comes back as a confident answer about somewhere else. Same shape as the `coordinates` on a hotel in the answer, so you can search around one you were just given. TAKES PRECEDENCE over `city` when both are sent: the point decides what is searched and which row leads, and `city` only names the place in the answer. Use `radius` to say how far around the point to look, and keep it small for a street or a venue. Tell the guest you estimated the point, so they can correct you."
},
"childrenAges": {
"type": "array",
"items": {
"anyOf": [
{
"type": "integer",
"maximum": 17,
"minimum": 0
},
{
"type": "null"
}
]
},
"maxItems": 10,
"description": "ONE ENTRY PER CHILD — their age, or `null` when you do not know it yet. Not a count: properties price a child by its age, and none may be invented. ASK WHETHER ANYONE UNDER 18 IS TRAVELLING, in the same message as `adults`. The moment the guest mentions a child, put it here: send `[null]` if you have not asked the age yet and the search is REFUSED until you replace it with the real age, which is what stops a family being quoted as a couple. A child you leave out altogether is priced as though they are not coming — the quote is for the adults alone, and the room the guest books may not sleep them, which they find out at the desk. Leave the field out when there are no children — an EMPTY ARRAY says the same thing and is read as none. An age of 0 is a real age — an infant is a child, not nobody."
},
"maxPricePerNight": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Budget per night, in the `currency` you send alongside it — BOTH ARE REQUIRED. TAKEN FROM A FIGURE THE GUEST GAVE YOU AND NOWHERE ELSE. Ask them roughly what they want to spend a night before you search: \"a budget hotel\", \"somewhere cheap\", \"nothing too pricey\" and a star rating are not amounts, and a figure you inferred hides every hotel they could have afforded behind a limit they never set. If they say they have no limit, ask for the most they would still pay and send that. PASS THE NUMBER THEY SAID AND NAME ITS CURRENCY — do not convert it yourself, and do not pass a euro figure you worked out from one they gave in francs or pounds. It FILTERS rather than labels. `priced` comes back holding ONLY the hotels at or under it, each carrying ONLY its rooms at or under it — so it can be shorter than `limit`, and it is not every hotel in the area. A kept room keeps all of its rate plans, including one dearer than the budget, so a breakfast rate is still there to offer. Dearer HOTELS are returned only when not one fits, in `aboveBudget`. Read the `hint`, which says how many were left out. Compares the stay average, not a nightly rate."
}
}
}