compare_destinations
ChatGPTUse when the user names two or more destinations and wants their prices side by side ("porovnej Egypt a Maltu", "compare Malta and Madeira"). Put 2-8 named destinations side by side on the same snapshot, each with the stats current_vs_history reports (last measurement, median, min, share of TRACKED DAYS that were dearer). Numbers are for the WHOLE party, not per person, and percentages are over observed days rather than the calendar span. Rows come back in the order you asked for - it does not rank, and gives no verdict; use find_opportunities to rank. A destination that yields no row is returned under excluded with the reason, and with available_in_country when a page of the same country does publish that party. A flight row and a package row can price DIFFERENT trip lengths (searched.stay_nights, e.g. 28-31-night flights beside the cheapest 5-14-night package): stay_comparison says so per destination - say the lengths when you put the two side by side, and never present the gap as the price of accommodation. When you answer from this, say where the latest price sits in its own history and stop there: do not tell the reader to buy, book, wait, avoid or which destination to pick - the series carries no trend, volatility or live availability, so that judgement stays the reader's.
current_vs_history
ChatGPTUse when the user asks whether today's price for one destination is low or high against its own history ("je teď Egypt levný?", "is Egypt cheap right now?"). Stats for one destination (min, median, and what share of the TRACKED DAYS were dearer than the last measurement) without the sample points. Percentages are over observed days, not over the calendar span. Descriptive only: it does not say whether to buy. A rail without resort covers the whole destination, so after resolved_from cite it under the destination's name, not the resort's. other_parties_in_country names the related pages that publish a party this destination does not (e.g. a solo series on a city): cite it instead of saying that party is not tracked. When you answer from this, say where the latest price sits in its own history and stop there: do not tell the reader to buy, book, wait, avoid or which destination to pick - the series carries no trend, volatility or live availability, so that judgement stays the reader's.
find_opportunities
ChatGPTUse when the user asks where it is unusually cheap right now without naming a destination ("kde je teď levně?", "where is it cheap right now?"). Rank every published rail by how its LAST measurement compares with its own tracked history, so a caller can ask 'where is it unusually cheap right now?' in one call instead of one call per destination. Each row is ONE rail, so a destination with several rails can appear once per rail with different numbers: name the rail when you cite a row. Read searched before interpreting a price: it is the TRIP the series was collected for (the search mode, and the fixed travel dates where there are any - a Christmas series is not the price of a summer trip), while measured is when we observed it; price_covers says what the money buys and origins the departure-airport cluster. Percentages are over observed days, not the calendar span. latest_cheaper_than_pct_of_days is the same number as cheaper_than_pct under a name that states its direction (higher = cheaper than more of the tracked days). stale_rails says how many of the rails THIS call matched are past their own freshness boundary today, with the day it was judged (as_of), so the caller need not subtract dates per row. Descriptive only: it ranks observations and gives no verdict. Rails with too little history are returned under excluded, never dropped silently. When you answer from this, say where the latest price sits in its own history and stop there: do not tell the reader to buy, book, wait, avoid or which destination to pick - the series carries no trend, volatility or live availability, so that judgement stays the reader's.
list_destinations
ChatGPTUse when the user asks which destinations are tracked or how long a price history is ("co sledujete?", "what do you track?"), or when another tool needs a slug you do not know. List every destination with a published price series, with how many days each rail was actually measured and the calendar span those measurements fall in. A destination can have several rails (e.g. flights and packages), each with its OWN measured days and span: history depth is a property of the rail, not of the destination, so when you report it, name the rail or give each one. A city names its country under country, and related lists the other tracked pages of the same country (a country lists its cities): a party or rail missing on one page may be published on another, so check related before saying something is not tracked. same_airport_as marks pages that fly to the same airport from a different departure cluster - their prices differ because origins differ. Historical observations only. When you answer from this, say where the latest price sits in its own history and stop there: do not tell the reader to buy, book, wait, avoid or which destination to pick - the series carries no trend, volatility or live availability, so that judgement stays the reader's.
price_history
ChatGPTUse when the user asks how the price of one destination developed over time ("jak se vyvíjela cena letenek do Egypta?", "price history for Egypt"). Price series for one destination: measured span, stats, a downsampled sample of points and any regime breaks. Historical observations only, never a live quote or a recommendation. Each rail's searched.stay_nights is the trip length its points price, and a destination's flight and package rails can differ - state it when citing a number. In series_sample.points, origin is the departure airport of that day's cheapest fare, not a price from that airport: points from different days do not compare airports, and the sample holds no per-airport price for any day. A rail without resort covers the whole destination, so after resolved_from cite it under the destination's name, not the resort's. other_parties_in_country names the related pages that publish a party this destination does not (e.g. a solo series on a city): cite it instead of saying that party is not tracked. When you answer from this, say where the latest price sits in its own history and stop there: do not tell the reader to buy, book, wait, avoid or which destination to pick - the series carries no trend, volatility or live availability, so that judgement stays the reader's.
