Tool description (what the LLM sees)
Tool description (what the LLM sees)
Cache-only flight price snapshot for a fixed origin/destination + dates pair. 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).
- 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: IATA city code preferred (PAR, NYC, LON); pin to airport only when the user actually committed to a specific airport.
- Use the SAME filter set the user has been monitoring against between polls.
PRICES: flight.total_price is an object {value, currency, decimal_places} where value is an INTEGER in minor units, divide value by 10^decimal_places before displaying (value 15977 with decimal_places 2 is 159.77 USD). JPY/KRW use 0 decimals, so never hardcode a division by 100.
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") | No | How to interpret origin. “city” (default) searches all airports in the city; “airport” pins to one airport. |
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") | No | How to interpret destination. Same semantics as origin_type. |
departure_date | string | Yes | Single departure date (YYYY-MM-DD). Exactly one date, no arrays or ranges. |
return_date | string | 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_price | number | No | Upper bound on the total fare in the requested currency. Lowest-fare semantics are “lowest within the filter constraints”, max_price 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. |
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 | Number of infant travelers (under 2). |
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. “find a cheap flight to Tokyo in mid-June”. 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 and never changes the result of the call; Jinko uses it to understand demand and improve results. |
Examples
Daily poll of PAR → NYC for a date pair:{
"name": "price_monitoring",
"arguments": {
"origin": "PAR",
"destination": "NYC",
"departure_date": "2026-06-17",
"return_date": "2026-06-26",
"currency": "EUR"
}
}
{
"name": "price_monitoring",
"arguments": {
"origin": "PAR",
"destination": "NYC",
"departure_date": "2026-06-17",
"return_date": "2026-06-26",
"direct_only": true,
"cabin_class": "economy",
"max_price": 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.