CheapOair

Apply filters, reset filters, or re-sort an existing search session. Use searchSessionId from a prior search_flights response. Do not use this for a brand-new route or date — call search_flights instead. To restore original results after filtering, pass reset=["all"]. To clear one filter dimension, pass reset=["airline"], ["stops"], ["price"], or ["time_of_day"]. Args: request: ApplyFiltersInput with search_session_id and optional filter, reset, sort_type, or query_text (short intent summary) fields. Returns: structuredContent with searchSessionId, flights, count, total_result, and has_more for the filtered or re-sorted set.

apply_filters

Filter or re-sort a cached hotel listing. Does not start a new search. Use this tool only for follow-up refinements on the same stay, after search_hotels has already returned a searchSessionId: a new sort, star rating, guest rating (Pleasant 6+, Good 7+, Very Good 8+, Wonderful 9+), popular filters (refundable; reserve now, pay later; breakfast included; member savings; most booked), property type, amenities, meal plan, refundable, or reserve-now-pay-later. Do NOT use this tool for filters the user asked for in their first message. Those belong on search_hotels (it caches the listing, then applies them). Requires the latest searchSessionId from the most recent search_hotels for the current stay. Older ids from prior searches are invalid after a new search_hotels — do not use them. Results are taken from the cached listing — the hotel search API is not called again. Do NOT use this tool when destination, dates / length of stay, travelers, or rooms change. Those require search_hotels (and suggest_hotel_location first if the destination changed). Selection type -------------- Multiselect (user can pick more than one; pass a list, or combine booleans): - popular_filters: refundable, reserve_now_pay_later, breakfast_included, member_savings, most_booked. Example ["refundable", "most_booked"] - star_ratings: 1–5. Example [4, 5] - property_types - amenities: casino, wifi, parking, ev_charging, gym, pets_allowed, swimming_pool, bar, restaurant, airport_shuttle. Example ["wifi", "parking"] - meal_plans: breakfast, lunch, dinner (Breakfast / Lunch / Dinner included) - refundable and reserve_now_pay_later: independent checkboxes; both may be true One select (exactly one value): - guest_rating: pleasant (Pleasant 6+), good (Good 7+), very_good (Very Good 8+), wonderful (Wonderful 9+). Minimum guest score; omit for Any. - sort_type: recommended, price_low, price_high, guest_rating, star_rating To restore the original unfiltered listing, pass reset=["all"]. To clear one filter, pass reset=["star_ratings"], ["guest_rating"], ["meal_plans"], ["property_types"], ["amenities"], ["refundable"], ["reserve_now_pay_later"], ["popular_filters"], ["most_booked"], or ["member_savings"]. You can combine reset with new filter values.

filter_hotels

Creates a new flight search and returns flights matching the user's search criteria. Use this tool whenever the user starts a new flight search or changes the route, travel dates, passengers, cabin class, or search filters. Before invoking this tool, ensure enough information is available to satisfy the user's request. If required information is missing, ask a clarification question instead of calling the tool. This tool performs the complete search workflow internally and returns the final flight results. If the user specifies filters (such as airline, non-stop, maximum price, departure time, arrival time, etc.) in the initial request, those filters are applied automatically before the results are returned. Do NOT call the apply_filters tool immediately after this tool if all requested filters were already provided as part of the search request. For follow-up requests that modify an existing search (for example: "show only United", "non-stop only", "under $300", or "morning departures"), use the apply_filters tool with the searchSessionId returned by this tool. Passenger Rules --------------- Children: if the user does not mention a child's age, default to 11. Pass all child ages in children_age_list (integers 2–11, one per child). Infants: whenever the user mentions an infant or a traveler under 2 years old, use infants_in_seat_count (InfantOnSeat). Only use infants_in_lap_count when the user explicitly asks for a lap infant. Location Resolution ------------------- The origin and destination arguments MUST always be valid IATA AIRPORT codes. If the user specifies a city, metropolitan area, region, or other location instead of an airport, resolve it to the most prominent commercial airport serving that location before calling this tool. Examples: - New York → JFK - London → LHR - Paris → CDG - Delhi → DEL - Mumbai → BOM - Srinagar → SXR - Bengaluru → BLR - Hyderabad → HYD - Chennai → MAA - Dubai → DXB - Tokyo → HND - San Francisco → SFO - Los Angeles → LAX - Las Vegas → LAS Never pass city names such as "Delhi", "London", or "New York" to this tool. Only airport IATA codes are valid inputs. If a city is served by multiple airports, choose the primary international or most commonly used commercial airport unless the user explicitly specifies a different airport. If the user explicitly names an airport (for example "Heathrow", "Gatwick", "JFK", "Narita"), use that airport instead. Only ask the user for clarification when there is no reasonable default airport or when the user explicitly indicates they are flexible among multiple airports. Travel Date Rules ----------------- The departure_date is optional. If the user does not specify any departure date, omit departure_date from the tool call. The tool will automatically use a departure date of 7 days from the current date. If the user specifies a departure date explicitly or using a relative date expression (for example "today", "tomorrow", "next week", "next month", "this Friday", "next Monday", "in two weeks", or "25 December"), resolve it to a specific future date (YYYY-MM-DD) and include departure_date in the tool call. If the user explicitly requests a round-trip flight, a return_date is required. Do not invoke this tool until a valid return_date is available. Do not assume or invent a return_date. Search Constraints (do not call this tool until fixed) ------------------------------------------------------ • Trip types supported: one-way and round-trip only. Do not call this tool for multi-city, open-jaw, or multi-destination itineraries. If the user asks for those, explain that only one-way and round-trip are supported and offer to search one leg at a time. • Origin and destination must be different IATA airports. If they are the same, ask the user to clarify the route instead of calling this tool. • departure_date must be today or a future date (YYYY-MM-DD). If the user gives a past date, ask for a valid future date instead of calling this tool. • If the user explicitly requests a round-trip flight but does not provide a return_date, ask the user for the return date instead of calling this tool. • return_date, when provided, cannot be earlier than departure_date (same-day return is allowed). If it is earlier, ask the user for a valid return date instead of calling this tool. • Total passengers (adults + seniors + children + infants) cannot exceed 9. If the user requests more than 9 passengers, explain the limit and ask them to reduce the party size before calling this tool. Args: request: SearchFlightsInput with origin, destination, traveler counts, optional departure_date, optional return_date, optional filters, sort_type, limit, optional search_session_id, and optional query_text (short intent summary — not the full user message). Returns: structuredContent with searchSessionId, flights, count, total_result, has_more, and page_index. Use searchSessionId for follow-up tools.

search_flights

Create a new hotel search and cache the listing. Dates and occupancy must already be valid before any hotel tool is called (including suggest_hotel_location). Call suggest_hotel_location only after that check passes. This tool requires dest_id (and dest_type) from that tool. It does not look up locations. Use this tool to start a new hotel search, or when the user changes destination (after a new suggest_hotel_location), check-in/check-out dates (or number of nights), travelers, or rooms. Do NOT use this tool to change sort or filters on an existing listing. For those follow-ups, use filter_hotels with the searchSessionId from this tool (the current id — it replaces any prior searchSessionId from earlier searches). Occupancy and dates ------------------- Default occupancy is 1 room with 2 adults when the user does not specify guests. Tell the user when that default was used. Children are ages 0–16; ages 17+ count as adults. If a child age is unknown, use 11. Per room limits (do not call this tool with an over-limit room — ask the user to add another room instead): - At least 1 adult. Children cannot stay without an adult. - At most 6 adults and at most 6 children. - At most 9 guests total (adults + children). Check-in must be today or a future date. Do not search past dates (a stay that starts yesterday is invalid even if check-out is in the future). Check-in/check-out default to today and a 2-night stay when omitted. Filters and sort on a fresh search ---------------------------------- If the first request already includes filters or sort, pass them here. This tool searches first, caches the full listing, then applies those filters and sort in memory before returning results. They are not sent to the hotel API. Supported filters: star_ratings (1–5), guest_rating (pleasant 6+, good 7+, very_good 8+, wonderful 9+ — one select), popular_filters (multiselect: refundable, reserve_now_pay_later, breakfast_included, member_savings, most_booked), property_types, refundable, reserve_now_pay_later, meal_plans (breakfast / lunch / dinner included), amenities (casino, wifi, parking, ev_charging, gym, pets_allowed, swimming_pool, bar, restaurant, airport_shuttle). Sort with sort_type: recommended, price_low, price_high, guest_rating, star_rating. Later filter or sort changes on the same stay must go through filter_hotels. After results ------------- When hotels are returned and the user did not already apply filters, ask once if they want to narrow the list. Mention only supported filters, briefly: star rating (e.g. 3-star or 4-star), guest rating (Pleasant 6+, Good 7+, Very Good 8+, Wonderful 9+), popular filters (refundable; reserve now, pay later; breakfast included; member savings; most booked), property type (e.g. hotel, guest house), meal plan (breakfast, lunch, dinner), amenities (wifi, parking, gym). Do not oversell or invent other filters. Use filter_hotels if they choose one. When presenting hotels, label distance from structuredContent.distance_from: "airport" → "Distance from airport"; "city_center" → "Distance from city center". Do not guess or mix those labels.

search_hotels

Resolve a hotel destination name to a CheapOair dest_id. Call this only after hotel dates and occupancy from this prompt are valid (see Hotel search constraints on the server instructions). Do not call this tool if check-in is in the past or a room exceeds occupancy limits — ask the user to correct those first. Then call this before search_hotels. It does not search hotels. Do not assume every destination is a city. Classify intent from the full user query, then pass destination (the place/property name, not the whole chat) and preferred_type: 1. City — a city or metro: "London", "New York", "Paris", "hotels in London". 2. Hotel — only a named property: "Hyatt House London Stratford", "India Gate Hotel", "Disneyland Hotel", "search India Gate Hotel near me". 3. PointOfInterest — landmark, monument, attraction, museum, tourist site, or famous place: "Statue of Liberty", "Eiffel Tower", "Times Square", "India Gate", "hotels near Statue of Liberty". Pass the place name. Do not add the word "hotel". Do not substitute the nearest city yet. 4. Airport — include the word "airport" when they said it. A metro IATA (LAS, LAX) resolves to All Airports unless they said "airport"; then it is that specific airport. An airport-only IATA (JFK) is the airport. preferred_type is a soft preference: AutoSuggest still searches by name. Rows whose type matches are preferred; if none exist, other types are used. Never invent a dest_id. This tool then resolves: - IATA codes as above - Airport wording among airports plus All Airports - A named hotel / preferred_type=Hotel among Type=Hotel matches - preferred_type=PointOfInterest among landmarks / PointOfInterest - Anything else among cities and landmarks. Matching hotel rows are collapsed to their city dest_id (e.g. India Gate-named hotels in New Delhi → New Delhi). Hotel names are never returned as location choices unless the user named a hotel. If one candidate matches, this tool returns dest_id, dest_type, and resolved_location. Then call search_hotels with those values plus dates, rooms, and any filters or sort the user asked for. If needs_location_choice is true, several relevant locations matched: - ASK the user which one they meant and offer exactly those candidates. - Same name in different places (Las Vegas Nevada vs New Mexico) is a real question — ask it, do not guess. Offer cities/landmarks, not hotel names, unless the user named a hotel. - "All Airports" is the whole metro; a specific airport is that one airport. When both appear, give the user both. - After the user answers, call search_hotels with that dest_id, dest_type, destination text, dates, rooms, and any filters or sort. Never invent a dest_id. If no matches are returned, you may call suggest_hotel_location ONE more time with adjusted wording — e.g. drop a street address down to just the city, fix an obvious typo, or for a famous landmark pass the well-known city ("India Gate" → "New Delhi") and preferred_type="City". Do not add the word "hotel" on retry unless the user named a hotel. Do this at most once per user turn. If it still returns no candidates, tell the user you couldn't find that destination and ask them to specify the nearest large city or town, the state/country (if the name could exist in more than one place), or an airport code if they know one. Never invent or guess a dest_id.

suggest_hotel_location