Retreats and Venues

Count how many published venues we have in a batch of places — countries, states and cities, mixed freely in one call. This is the ONLY way to know where inventory actually is; never answer an inventory question, pick a destination, or name an alternative from your own world knowledge. WHEN TO USE — four distinct jobs, not just the pre-search gate: 1. ANSWERING AN INVENTORY QUESTION DIRECTLY — "how many venues do you have in Portugal?", "do you cover Croatia?", "where in Spain do you have the most options?". Call with NO hard filters unless the user has stated constraints, answer from 'count', and use 'topCities' to name the leading places. Never run search-venues just to count its results. 2. CHOOSING BETWEEN CANDIDATE DESTINATIONS — the user is weighing two or more places, or named a continent / broad region ("the Mediterranean", "Southeast Asia") and has to narrow to specific countries. Batch every candidate into ONE call and let the numbers drive the recommendation. Multi-country batches are supported and expected here. 3. RECOVERING FROM THIN OR EMPTY RESULTS — a row came back 'thin', or search-venues returned nothing. Call again with neighbouring places, and use 'topCities' on the country or state row to name a concrete alternative that has inventory. NEVER suggest an alternative destination you have not counted. 4. GATING A SEARCH — before search-venues when you are passing 'cities', and any time you want to know a search is worth running. WORKFLOW 1. Decide every place worth weighing — the one the user named, plus any neighbour or fallback you might suggest. 2. Put them ALL in one call, at whichever granularity you have: 'city' for a city, 'state' for a whole state, neither for the whole country. 3. Pass the hard filters you plan to send to search-venues. 4. Read the rows: a healthy count means search; 'thin' means broaden or offer an alternative from 'topCities' first; 'unmatched' means retry the name, not that the place is empty. 5. Only then call search-venues. Do NOT call this tool again with the same locations and filters in the same turn. INPUTS: 'locations' is an array of up to 35 entries. Each entry REQUIRES 'countryCodeIso2'. Add 'city' to count one city, add 'state' to count a whole state, or give neither to count the whole country. Batch every place you are weighing into ONE call. INPUTS — CRITICAL: Pass the SAME hard filters you plan to pass to search-venues (minBedrooms, maxBedrooms, minMeetingSpaces, maxPrice, maxTimeToAirportMinutes). Filters apply to every location in the call. If you pass fewer filters here than to search-venues, counts will OVERSTATE reality and you'll mis-gate. Example failure: the user wants 40+ bedroom venues in southern Italy. You call this tool with just the cities and no filters — Naples, Bari and Palermo all come back healthy, so you search. search-venues with minBedrooms=40 returns 1 venue, and you have now told the user there was plenty of choice. Passing minBedrooms=40 to this tool would have flagged all three rows 'thin' and sent you straight to broadening. Do NOT pass amenities, environments or minPrice — these are soft signals in search-venues (ranking boosts, or in the case of minPrice a soft floor that auto-relaxes when results are thin), so they don't constrain the matching set and are not accepted here. RETURNS one row per requested location, in the order you sent them: - 'location' — what was counted, echoed back so you can attribute the row. - 'count' — venues matching that place plus your filters. - 'thin' — present when 'count' is below 5. Broaden before searching there. - 'unmatched' — present when the name matched no place we hold. This means the NAME failed, NOT that the place is empty. Never tell the user a real city has no venues on the strength of an 'unmatched' row: re-check the spelling or use the full official name, and if it still comes back 'unmatched' count the surrounding state or country instead. - 'topCities' — country and state rows only: the leading cities inside that place. Use these to name a concrete nearby alternative when the place the user asked about is thin. TELLING THE USER A NUMBER: counts are of publicly listed venues and are approximate. Always phrase them loosely — "around 200 venues across Portugal", "a bit over 30 in Lisbon" — and NEVER give an exact figure like "exactly 210". Other parts of the site compute country counts differently, so a precise number invites a contradiction.

Fetch available filter options for venue searches. Returns a list of valid values that can be passed to search-venues as amenities or environments filters. Call this before presenting filter options to the user via ask-user-questions (if available).

Fetch one help article's full content by its slug. Slugs come from the help-article index in your instructions; never invent, shorten, or assemble one. Call it more than once in parallel within the same turn when several entries in that index apply.

Resolve a place the user named into a specific city record. Returns an identifier, never a coordinate — search-venues accepts a city uuid as a search centre or as an exclusion and accepts nothing else, so this call is the only way a city search gets its centres. You cannot pass a latitude, a longitude, or a place name in its stead. WHEN TO CALL: the user named a city or town to search in — "venues in Split", "Lisbon or Porto" — with or without a distance, and including "within 100 km of Geneva" or "a couple of hours from Tokyo". Also when they want a place left out of such a search ("around Lisbon but not Cascais"). One call per place — every centre and every excluded city is its own lookup. Do NOT call this for towns YOU are naming to cover a region the user described; those go to search-venues as `cities` and need no uuid. INPUTS: 'name' is the place as the user said it. 'countryIso2' is REQUIRED and comes from the country you are already tracking, or the one the user just named — never guess it, and ask the user if you do not have one. 'stateIso31662' is optional and only worth sending when the user has already told you the state, or has just picked one from an ambiguous result. RETURNS one of three outcomes in 'outcome'. Branch on that field — never on the length of a list. - "resolved" — exactly one city, in 'city'. Use 'city.uuid', and TELL THE USER which place you are measuring from using 'city.label' ("measuring from Londonderry, Vermont"), so they can catch it if you resolved the wrong one. - "ambiguous" — several real cities, in 'candidates', at most 5. Ask ONE question that names them by their 'label', then call again with the 'stateIso31662' of the one the user picks, or use that candidate's uuid directly. Do NOT choose for them, do NOT take the first one, and do NOT reach for the largest — we hold no population data, so there is no largest. When 'truncated' is true there were more matches than shown ('totalMatches' says how many): say so and ask for the state. - "not_found" — the name is not a settlement we hold. This is NOT an error and NOT a reason to retry with a coordinate or a different spelling. We hold cities, towns and administrative areas, so valleys, coastlines, mountain ranges and informal areas ("the Cotswolds", "the Amalfi Coast") miss by design. Read 'guidance' and do what it says: fall back to the region-to-city-list procedure — name the cities of that region yourself and search them as 'cities'. Regions still work; they just do not work through a circle. NEVER invent a uuid, and never reuse one from an earlier turn for a different place. A uuid is only valid because this tool returned it.

Recommend destinations for a group retreat at one tier — countries, or cities — scored by budget, safety, visa-friendliness, accommodation cost, and optionally travel distance. Call this tool when the user wants help choosing where to go (not a specific venue). ALSO call it whenever the user asks about venues but has NOT named a specific country (e.g. "find me a venue", "a beachfront villa for 20 people", "somewhere warm for our team") — destination must be resolved before search-venues can run. Vibe, group size, budget, and climate hints alone are not destination signal. Tiers: omit tier (or pass "country") to rank countries. Pass tier="city" to rank cities, scoped by includeCountries exactly as the country tier is — no country needs to be settled first. Omit includeCountries to rank cities worldwide: do this when a signed-in user asks for a city outright ("help me pick a city", "which city should we go to?"). Pass several codes to rank the cities of those countries against each other, which is what a user asking for a city across the countries already on the table wants. Pass one code to rank that country's cities, when the user picks or asks about one of the recommended countries or asks where within it ("where in Portugal?", "which part of Mexico?") — that case skips the country ranking entirely. Carry forward the same tempRange, originGroups and travelMonth as the country call. Regions (states, provinces) are not ranked: when asked for a country's best regions, rank its cities instead and say so — never present cities as a region ranking. Signed-in only: the city tier runs as the signed-in user. For a guest it returns error="CITY_TIER_REQUIRES_SIGN_IN" and no cards — say in one warm sentence that ranking cities needs a signed-in account, offer to keep going with the country ranking, and never imply the cities exist but are hidden. Never offer a city ranking to a guest. Before calling: Use ask-user-questions to gather any missing inputs — climate preference (tempRange), origin countries (originGroups), and travel months (travelMonth). Only ask for what the user hasn't already provided. If the user gave specific countries, use those. If the user gave a vague regional answer (e.g. "Mostly Europe", "global", "Asia"), resolve it to 3–5 populous countries in that region with headcount=1 each — see the assistant prompt for preset mappings. Only OMIT originGroups when the user skipped the origin question entirely (no answer at all). Never error out or re-ask just because an answer was regional rather than country-specific. Origins: when the user named where people travel from more precisely than a country, pass it on the origin group: iataCode for an airport, or cityName (plus stateIso31662 only if the user gave the state) for a city, always with its originIso2. When the result carries downgradedOriginGroups, those groups were scored from a less precise place than named (see each group's precision and reasons). The ranking still stands, so present it, then ask one short question to pin those origins down: for CITY_AMBIGUOUS offer the cityCandidates labels and pass the pick back as cityName with its stateIso31662 (when cityCandidatesTotalMatches is present the list is capped: say so and ask for the state); for CITY_NOT_FOUND or AIRPORT_NOT_FOUND ask for a nearby city or airport. Skip the question when the user has said the precise origin does not matter. After presenting results: Briefly mention the user can adjust the priority weights using the "Adjust priorities" button below the results to refine recommendations. After a country list, offer a signed-in user to narrow to one country's best cities, or to rank the cities across the countries shown. If the user picks a destination, use search-venues to find venues there — a city goes in `cities` with its country in `countryCodesIso2`, a country goes in `countryCodesIso2` alone. Do NOT list place names — the UI renders destination cards automatically. Differentiation: visa access is national, so it is identical for every city of one country and cannot separate them — it only ever applies to a ranking scoped to a single country, never to a city ranking that spans several. When the response sets undifferentiated=true the list came back at the country tier instead of the one you asked for, because the chosen priorities cannot separate that one country's cities: say so plainly, present the country ranking it returned, and offer a change of priorities. If every destination carries the same recommendationScore, or the user's latest "Adjust priorities" message put essentially all the weight on visa access, do not present the list as a ranking. Country filtering: When the user wants to exclude or restrict countries/regions, you MUST call this tool again immediately with the updated filters — do NOT just acknowledge in text. Use the same tempRange, originGroups, and travelMonth as the previous call, plus the new country filters. To exclude (e.g. "no Asia", "not Australia", "I don't want to go to Europe"), resolve the geographic reference to ISO2 codes and pass as excludeCountries. To restrict (e.g. "only Europe", "just Southeast Asia"), resolve to ISO2 codes and pass as includeCountries. Be comprehensive — include all countries in the referenced region. Priority adjustments: Recommendation priority weights are owned by the user via the "Adjust priorities" radar chart in the UI — they are NOT a parameter of this tool. When the user message starts with "Adjust recommendation weights::", they have updated their priorities through the UI. Call this tool again, carrying forward the previous tier, tempRange, originGroups, travelMonth, excludeCountries, and includeCountries — the backend will apply the user's saved priorities automatically. After receiving re-weighted results, compare with the previous results: if the same places appear in the same order, note that the match percentages have shifted based on the new priorities. If different places appear or the order changed, highlight what's new or what moved up/down. If the user asks in plain text to change recommendation priorities (e.g. "make budget more important", "I care more about safety", "weight visa access higher"), do NOT call any tool to express that change. Briefly tell the user they can adjust priorities using the "Adjust priorities" button below the destination recommendations.

PREREQUISITE: countryCodesIso2 must contain at least one specific country, UNLESS you are searching by venueName. If the user has not named a country (or has only mentioned a continent/broad region like "Europe" or "Southeast Asia" without committing to specific countries), call recommend-destinations first to help them pick — never call this tool with no country, with a guessed country, or to "search broadly". Vibe, group size, budget, and climate hints alone are not destination signal. Calling with neither a country nor a venueName returns error: "COUNTRY_REQUIRED" with no results. Searching by name: set venueName when — and only when — the user names a specific property or a brand that appears in venue names ("do you have the Four Seasons?", "any Aman properties?"). Never fill it from a vibe, a property type, or a place: "beachfront" is environments, "Tulum" is cities, "boutique hotel" is neither. A name search may run with no country at all (worldwide) or be scoped by passing countryCodesIso2, matches loosely on partial names and brand fragments, and returns every match under the normal pagination rules. Skip count-venues for name searches. If a name search returns no venues, retry ONCE with just the distinctive part of the name, then tell the user we have nothing under that name and offer comparable venues instead — the name is never automatically broadened away, so an empty result is a real answer. ALWAYS call count-venues before this tool when using the cities parameter, and call it for multi-country searches too — one batched call covers every country and city in play. 1. Call count-venues with the same locations AND all filters you plan to pass here. 2. Call this tool only after coverage is acceptable. If a location came back thin, broaden or offer a counted alternative first. Search for retreat venues by parameters. Returns matching venues with details including links, photos, and pricing. If you have access to search-venues-map, prefer that tool instead — it provides the same results plus an interactive map. Multi-country searches: countryCodesIso2 accepts up to 5 ISO codes (e.g. ["PT","ES"]). When more than one country is provided, state and cities MUST be omitted — passing them returns error: "MULTI_COUNTRY_WITH_LOCALE" with no results. If the user mentions a specific city or state, narrow countryCodesIso2 to just that one country instead. count-venues accepts multi-country batches — use it to compare the countries before searching. Searching cities the user named: ANY city or town the user themselves named is a circle search, up to 3 of them — "venues in Split", "Lisbon or Porto", "within 100 km of Geneva", "a couple of hours from Tokyo". Call lookup-city once per place and pass the uuids it returns as radiusCentreCityUuids. Each circle returns venues that sit inside that city PLUS anything within radiusKm of its centre, so a city with thin inventory of its own still comes back with its surroundings. Leave radiusKm null unless the user stated a distance — it then defaults to 20 km. Kilometres is the only unit accepted — convert miles and drive times yourself, then reply to the user in the unit they used. Rules that differ from a city-list search: - Omit cities and state entirely. The circles scope the search on their own, so passing either alongside them searches the circles and ignores it; the response then names what was set aside in "radiusIgnoredCities" and "radiusIgnoredState", and you must say so ("I measured out from Faro rather than searching the Algarve town by town"). cities is for towns YOU name to cover a region the user described — it takes no radius. - radiusKm without radiusCentreCityUuids returns error: "RADIUS_INCOMPLETE" — there is no radius without a centre. A country-wide search, a region decomposed into cities, and a name search all pass null for both rather than a placeholder uuid or a token distance. - radiusCentreCityUuids come from lookup-city and nowhere else. A uuid that names no city we hold fails the whole call with error: "RADIUS_CENTRE_NOT_FOUND" and no results — look the place up and search again, or pass null for both radius parameters if no specific city is in play. - A circle search NEVER broadens, so "broadenedTo" is never returned. A thin result is the real answer: report the count honestly rather than searching again wider, and offer a larger radius only if the user wants one. - Out-of-range radii are clamped, not rejected. If the response carries "radiusClampedFromKm", the distance actually searched was the nearest accepted bound — do not repeat the requested figure back to the user as if we had used it. - The country filter is dropped inside the circles when the user STATED a distance, unless confineRadiusToCountry is true, because a border is not a distance. A defaulted radius keeps the country in force — a city the user named is a question about that country. Skip count-venues for circle searches — it has no radius concept, so its counts describe a smaller search and would talk you out of one worth running. - excludeCityUuids subtracts places from the circle, but only when the user actually asks to leave somewhere out. Each excluded place needs its own lookup-city call. A circle response describes the search it ran, so describe it from these fields and never re-derive them: - "radiusCentreLabels" are the places actually searched. Say them back in your reply ("measuring from Geneva, Switzerland") so the user can catch a wrong resolution before you list venues. - "radiusDefaulted" means the user named a city without a distance and the search covered its surroundings too. Say so in the same sentence that presents the venues — "these are in and around Split" — so nobody reads a venue 20 km out as being in town. - "radiusKm" is the distance actually searched. Quote this one, converted back to the user's own unit — not the figure you sent, which may have been clamped. - "radiusExcludedLabels" names the places left out. Say them, so an empty-looking area reads as a place the user asked to skip rather than as no inventory. - "radiusIgnoredCities" / "radiusIgnoredState" appear only when a city scope was passed alongside the circle and the circle won. Say which one ran, and offer the city list as the alternative if the user actually wanted it. - "radiusCountriesSpanned" lists the countries the venues in THIS response sit in, each with its name. When there is more than one, say so up front — a cross-border shortlist must never be a surprise at booking time. It describes the venues you were just given, so do not present it as the whole circle's spread when more pages remain. - Each venue carries "distanceKm" from the centre. Use it to place venues in the circle ("about 60 km out") instead of implying they are all equally close, and round it when you speak. The search automatically broadens ONLY on the first page if no results are found (e.g., dropping city/state filters). Check the "broadenedTo" field in the response — if present, inform the user the search was broadened AND do not paginate further (pagination is disabled for broadened results). Price floor relaxation: when minPrice is set and the initial result set is sparse, the search automatically supplements with venues priced below the floor. Check the "priceFloorRelaxedTo" field in the response — if present, you MUST tell the user the price floor was loosened so they understand why some results are below their stated minimum. Use language like "I had to loosen the price range — there weren't enough venues at $X+/night, so I included some priced below that". Values: "halved" means venues down to minPrice/2 were included; "removed" means the floor was dropped entirely (any price up to maxPrice). Pagination is disabled when this fires — do not paginate further. Exclusive use (full buyout): isFullBuyout caps the bedroom range so the results are properties the group could plausibly take over, instead of the 300-room resorts an open-ended group size returns. The response reports the range it actually searched. Read these three fields and state what they carry — never present a buyout shortlist as if every venue matched the group size exactly. - "buyoutBedroomRange" is the range searched, as { minBedrooms, maxBedrooms }. A null maxBedrooms means no upper limit was applied. Quote this range rather than the group size you sent. - "buyoutCeilingRaised": true means the group was small enough that the ceiling was lifted above their size to surface enough options, so the results include properties larger than they asked for. You MUST say so in one clause and give the figure — "I stretched the size range up to 25 bedrooms so there's more to choose from". Never imply every result is sized to the group. - "buyoutBedroomsRelaxedTo" appears only when the first range came back too thin and the search widened. Values, widest last: "conservative", "aggressive", "unbounded". - "conservative": say the range was widened and quote the new one. - "aggressive" or "unbounded": say the range was widened AND warn that the larger properties may not suit a buyout, because the group pays for every room whether or not they fill it. Like: "There wasn't much at that size in Croatia, so I widened the search — the bigger places here would mean paying for rooms you won't use." - After ANY relaxation, your closing sentence MUST offer a different DESTINATION or a different GROUP SIZE, and nothing else. This REPLACES the usual offer to narrow by budget or setting — narrowing a search that just had to widen finds nothing, so offering it wastes the turn. Never ask "shall I broaden the search?" — it has already broadened. - Pitch that offer at the scope the user named, one step out at most, so it reads as help with THEIR destination rather than a change of subject. A city ask gets other towns nearby ("Want me to look at a few towns around Split too?"); a region ask gets the rest of the country ("Want me to open this up to the rest of Croatia?"); only a country ask gets other countries ("Want me to try a couple of nearby countries where there's more at your size?"). Offering a new country to someone who asked about one city reads as though you ignored them. - Pagination is disabled whenever "buyoutBedroomsRelaxedTo" is set — do not call with page > 1. Exact matches versus widened ones: when a widening ran on top of a result set that was NOT empty, the response carries "resultGroups" splitting the venues in two. "original" holds the venues that matched what the user actually asked for; "broadened" holds only what the widening added, with no overlap. Each carries "venueUuids" and a "totalCount", and "broadened" also carries "reason" and "filterDelta" — the filters that moved. - Pass EVERY uuid in "resultGroups.original.venueUuids" to present-venues FIRST, then fill the remaining slots from "resultGroups.broadened.venueUuids". The exact matches are the answer to the question that was asked; they never lose a slot to a widened one. Keep the order the tool gave you. - Lead your reply with the exact matches and their count — "just the two at that size in Vietnam" — and only then say what you widened and why. NEVER present the widened set as the answer to the strict question, and never bury a one- or two-venue exact result inside a wider list without saying that is what it is. The user asked a specific question; a small honest answer to it is a real answer, not a failure to be padded. - The panel renders the two as separate sections with the widening labelled, so do NOT list or re-describe which venues fall in which group — say the counts and what moved, and let the cards do the rest. - "resultGroups" is absent when the search answered exactly what was asked, and when the original result set was empty. An empty original is NOT a group of zero: there is nothing to hold apart, so report it as an ordinary widened search using the disclosure fields above. - A venue we hold a buyout price for ranks higher, and the large-property bonus is withdrawn, so the order you receive already favours realistic buyouts. Do not re-sort or re-rank it yourself. Environments: Use environments to express soft preferences like "beachfront" or "mountain". Matching venues rank higher but all results are still returned. Call get-filters with filterType "environments" to see available options. Amenities: Same soft-preference behavior as environments — use them to express what the user is hoping for (e.g., "pool", "sauna"). Matching venues rank higher but venues missing some of the requested amenities are still returned. Call get-filters with filterType "amenities" to see available options. Results are sorted by best match (deterministic). Sorting by specific fields (price, rating, etc.) is not supported. Pagination: - The response includes `pagination: { page, totalPages, totalCount, hasNextPage }`. - If `hasNextPage` is true the response also includes a `searchToken`. - To fetch more results for the SAME search (user asks "more", "show more", "next", "other options"): call again with `page: previousPage + 1`, pass the `searchToken` from the previous response, and keep EVERY other filter IDENTICAL. - Any filter change (cheaper, different country, extra amenity, etc.) is a refinement — start over with `page: 1` and no `searchToken`. - If `broadenedTo` or `priceFloorRelaxedTo` is set, or `hasNextPage` is false, do not call with `page > 1`. - If the response contains `error: "PAGINATION_TOKEN_MISMATCH"`: retry once using the `expectedToken` from the error and the same filters. Do not mention the error to the user.

This is the preferred tool for venue searches — always use this over search-venues unless explicitly asked for a text-only response. Search for retreat venues and render an interactive map in a single call. Accepts the same search filters as search-venues and returns map-ready venue data with coordinates plus a shareable collection link. Multi-country searches: countryCodesIso2 accepts up to 5 ISO codes (e.g. ["PT","ES"]). When more than one country is provided, state and cities MUST be omitted — passing them returns error: "MULTI_COUNTRY_WITH_LOCALE" with no results. If the user mentions a specific city or state, narrow countryCodesIso2 to just that one country instead. count-venues accepts multi-country batches — use it to compare the countries before searching. The search automatically broadens if no results are found (e.g., dropping city/state filters). Check the "broadenedTo" field in the response — if present, inform the user the search was broadened. Bedroom mapping: When a user says "a venue for X people" or "X guests", treat that number as minBedrooms if the number of bedrooms is not explicitly provided.