ask_theatre_concierge
ChatGPTUse this when the user asks a free-text theatre question (best musical for kids, romantic show tonight, cheap comedy). Returns a concise grounded answer plus cited theatre products with booking URLs. Intent-aware (budget, audience, timeframe) via the concierge seam.
check_availability
ChatGPTUse this when the user has picked a specific experience and asks whether it is available on one date, what it costs for a party, or wants a booking link. This is the legacy-compatible date-specific availability interface.
compare_experiences
ChatGPTUse this when the user wants a side-by-side comparison of 2-5 specific products. Pass the slug for each. Returns a comparison table plus per-axis winners (value, rating, popularity, family-fit).
find_theatre_for_occasion
ChatGPTUse this when the user has an occasion: family outing, date night, group celebration, solo culture trip, business entertainment. Returns ranked theatre shows with fit scores and reasons, honouring party ages and an optional date.
get_availability
ChatGPTUse this when the user is ready to check live bookable dates, times, prices, or remaining spaces for one selected product. This is the live supplier-check tool; pass product_id from search or slug plus city_slug.
get_city_guide
ChatGPTUse this when the user wants an orientation overview of a city for trip planning. Returns highlights, dominant categories, price band, best-for audience hints, seasonal notes, and a short list of local advice items.
get_city_highlights
ChatGPTUse this when the user wants an orientation overview of a city for trip planning. Returns a ranked list of the city's most popular bookable experiences (search rows); derive the dominant categories and price levels from those rows rather than expecting a structured guide payload.
get_date_night
ChatGPTUse this when the user wants an evening plan for two. Returns a pre-dinner activity, dinner area suggestion, evening show, post-show tip, and an estimated total cost. Filters out family-rated and high-physical-level venues.
get_experience_details
ChatGPTUse this when the user selects a specific experience from search results and needs richer product, location, supplier, and booking fields. Accepts either product_id or slug.
get_family_day
ChatGPTUse this when the user wants a full-day plan for a family in one city. Returns a morning activity, lunch area suggestion, afternoon attraction, and optional evening stop. Uses age-aware filters and clusters venues by walking distance.
get_hidden_gems
ChatGPTUse this when the user wants less-popular experiences locals favour rather than top-of-list bestsellers. Returns rows tagged HiddenGem or with high ratings and lower review counts; explicitly excludes Bestseller, HopOnHopOff, and CityPass products.
get_itinerary_candidates
ChatGPTUse this when the user wants a multi-day plan for a single city. Returns a flat ranked candidate list of experiences (search rows), not structured day slots or a running cost. Arrange the candidates into days yourself and compute totals only from returned price fields.
get_last_minute
ChatGPTUse this when the user wants experiences starting within the next few hours. Returns rows with start_time, countdown_text, and seats_remaining hints, sorted by soonest first.
get_show_guide
ChatGPTUse this when the user asks about a specific show: how long it is, age guidance, venue and address, typical curtain times and dark days, who it is good for, and this week's performances. One rich guide record fusing live catalogue data with theatre expertise. Accepts slug or product_id.
get_theatre_weekend
ChatGPTUse this when the user asks what theatre is on this weekend or next. Server-side date math resolves the Friday/Saturday/Sunday dates; returns theatre shows in the city with scheduled performances on those days, grouped by day. Schedule data, not live seat inventory.
get_transfer_info
ChatGPTUse this when the user is arriving in a supported city and needs transfer guidance from an airport, station, or port to a hotel coordinate. Returns taxi, metro, bus, and train estimates with durations, costs, and directions.
get_travel_tips
ChatGPTUse this when the user asks practical logistics questions about a city. Returns short tips grouped by topic (transport, money, safety, culture, food, weather, language, connectivity), plus emergency numbers and quick phrases where relevant.
get_whats_on_this_week
ChatGPTUse this when the user wants a day-by-day weekly calendar for a city. Returns one entry per day for the next 7 days, each with morning, afternoon, and evening picks plus a daily highlight.
list_cities
ChatGPTUse this when the user wants to browse supported cities before searching. Returns city names, slugs, country codes, and product counts.
plan_itinerary
ChatGPTUse this when the user wants a multi-day plan for a single city. Returns morning, afternoon, and evening slots per day, with geographic clustering, category diversity, and a running total cost.
recommend_experiences
ChatGPTUse this when the user describes what they want in natural language rather than naming a category. Parses the query for audience, mood, constraints, occasion, and time of day, then returns scored recommendations with a reason field explaining the match.
render_experience_cards
ChatGPTUse this immediately after ANY discovery or search tool (search_experiences, whats_on_tonight, get_last_minute, get_whats_on_this_week, recommend_experiences, search_by_mood, get_hidden_gems, get_family_day, get_date_night, search_local_experiences) returns results — it is the only tool that displays the visual experience cards, so always call it once for every result set you want shown. Take the experience_ids those tools provide and render them; pass the stable product IDs (the t_ ids) only, never full product rows. Provide render_context.intent_summary describing what the user asked for (city, date, audience) — it becomes the carousel heading. Call it exactly once per result set, and do not also re-list the experiences as text.
search_by_mood
ChatGPTUse this when the user describes the feeling or vibe they want rather than a category, such as romantic, relaxing, adventurous, family fun, foodie, luxury, or rainy day. Maps the mood to preset search filters and returns matching experiences.
search_experiences
ChatGPTUse this when the user names a city plus a category, query, or filter set and wants a ranked list of bookable experiences. Returns products each with a stable product_id, plus name, slug, city, category, price, rating, review count, and tags. To show the results as visual cards, pass the product_id values from these results into render_experience_cards (experience_ids). Pair with get_experience_details for richer fields.
search_local_experiences
ChatGPTUse this when the user mentions a place, neighbourhood, landmark, or area but does not give exact coordinates. Examples: 'near the Louvre', 'in Trastevere', 'around Times Square', "walking distance from St Paul's Cathedral". Returns experiences matched first by exact venue/neighbourhood, then by city centre fallback. Do not use for general city-wide search; use search_experiences for that.
whats_on_tonight
ChatGPTUse this when the user asks what is bookable in a city tonight. Returns experiences with start times tonight, sorted by soonest first; events that have already started are filtered out. Each row includes start_time, countdown_text, venue, and a short urgency hint.
check_availability
ClaudeUse this when the user has picked a specific experience and asks about exactly one date: whether it is available that day, what it costs for a party, or a booking link for that date. For browsing a date range or listing upcoming times and live slot prices, use get_availability.
compare_experiences
ClaudeUse this when the user wants a side-by-side comparison of 2-5 specific products. Pass the slug for each. Returns a comparison table plus per-axis winners (value, rating, popularity, family-fit).
find_nearby_experiences
ClaudeUse this when the client already holds exact latitude and longitude coordinates and wants experiences near that point. When only a place name, landmark, or neighbourhood is known, use search_local_experiences, which accepts coarse place hints and needs no coordinates.
get_availability
ClaudeUse this when the user is ready to check live bookable dates, times, prices, or remaining spaces for one selected product. This is the live supplier-check tool; pass product_id from search or slug plus city_slug. Slot price.amount is in MINOR currency units (pence/cents): amount 13125 with currency_code GBP means GBP 131.25. Slot time is venue-local; when the venue timezone is known, timezone carries its IANA name and datetime/next_available carry the real UTC offset (e.g. 2026-07-18T19:30:00+02:00), so they are safe for time math.
get_city_guide
Claudeget_city_highlights
ClaudeUse this when the user wants an orientation overview of a city for trip planning. Returns a ranked list of the city's most popular bookable experiences (search rows); derive the dominant categories and price levels from those rows rather than expecting a structured guide payload.
get_date_night
ClaudeUse this when the user wants an evening for two. Returns a flat ranked list of experiences (search rows) with romantic-tagged rows promoted and out-of-season products dropped, not a structured pre-dinner/dinner/show arc. Promotion is a re-rank, not a filter, so rows are not guaranteed couples-only. date selects which season counts as current; budget is accepted but NOT yet applied. Compose the evening yourself (search_by_mood with mood 'romantic' can bias the pool further).
get_experience_details
ClaudeUse this when the user selects a specific experience from search results and needs richer product, location, supplier, and booking fields. Accepts either product_id or slug.
get_family_day
ClaudeUse this when the user wants family-suitable options for a day in one city. Returns a flat ranked list of experiences (search rows) with family-tagged rows promoted and out-of-season products dropped, not a structured morning/lunch/afternoon/evening plan. date selects which season counts as current; kids_ages and budget are accepted but NOT yet applied, so compose the day yourself and verify age suitability per pick via get_experience_details.
get_hidden_gems
ClaudeUse this when the user wants lower-profile options rather than headline bestsellers. Excludes Bestseller, hop-on-hop-off, and CityPass tagged products and prefers highly rated rows with fewer reviews; falls back to the standard ranked list when a city has too few qualifying rows (results may then overlap with headline search).
get_itinerary_candidates
ClaudeUse this when the user wants a multi-day plan for a single city. Returns a flat ranked candidate list of experiences (search rows), not structured day slots or a running cost. Arrange the candidates into days yourself and compute totals only from returned price fields.
get_last_minute
ClaudeUse this when the user wants something to do within the next few hours. Returns currently-on-sale experiences with seasonal products filtered out, ranked by popularity. Rows may include start_time, countdown_text, and seats_remaining hints when known, but none are guaranteed: confirm the selected experience with get_availability before stating it starts soon or is available today.
get_related_experiences
ClaudeUse this when a widget or client holds a selected product_id and needs related products to pair with it, do after it, find nearby, or find similar alternatives. Returns cached graph and semantic related products for trio-style widgets.
get_transfer_info
ClaudeUse this when the user is arriving in a supported city and needs transfer guidance from an airport, station, or port to a hotel coordinate. Returns taxi, metro, bus, and train estimates with durations, costs, and directions.
get_travel_tips
Claudeget_whats_on_this_week
ClaudeUse this when the user wants ideas for the coming week in a city. Returns a ranked list of currently on-sale experiences (search rows) with out-of-season products dropped, not a day-by-day calendar. Assemble any weekly structure yourself and verify specific dates with get_availability.
list_cities
ClaudeUse this when the user wants to browse supported cities before searching. Returns city names, slugs, country codes, and product counts.
plan_itinerary
Clauderecommend_experiences
ClaudeUse this when the user describes what they want in natural language rather than naming a category. Parses the query for audience, mood, constraints, occasion, and time of day, then returns scored recommendations with a reason field explaining the match.
render_experience_cards
ClaudeUse when visual cards would help present a discovery result from a supported search tool. Pass the product_id values from that result as experience_ids, never full product rows, and choose a render_type. Optionally pass render_context.intent_summary (a short phrase describing what the user asked for, such as city, date, or audience) to set the heading. Keep each result set to one card view to avoid duplicate cards; concise text context may accompany it.
report_quality_signal
ClaudeUse this to push a quality signal back to tickadoo about an experience or recommendation you previously surfaced. Examples: stale availability, a failed click-through, a supplier outage, or misleading content. Requires a real forward-event request_id returned within the last 30 days. Repeating the same signal for the same request is idempotent per caller.
search_by_mood
ClaudeUse this when the user describes the feeling or vibe they want rather than a category, such as romantic, relaxing, adventurous, family fun, foodie, luxury, or rainy day. Maps the mood to preset search filters and returns matching experiences.
search_experiences
ClaudeUse this when the user names a city plus a category, query, or filter set and wants a ranked list of bookable experiences. query matches on experience NAME (and venue), so it suits a title or keyword ("Lion King", "river cruise"); for mood or theme use search_by_mood, and for a free-text "what should I do" ask use recommend_experiences. When a query matches no name, results are the city top-picks flagged match_type "fallback_city_ranked" (reason_codes include "fallback_no_text_match") rather than a genuine match, so treat those as suggestions, not the thing asked for. Returns products each with a stable product_id, plus name, slug, city, category, price, rating, review count, and tags. To show the results as visual cards, pass the product_id values from these results into render_experience_cards (experience_ids). Pair with get_experience_details for richer fields.
search_experiences_by_topic
ClaudeUse this when the user asks for bookable experiences by keyword or topic in a city. Returns a ranked search of bookable experience rows. The topic argument is accepted but does no filtering, so every topic returns the same city ranking. The payload contains no tips text or logistics guidance.
search_local_experiences
ClaudeUse this when the user mentions a place, neighbourhood, landmark, or area but does not give exact coordinates. Examples: 'near the Louvre', 'in Trastevere', 'around Times Square', "walking distance from St Paul's Cathedral". Returns experiences matched first by exact venue/neighbourhood, then by city centre fallback. Do not use for general city-wide search; use search_experiences for that.
whats_on_tonight
ClaudeUse this when the user asks what is on in a city tonight. Returns evening-appropriate experiences currently on sale, with out-of-season products filtered out, evening-led options ranked first, and multi-day passes, travel cards and transport products ranked last. Top results carry start_time (venue-local) when the live supplier calendar confirms a performance in the evening window (late afternoon onward); a confirmed slot lifts a row, and timed rows sort soonest-first within one relevance band. Rows without start_time have no confirmed evening time. Confirm the selected experience with get_availability before stating it is bookable tonight.
