limit adjusts), so the user gets a diverse shortlist rather than a cluster of near-adjacent cheapest days. Cache-backed; no live pricing. Each result includes an offer token; run a flight_search price check on it to get a bookable fare before adding the flight to a trip.
Tool description (what the LLM sees)
Tool description (what the LLM sees)
Find the best date options for a known origin and destination using cached pricing. Takes the same inputs as flight_calendar except offset, but returns one cheapest itinerary per (departure, return) date-pair, spread across the requested departure window (20 date-pairs by default; `limit` adjusts), so the user sees a diverse set of "when should I fly?" options rather than the full per-date list.
WHEN TO USE THIS TOOL:
- The user knows the route (origin AND destination) and is flexible on WHEN, and wants a short, spread-out shortlist of the best date options.
- Examples: "When is the cheapest time to fly Paris → New York in June?", "Best weekends to go from London to Lisbon next month", "Give me a few good date options for a week in Tokyo".
WHEN TO USE flight_calendar INSTEAD:
- The user wants the full price-per-date list / calendar grid for a route, not a curated 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 MUST be in the future. Never use past dates.
Origin and destination: the city code when the user named a city (PAR, NYC), the airport code when they named an airport (CDG, JFK). 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.
By default search roundtrip unless the user explicitly asks for one-way (trip_type="oneway").
Flow: find_dates → flight_search (price-check the chosen dates) → 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.
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" | "recommendation") | No | Sort order. Default: “lowest” (cheapest first). |
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 date-pairs to return (1-100). Default 20. |
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. |