find_destination
find_destinationFull Description
Discover the best travel destinations by finding the best flight deals from your origin location.
USE THIS TOOL WHEN :
- The user does not know where to go
- The user is looking for destination ideas based on specific criteria (for example: beach, family-friendly, kitesurfing)
- The user previously asked for destination recommendations and is now asking about pricing for those options
PURPOSE: Help users discover where to travel when they don't know where to go. Focus on finding great destinations based on flight prices and availability rather than searching for flights to known destinations. This tool leverage ChatGPT intelligence to identify relevant destinations for the user based on various criteria and passing it to the tool via the destinations field.
IMPORTANT
- DATES
All dates in query parameters (departure_dates, departure_date_ranges, return_dates, return_date_ranges) MUST be in the future. Never use past dates. Please fill as much as possible search parameters based on user intent to get best results. All departure dates MUST be for a future dates, never a past dates.
IMPORTANT
- RE-CALL THIS TOOL when the user:
- Asks for a different destination [city, region, country]
- Asks for different dates
- Asks for destination with specific criteria such beach, city trip, chill etc.
- The user is already in fullscreen mode in the widget.
CORE FUNCTIONALITY:
- REQUIRED: User's origin location (LLM identifies ALL nearby airports)
- OPTIONAL: Destination filtering by specific airports/cities OR omit for global discovery mode
- Destination Discovery Mode: When destinations is omitted/empty, searches ALL destinations globally
- Flexible dates and stay durations for exploring options
- Filter by budget, direct flights preference, currency, and locale
- By default, please search roundtrip flights unless user specifies one-way. Use "one-way" in the tool ONLY when the user type explicitely one way in the query
AIRPORT IDENTIFICATION
- CRITICAL:
LLM MUST identify and recommend ALL relevant airports for user's origin location:
- "New York": ["JFK", "LGA", "EWR"] (3 major airports)
- "London": ["LHR", "LGW", "STN", "LTN", "LCY"] (5 airports)
- "Paris": ["CDG", "ORY"]
- "Tokyo": ["NRT", "HND"]
- "Chicago": ["ORD", "MDW"]
- "Los Angeles": ["LAX"]
- "San Francisco": ["SFO"]
- "SFO": ["SFO"]
If user ask for SFO, SF or San Francisco, which means the city, please only use SFO airport code.
DESTINATION FILTERING
- INTELLIGENT INTERPRETATION:
Destinations can be specified using IATA airport codes OR city codes (3 letters). You can mix both types:
- Airport codes: ["JFK", "LAX", "LHR"] - searches specific airports
- City codes: ["NYC", "LON", "PAR"] - searches all airports in those cities
- Mixed: ["JFK", "LON", "TYO"]
- JFK airport + all London airports + all Tokyo airports
DESTINATION LIST
- CRITICAL:
When users mention criteria that imply a type of destination, the LLM MUST first interpret that intent and generate the appropriate list of destinations before making the tool call:
Examples:
- "Sunny places in winter": LLM identifies warm-weather destinations: ["MIA","MCO","SAN","PHX","HNL","CUN","PUJ","PTY","LIM","GIG"]
- "Somewhere in Asia": LLM compiles major Asian destinations: ["NRT","HND","ICN","PVG","PEK","HKG","SIN","BKK","KUL","MNL"]
- "Beach destinations": LLM identifies beach cities: ["MIA","SAN","HNL","CUN","PUJ","SJU","NAS","MBJ"]
- "European capitals": LLM lists capital airports: ["LHR","CDG","FRA","MAD","FCO","AMS","BRU","VIE","PRG","CPH"]
- "Ski destinations": LLM identifies ski resort airports: ["DEN","SLC","ZRH","INN","GVA","TRN"]
If no destination filtering is specified or criteria is too broad ("anywhere", "surprise me"), leave destinations empty for global discovery mode.
TYPICAL USE CASES FOR THIS TOOL: 1. "Where should I travel from NYC next month?" : origins: ["JFK","LGA","EWR"], departure_date_ranges, destinations: [] (global discovery)
2. "Find me cheap flights from SF to Europe under $800" : origins: ["SFO"], destinations: [European airports/cities], max_price: 800
3. "I want to go somewhere warm from Chicago for a week in December" : origins: ["ORD","MDW"], stay_days: 7, departure_date_ranges, destinations: [warm destinations]
4. "Best weekend getaways from Boston?" : origins: ["BOS"], stay_days_range: {min: 2, max: 4}, destinations: [] (discover mode)
5. "Direct flights from LA to Asia" : origins: ["LAX","BUR","SNA","ONT"], destinations: [Asian airports/cities], direct_only: true
6. "Beach vacation from Seattle in summer under $600" : origins: ["SEA"], destinations: [beach destinations], max_price: 600
7. "Flights to London from New York" : origins: ["JFK","LGA","EWR"], destinations: ["LON"] (city code for all London airports)
WHEN TO NOT USE THIS TOOL
- Never use this tool when the user asks the price for a single destination. A destination is defined as a city.
Examples : 1. ""What are the cheapest date to go NYC from PAR"?" : origins: ["CDG","ORY"], departure_date_ranges, destinations: ["JFK", "LGA", "EWR"]
2. ""Give me the chepaest flight from Los Anegles to Miami in June"?" : origins: ["LAX"], departure_date_ranges, destinations: ["MIA"]
IMPORTANT: Always provide ALL airports for both origins and (when applicable) destinations to maximize search results and find the best deals.
Parameters (2 required, 14 optional)
originsarrayREQUIRED. Array of origin IATA codes (3-letter uppercase), representing either airports or cities where the trip starts. The LLM MUST detect and include all relevant nearby airports or city codes based on the user’s location. Examples: ["JFK", "LGA", "EWR"] for New York City; ["SFO", "OAK", "SJC"] for the San Francisco Bay Area; ["ORD", "MDW"] for Chicago; or a single city code like ["NYC"].
trip_typestringREQUIRED. Type of trip: "oneway" for single-leg flights, or "roundtrip" for return flights.
onewayroundtripcabin_classstringPreferred cabin class. Options: "economy", "premium_economy", "business", or "first". Filters results accordingly.
economypremium_economybusinessfirstcurrencystringISO 4217 currency code (e.g., USD, EUR, GBP, JPY, CAD, AUD). Defaults to USD. Should align with the user’s location or preference.
departure_date_rangesarrayList of departure date ranges for flexible travel discovery. Use when the user mentions periods like “next month” or “spring.” Supports multiple non-contiguous ranges (OR logic). Example: [{start: "2025-12-10", end: "2025-12-15"}, {start: "2025-12-20", end: "2025-12-25"}].
departure_datesarrayList of specific departure dates in ISO 8601 format (YYYY-MM-DD). Use for searching multiple specific dates with OR logic. Example: ["2025-12-15", "2025-12-16", "2025-12-17"] for flexible date searches. Useful when user wants to check specific dates like weekends.
destinationsarrayOPTIONAL. Array of destination IATA codes (3-letter uppercase), representing either airports or cities. When a city code is provided, the LLM MUST expand it to include all associated airports. Examples: ["LHR", "LGW", "STN", "LTN", "LCY"] for London airports; ["CDG", "ORY"] for Paris; ["TYO"] for all Tokyo airports. You may mix airport and city codes: ["JFK", "LAX", "LON", "PAR"]. When omitted or empty, the system searches globally to discover the best flight deals (destination discovery mode).
direct_onlybooleanWhen true, only returns nonstop (direct) flights. Useful for avoiding layovers or minimizing total travel time.
localestringLocale code for formatting and language (e.g., "en-US", "es-ES", "fr-FR", "de-DE", "ja-JP"). Defaults to "en-US". Affects date, number, and language presentation.
max_pricenumberMaximum total price per passenger in the selected currency. Filters out results exceeding the limit. Example: 500 = limit of $500/€500/£500 per person.
return_date_rangesarrayList of return date ranges for flexible round-trip searches. Supports multiple return windows. Example: [{start: "2025-12-22", end: "2025-12-25"}, {start: "2025-12-29", end: "2026-01-02"}].
return_datesarrayList of specific return dates for round-trip searches (YYYY-MM-DD). Must be after the corresponding departure dates. Supports multiple options (OR logic). Example: ["2025-12-22", "2025-12-23", "2025-12-24"].
sort_bystringSorting preference for search results. Options: "lowest" (cheapest first, default) or "recommendation" (best overall balance of price, duration, and stops).
lowestrecommendationstay_daysintegerExact number of days to stay at the destination. Used with a departure date to automatically compute the return date. Example: 7 = one-week trip; 3 = weekend getaway.
stay_days_rangeobjectRange of acceptable trip durations for flexible planning (e.g., “5 to 10 days”). Cannot be combined with stay_days or explicit return_date. Example: {min: 5, max: 10}.
user_querystringThe original natural-language user query that triggered this tool call. Used for context.