Tool description (what the LLM sees)
Tool description (what the LLM sees)
Search flights between a known origin and destination using cached pricing, especially for flexible dates.
WHEN TO USE THIS TOOL (CRITICAL):
- The user provides both an origin AND a destination (city or airport)
- Examples: "Paris to Barcelona", "JFK to CDG", "London to NYC for a weekend"
- Supports loose / flexible dates: single dates, date arrays, date ranges, stay_days
- ALSO the right tool for "cheapest flight", "best flight", "find me a flight", "cheapest date" phrasings, returns the cheapest cached itineraries.
WHEN TO USE find_destination INSTEAD:
- The user does NOT specify a destination: "Where should I go from Paris?", "Best deals from NYC"
- The user wants inspiration: "Beach destinations from London", "Cheap flights from SF"
WHEN TO USE find_dates INSTEAD:
- The user wants a short shortlist of the best date options rather than the full per-date list: one cheapest itinerary per (departure, return) date-pair, spread across the departure window. Same inputs as this tool except offset (find_dates does not paginate; limit scales the shortlist).
WHEN TO USE flight_search INSTEAD:
- The user wants live pricing on one specific route with an exact departure date. For a round trip, also require an exact return date; one-way trips need no return date.
- Examples: "Paris → NYC one-way on June 17", "Paris → NYC, June 17 → June 26"
- flight_search hits live pricing (each call has a cost) and is the step immediately before booking. Use once the route and required travel dates are locked.
IMPORTANT:
All dates in query parameters (departure_dates, departure_date_ranges, return_dates, return_date_ranges) MUST be in the future. Never use past dates.
Use departure_dates for specific days or departure_date_ranges for a window. There is no departure_date parameter.
Origin and destination: send the city code when the user named a city (Paris → PAR, New York → NYC) and the airport code when they named an airport (JFK, CDG). A code that names a multi-airport city covers every airport of that city; any other code is that one airport. LAX, MIA and LAS are both a city code and that city's main airport, so they are read as the city here, this tool has no type field; flight_search has origin_type / destination_type to pin one airport.
ROUTE SEARCH:
- Use exact 3-letter IATA airport codes or IATA city code for both origin and destination
- Date ranges OR stay duration for flexible trip planning
- Natural trip duration (stay_days) instead of exact return dates
- By default, please search roundtrip flights unless user specifies one-way. Use trip_type="oneway" ONLY when the user explicitly asks for a one-way trip
USE CASES:
✓ "Find flights from JFK to CDG next month" - Specific route with date range
✓ "Fly from Los Angeles to Tokyo for a week in December" - Uses departure_date_ranges + stay_days
✓ "Paris to Barcelona for a weekend in April" - Specific route
✓ "Cheapest flight from ORD to LHR under $600" - Specific route with budget
✓ "Direct flight in business class from New York to London" - Specific route with preferences
Flow: flight_calendar → flight_search (price-check) → trip → checkout
The result carries `search_criteria` (what was actually searched) and `next` (the call to make next, on an empty answer up to three exact-date `flight_search` searches, on a non-empty one `price_check` for the best candidates). Follow `next` before telling the user there are no flights or quoting a cached price.
Every price this tool returns is one adult's cached fare (search_criteria.priced_for: "one_adult"); the tool takes no party. To price the whole party, price-check the offer using flight_search with price_check and the travellers' counts in traveler_counts.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
origin | string | Yes | Origin airport IATA code or city code (3 letters). Examples: “JFK”, “PAR”. A code that names a multi-airport city (NYC, LON, PAR, and LAX, MIA, LAS, which a city shares with its main airport) covers every airport of that city; any other code is that one airport. |
destination | string | Yes | Destination airport IATA code or city code (3 letters). Examples: “CDG”, “NRT”. A code that names a multi-airport city (NYC, LON, PAR, and LAX, MIA, LAS, which a city shares with its main airport) covers every airport of that city; any other code is that one airport. |
trip_type | enum ("oneway" | "roundtrip") | Yes | Trip type: “oneway” or “roundtrip”. |
departure_dates | array<string> | No | Specific departure dates (YYYY-MM-DD). Multiple dates searched with OR logic. |
departure_date_ranges | array<object> | No | Departure date ranges for flexible search. |
departure_date_ranges[].start | string | Yes | Range start date (YYYY-MM-DD) |
departure_date_ranges[].end | string | Yes | Range end date (YYYY-MM-DD) |
return_dates | array<unknown> | null | No | Specific return dates (YYYY-MM-DD) for round-trip flights. |
return_date_ranges | array<object> | null | No | Return date ranges for flexible round-trip search. |
stay_days | integer | null | No | Exact stay duration in days for round trips. Auto-calculates return date. Omit when trip_type is “oneway”. |
stay_days_range | object | null | No | Flexible stay duration range for round trips. Example: {min: 5, max: 10}. Omit when trip_type is “oneway”. |
direct_only | boolean | No | Only return nonstop flights. |
cabin_class | enum ("economy" | "premium_economy" | "business" | "first") | null | No | Cabin class filter. |
departure_time_range | object | No | Filter the OUTBOUND leg by local departure time-of-day. Example: { “earliest”: “08:00”, “latest”: “12:00” }. |
departure_time_range.earliest | string | No | Inclusive earliest local time-of-day (HH:MM, 24-hour). |
departure_time_range.latest | string | No | Inclusive latest local time-of-day (HH:MM, 24-hour). |
arrival_time_range | object | No | Filter the OUTBOUND leg by local arrival time-of-day. Example: { “latest”: “20:00” }. |
arrival_time_range.earliest | string | No | Inclusive earliest local time-of-day (HH:MM, 24-hour). |
arrival_time_range.latest | string | No | Inclusive latest local time-of-day (HH:MM, 24-hour). |
return_departure_time_range | object | null | No | Round-trip only. Filter the RETURN leg by local departure time-of-day. |
return_arrival_time_range | object | null | No | Round-trip only. Filter the RETURN leg by local arrival time-of-day. |
max_total | number | null | No | Maximum total of the cached fare, in the requested currency. Cached fares are priced for one adult, so the cap applies to a one-adult fare. For a whole-party budget, divide it by the number of ADULTS only and treat the result as a loose pre-filter: children and lap infants usually cost less than an adult, so dividing by every traveller would exclude affordable trips. Send a per-person budget as-is. The exact whole-trip budget check is flight_search with max_total. |
sort_by | enum ("lowest") | No | Sort order. “lowest” (cheapest first) is the only order today; omit it for the same. |
currency | string | No | ISO 4217 currency code. Defaults to “USD”. |
locale | string | No | BCP 47 locale. Defaults to “en-US”. |
format | enum ("text" | "json") | No | Compatibility option: “text” and “json” both return JSON in the text channel for successful or empty results. Read structuredContent for the result data. |
limit | integer | No | Max results to return per page (1-100). Default 20. |
offset | integer | No | Number of results to skip, for pagination. Default 0. |
user_intent | string | No | The end user’s current request in their own words, e.g. “help me with my travel plans”. Pass it as-is when short; otherwise condense the goal and constraints into 1-2 sentences. Strip personal identifiers (names, emails, phone numbers, addresses, payment details), replace them with placeholders like “[name]”. Optional. Jinko uses it to understand demand, and hotel_search uses it to rank hotel results against what the user asked for (e.g. “quiet, with a gym, near Times Square”), so keep the user’s stated preferences in it. |
Examples
Cheapest days to fly JFK→CDG in June:{
"name": "flight_calendar",
"arguments": {
"origin": "JFK",
"destination": "CDG",
"trip_type": "roundtrip",
"departure_date_ranges": [{ "start": "2027-06-01", "end": "2027-06-30" }],
"stay_days": 7,
"currency": "USD"
}
}
{
"name": "flight_calendar",
"arguments": {
"origin": "CDG",
"destination": "NRT",
"trip_type": "oneway",
"departure_date_ranges": [{ "start": "2027-09-01", "end": "2027-09-30" }],
"cabin_class": "business",
"direct_only": true,
"currency": "EUR"
}
}
structuredContent.flights and pass the selected entry’s id to flight_search as price_check.offer_token for live pricing before booking. The calendar’s next.args also provides ready-to-use price-check arguments.