Tool description (what the LLM sees)
Tool description (what the LLM sees)
Cache-only flight price snapshot for a fixed origin/destination + dates pair. Returns one snapshot per call. The calling agent or application must schedule repeated calls and send notifications; this tool creates no persistent monitor or alert subscription. Intended for scheduled polling, NOT for one-shot shopping or booking.
WHEN TO USE:
- Track the price of a specific route + dates over time and react when it drops (cron / scheduled job).
- Recommended cadence: poll no faster than the cache refresh interval. Polling faster is wasted work.
WHAT IT RETURNS:
- The single cheapest cached itinerary matching the request filters (lowest WITHIN the filter constraints, filters constrain the candidate set, not the win condition).
- Its price is a ONE-ADULT fare. traveler_counts has no effect on the fare, max_total cap, or returned flight (the price and cap are for one adult; the counts are only echoed back in request_echo); the response contains no booking link. Use flight_search with max_total for the exact whole-trip budget check for all travelers.
- An offer_token that remains re-shoppable via flight_search (price_check mode) when the user decides to book.
- status: "ok" (offer present) or "stale" (cache had no matching itinerary, retry later, or call flight_search for a live quote).
WHEN TO USE flight_search INSTEAD:
- The user is ready to book NOW and needs a live quote.
- One-shot exploration where you don't intend to come back.
WHEN TO USE flight_calendar / find_destination INSTEAD:
- Flexible dates or ranges, price_monitoring requires exact departure_date (+ optional exact return_date).
- The user is still exploring and hasn't committed to a specific route to monitor.
CACHE-ONLY CONTRACT:
- This tool NEVER triggers a live connector call. status:"stale" is the correct response when the cache is cold, do not retry in a tight loop and do not silently fall back to flight_search.
INPUT NOTES:
- Origin / destination: the city code when the user named a city (PAR, NYC, LON); origin_type / destination_type "airport" when they named an airport. Untyped, a code that names a multi-airport city is the city and any other code is the airport, LAX, MIA and LAS are read as the city.
- Use the SAME filter set the user has been monitoring against between polls.
The result carries `search_criteria` (what was actually monitored). On `status: "stale"` it also carries `next`: the live `flight_search` for the same dates, to offer when the user needs a price now, monitoring itself stays cache-only.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
origin | string | Yes | Origin IATA city code (e.g. PAR, NYC, LON) or airport code (CDG, JFK, LHR). City codes preferred, they cover every airport in the city. |
origin_type | enum ("city" | "airport") | null | No | How to read origin: “city” searches every airport of the city; “airport” only that one airport. With no type sent, the platform applies one rule: a code that names a multi-airport city is searched as the city; every other code is searched as the airport. NYC, LON, PAR → the city. JFK, LHR, CDG → the airport. LAX, MIA, LAS, codes a city shares with its main airport, → the CITY, every airport of it. If the user named the airport (“LAX”, “JFK”, “Heathrow”), send “airport”; if they named the city (“Los Angeles”, “New York”), send the city code and omit the type. |
destination | string | Yes | Destination IATA city code (e.g. MIL, BCN, TYO) or airport code (MXP, BCN, NRT). City codes preferred. |
destination_type | enum ("city" | "airport") | null | No | How to read destination: “city” searches every airport of the city; “airport” only that one airport. With no type sent, the platform applies one rule: a code that names a multi-airport city is searched as the city; every other code is searched as the airport. NYC, LON, PAR → the city. JFK, LHR, CDG → the airport. LAX, MIA, LAS, codes a city shares with its main airport, → the CITY, every airport of it. If the user named the airport (“LAX”, “JFK”, “Heathrow”), send “airport”; if they named the city (“Los Angeles”, “New York”), send the city code and omit the type. |
departure_date | string | Yes | Single departure date (YYYY-MM-DD). Exactly one date, no arrays or ranges. |
return_date | string | null | No | Single return date (YYYY-MM-DD). Omit for one-way. Must be on or after departure_date. |
direct_only | boolean | No | If true, only return non-stop flights. Mirror the upstream filter the user committed to when they started monitoring. |
cabin_class | enum ("economy" | "premium_economy" | "business" | "first") | No | Cabin class filter. Omit for economy. |
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. traveler_counts has no effect on the fare, the max_total cap, or the returned flight (the counts are only echoed back in request_echo). Lowest-fare semantics are “lowest within the filter constraints”, max_total tightens the candidate set, not the win condition. |
include_carriers | array<string> | No | IATA 2-letter marketing carrier codes to include (whitelist). Example: [“AF”,“KL”]. Use to lock monitoring to specific airlines the user actually flies. |
exclude_carriers | array<string> | No | IATA 2-letter marketing carrier codes to exclude (blacklist). Example: [“FR”,“U2”]. Use to keep airlines the user refuses out of the picture. |
traveler_counts | object | No | Traveler counts. Defaults to 1 adult. They do not affect the fare, the max_total cap, or the returned flight (the counts are only echoed back in request_echo). The price and cap are for one adult, and the response contains no booking link. |
traveler_counts.adults | integer | No | Number of adult travelers (12+). |
traveler_counts.children | integer | No | Number of child travelers (2-11). |
traveler_counts.infants | integer | No | Infant travelers (under 2), traveling on an adult’s lap. Seated infants (own seat) are not supported. |
locale | string | No | User’s BCP 47 locale (e.g. “fr-FR”, “en-US”). Inherits from the conversation locale if omitted. |
currency | string | No | ISO 4217 currency code (e.g. “EUR”, “USD”). Inherits from the conversation if omitted. Must match the currency the user is monitoring against, switching currencies mid-poll is not what they want. |
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
Daily poll of PAR → NYC for a date pair:{
"name": "price_monitoring",
"arguments": {
"origin": "PAR",
"destination": "NYC",
"departure_date": "2027-06-17",
"return_date": "2027-06-26",
"currency": "EUR"
}
}
{
"name": "price_monitoring",
"arguments": {
"origin": "PAR",
"destination": "NYC",
"departure_date": "2027-06-17",
"return_date": "2027-06-26",
"direct_only": true,
"cabin_class": "economy",
"max_total": 800,
"include_carriers": ["AF", "KL"],
"currency": "EUR"
}
}
offer_token is directly re-shoppable via flight_search (price_check mode) when the user is ready to book.