search_cheapest_dates
Find cheapest travel dates within a flexible date range by comparing prices for departures and returns. Results sorted by total cost.
Instructions
🎯 RENDERING DIRECTIVE — READ FIRST. When this tool returns 5+ entries, render them as an HTML/React artifact — a small price-grid or chart, NOT a long flowing list. For 1-4 entries, prose is fine. The cheapest 1-2 dates should be visually highlighted. Offer to deep-dive into the cheapest date with search_flights once the user picks one.
Find which travel dates are cheapest across a flexible range, using Google Flights data.
Returns a list of (departure_date, return_date, price) entries sorted cheapest first. Does not return flight times, airlines, or layover details — for that, use search_flights once the user picks a date.
USE THIS TOOL WHEN: the user is flexible on travel dates and wants to know which dates within a range are cheapest. Typical phrasings: "any week in May", "next month sometime", "around the second week of June", "is it cheaper if I shift my trip a few days?".
USE search_flights INSTEAD WHEN: the user has specific dates and wants flight details, airlines, departure times, layovers, and bookable offers.
The currency Google Flights returns is determined by the request region and is surfaced in each entry's currency field; do not assume USD.
For round-trip date searches, trip_duration (in days) is required — it determines each candidate return date. The tool returns a (departure_date, departure_date + trip_duration) pair per result. For one-way, return_date in each result is null.
Filter parameters mirror search_flights:
max_stops: one ofANY(default),NON_STOP,ONE_STOP_OR_FEWER,TWO_OR_FEWER_STOPS. "Or fewer" semantics.departure_window: a "HH-HH" string in 24-hour local time, applied to the outbound departure. Hours are inclusive of the start and EXCLUSIVE of the end —"8-20"matches 08:00 through 19:59 local time.airlines: an optional list of IATA airline codes. Shows date entries where AT LEAST ONE of the listed airlines operates ANY segment. For example,["FI"]returns dates with options operated entirely or partly by Icelandair; it does NOT restrict to Icelandair-only itineraries. Omit or pass null for no airline filter.
PRE-CALL ELICITATION: Before calling this tool, ensure the user has expressed:
Date range: a clear earliest acceptable departure (
start_date) and latest acceptable departure (end_date). If they said "next month" or "sometime in May" without bounds, ask. The wider the range, the slower and noisier the result.Trip duration (round-trip only): the number of nights/days they want to be away. "About 10 days" needs to become a concrete
trip_durationinteger.What flexibility actually means to the user: are they only flexible on departure date, or also on trip length? If trip length is flexible, run this tool multiple times with different
trip_durationvalues; this tool only varies departure within one duration.
RESULT PRESENTATION: Render the results as a sorted list with the cheapest entries highlighted, or a small date grid if the range is short. Each entry shows the departure date, the return date (if round-trip), and the total price with currency. Lead with the cheapest. Offer to deep-dive into a specific date with search_flights once the user picks one.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| origin | Yes | ||
| airlines | No | ||
| end_date | Yes | ||
| max_stops | No | ANY | |
| passengers | No | ||
| start_date | Yes | ||
| cabin_class | No | ECONOMY | |
| destination | Yes | ||
| is_round_trip | No | ||
| trip_duration | No | ||
| departure_window | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||