INSPIRATION: "I have $1500, where can I go?" Ranks destinations under a total budget with flight + hotel costs calculated.

Args: origin: Departure airport IATA code (e.g., "JFK") total_budget: Total budget for trip trip_length_days: Number of nights departure_month: YYYY-MM (e.g., "2026-08") or omit for any travelers: Number of travelers interests: Comma-separated (e.g., "beach,food,history") visa_free_only: Only visa-free destinations (requires passport_country) passport_country: ISO 2-letter code (e.g., "US") currency: USD, EUR, etc. max_results: Max destinations to return

INSPIRATION: Find cheapest destinations from origin airport.

"Show me cheap flights from NYC anywhere in March" - returns ranked destinations by price. Set round_trip_days for realistic round-trip budgeting.

Args: origin: IATA airport code (e.g., "JFK") month: YYYY-MM constraint (optional) max_price: Filter out above this price (per-person) max_results: Max destinations currency: USD, EUR, etc. regions: Comma-separated (europe, asia, americas, oceania, africa, middle_east) round_trip_days: Days at destination for round-trip price (omit for one-way)

INSPIRATION: Compare multiple destinations side-by-side for same dates.

"Paris vs Rome vs Barcelona for next month" - returns flight + hotel costs for each, ranked by total cost.

Args: origin: Departure airport IATA code destinations: Comma-separated (e.g., "CDG,FCO,BCN" or "Paris,Rome,Barcelona") departure_date: YYYY-MM-DD return_date: YYYY-MM-DD travelers: Number of travelers currency: USD, EUR, etc.

Search live flight prices between two airports using Google Flights data.

Read-only. No auth required. No rate limits enforced. Data freshness: scraped live at call time; prices may shift minute-to-minute. Returns a list of flight options each with price, stops, duration, airline, and booking deeplink.

Use this when the user wants to compare specific flight options for a known origin-destination pair. Use tool_fare_calendar instead when dates are flexible. Use tool_find_cheapest_month for month-level planning. Use tool_cheap_anywhere_from when the destination is open. Use tool_optimize_budget to bundle flights + hotels.

Args: origin: IATA airport code (e.g., "JFK", "LAX", "LHR") destination: IATA airport code (e.g., "CDG", "NRT", "SYD") departure_date: YYYY-MM-DD return_date: YYYY-MM-DD (omit for one-way) adults: Number of passengers, 1-9 max_results: Max flight options to return (1-20) currency: ISO currency code — USD, EUR, GBP, INR, etc. nonstop_only: True to exclude connecting flights

PLANNING: Search hotels in a city.

Uses Google Hotels names through fast_hotels plus booking deeplinks. Args: city: City name (e.g., "Paris", "Tokyo") - NOT IATA code check_in: YYYY-MM-DD check_out: YYYY-MM-DD adults: Number of guests rooms: Number of rooms max_results: Max results currency: USD, EUR, etc. price_range: "100-300" ratings: "3,4,5"

PLANNING: Generate data-backed day-by-day itinerary with real activities and weather.

Args: destination: City and country (e.g., "Paris, France") start_date: YYYY-MM-DD end_date: YYYY-MM-DD interests: Comma-separated (e.g., "food,history,nature,art") budget_level: budget, moderate, luxury travelers: Number of travelers include_weather: Include forecast include_activities: Include nearby attractions

Find the cheapest flight + hotel combination across flexible date windows.

Read-only. No auth required. Scrapes Google Flights and Hotels live; prices are indicative and may shift. Returns ranked date combinations each with total cost (flights + estimated hotel), per-person breakdown, and booking deeplinks.

Use this when the user wants the lowest total trip cost and can shift dates by a few days. Use tool_search_flights for fixed-date flight-only search. Use tool_fare_calendar for a full month price grid without hotel bundling.

Args: origin: Departure airport IATA code (e.g., "JFK") destination: Arrival airport IATA code (e.g., "CDG") departure_date: Preferred departure YYYY-MM-DD return_date: Preferred return YYYY-MM-DD adults: Number of travelers (affects per-person vs total cost) currency: ISO currency code — USD, EUR, etc. flexible_dates: True to search ±flexibility_days around given dates flexibility_days: Date window to search each side, 1-7

Official US State Department travel advisory for a country.

Returns advisory level (1=safe, 4=do not travel), summary, and link. No API key. Cached 60 min.

Args: country: Country name in English (e.g., "Japan", "Egypt") or ISO code

List countries currently at advisory level X or above.

"What countries should I avoid right now?"

Args: min_level: 1-4. Default 3 = Reconsider Travel. 4 = Do Not Travel.

DIFFERENTIATOR: Find concerts, shows, sports during your trip dates.

"Coldplay is in Paris while you're there." Uses Ticketmaster Discovery.

Args: city: City name start_date: YYYY-MM-DD end_date: YYYY-MM-DD classification: music, sports, arts, family, film, miscellaneous keyword: Artist, team, or show name max_results: Max events

DIFFERENTIATOR: Cost-of-living index + quality of life scores for a city.

"Your $100/day = lavish in Lisbon, broke in London." Free, no auth. Covers ~270 cities globally with detailed quality scores.

Args: city: City name (e.g., "Lisbon", "Tokyo", "San Francisco") home_currency: Your home currency (USD, EUR, etc.)

DIFFERENTIATOR: Multi-objective destination ranking.

Scores destinations on cost + weather + safety + events + quality of life simultaneously. The killer "where should I actually go?" tool.

Args: destinations: Comma-separated (e.g., "Paris,Rome,Barcelona,Tokyo") travel_start: YYYY-MM-DD travel_end: YYYY-MM-DD weights: key:weight pairs (e.g., "cost:3,weather:2") weather_pref: warm_dry, cool_dry, warm_any, snow, shoulder_season origin: Optional origin airport

WEATHER timing: best month to visit by climate, not price.

"When is Bali at its best?" Uses 5yr Open-Meteo historical archive. No auth. For cheapest month by airfare use find_cheapest_month; for day-level price grid within a month use fare_calendar.

Args: latitude: Location latitude longitude: Location longitude preferences: warm_dry, cool_dry, warm_any, snow, shoulder_season

Get weather forecast for travel dates. No auth required.

Args: latitude: Latitude longitude: Longitude start_date: YYYY-MM-DD end_date: YYYY-MM-DD

Convert between currencies with live rates. No auth required.

Args: amount: Amount to convert from_currency: Source currency (e.g., "USD") to_currency: Target currency (e.g., "EUR")

Get exchange rates. No auth required.

Args: base_currency: Base (e.g., "USD") target_currencies: Comma-separated targets or omit for all

Search activities and attractions near a GPS coordinate using Wikidata/OpenTripMap.

Read-only. No auth required. No rate limits. Data source: Wikidata with OpenTripMap fallback — community-curated, not real-time. Returns a list of places each with name, category, coordinates, description, and Wikipedia link where available.

Use this when you have coordinates (from tool_geocode) and need nearby things to do. Use tool_search_restaurants_bars specifically for dining. Use tool_get_local_events for time-sensitive events like concerts or festivals. Not suitable for business hours or current pricing — those change frequently.

Args: latitude: Decimal latitude (e.g., 48.8566 for Paris) longitude: Decimal longitude (e.g., 2.3522 for Paris) radius_km: Search radius in km, 1-50 category: Filter by type — culture, nature, food, shopping, nightlife, architecture, historic, museums, religion, sport — or omit for all max_results: Max places to return, 1-50

Essential country info (currency, language, timezone). No auth required.

Args: country_name: Country name (e.g., "Japan")

City or place -> coordinates. No auth required.

Args: place_name: City or place (e.g., "Paris, France")

Verify a named place actually exists by cross-checking OSM, Foursquare, and OpenTripMap.

Read-only. No auth required (Foursquare key optional; degrades gracefully without it). Returns: verified (bool), confidence score, canonical name, coordinates, matched sources, and a warning message if the place appears to be hallucinated.

Use this before presenting any specific restaurant, hotel, or attraction to the user — especially when the name came from an LLM rather than a live API. Do not use for checking business hours or current availability; this only confirms existence. Use tool_geocode if you only need coordinates for a city or landmark.

Args: place_name: Place name to verify (e.g., "Eiffel Tower", "Nobu Tokyo") city: City context to narrow the search (e.g., "Paris", "Tokyo") expected_type: Optional type hint — restaurant, attraction, hotel, museum, park

Verify a flight route exists between two airports.

Args: origin: IATA code destination: IATA code

KILLER: Find hidden-city ticketing fares (cheaper than direct).

Buy NYC->Mexico via Houston, get off in Houston, save 60%. Skyscanner and Kayak are CONTRACTUALLY FORBIDDEN from showing these. We pull them direct from Skiplagged.

CAVEATS: Carry-on only. One-way only. No frequent flyer credit. Tool returns warnings.

Args: origin: IATA code (e.g., "JFK") destination: IATA code (e.g., "LAX") departure_date: YYYY-MM-DD return_date: YYYY-MM-DD (compare round-trip; book separately) max_results: max fares to return

Find the cheapest city for a group of travelers flying from different origins to meet.

Read-only. No auth required. Scrapes Google Flights live for each origin-destination pair; results are indicative. Returns a ranked list of meeting cities each with total group cost, per-traveler cost breakdown, and individual flight details. Combinatorial search — response time scales with number of origins × candidates.

Use this when multiple travelers in different cities need to meet and want to minimize total group flight spend. Use tool_search_flights for single-origin itineraries. Use tool_optimize_budget when origin and destination are fixed.

Args: origins: Comma-separated IATA codes for each traveler's departure city (e.g., "JFK,LHR,NRT" for New York, London, Tokyo) departure_date: YYYY-MM-DD shared departure date return_date: YYYY-MM-DD shared return date max_results: Max candidate meeting cities to return (1-20) currency: ISO currency code for price display — USD, EUR, etc. regions: Comma-separated region filter to narrow candidates — europe, asia, americas, middleeast, africa (omit for global)

KILLER: Reverse search - "where to see northern lights cheapest, next 60 days?"

Combines NOAA KP-index forecast + aurora-zone airports + flight prices. Returns ranked destinations with aurora visibility scores.

Args: origin: Departure IATA code max_budget: Max flight budget days_ahead_min: Earliest departure (days from now) days_ahead_max: Latest departure currency: USD, EUR, etc. max_results: max destinations

Fetch recent mistake fares and deal alerts from Secret Flying and Flight Deal RSS feeds.

Read-only. No auth required. Data freshness: RSS feeds polled at call time, posts typically 1-48 hours old. Returns a list of deals each with origin, destination, price, sale price, percentage discount, source, and post date. Does not book or hold fares — prices expire fast, often within hours.

Use this when the user wants passive deal discovery without a fixed destination. Use tool_search_flights when the user has a specific route and date in mind. Use tool_fare_calendar for flexible-date price grids on a known route.

Args: origin: City name to filter deals by departure city (e.g., "New York", "London") — omit to return deals from all origins days_lookback: Include only posts published in the last N days (1-30) max_results: Max deals to return (1-50)

Check the visa requirement for one passport entering one destination country.

Read-only. No auth required. Data source: built-in curated dataset (static snapshot — regulations change; always verify with the official embassy before travel). Returns: category (visa_free / eta_required / visa_on_arrival / evisa / visa_required), apply_link, estimated cost, processing time, and guidance notes. Invalid ISO codes return an error field, not an exception.

Use this for a single passport-destination pair. Use tool_visa_free_destinations to list all countries a passport can enter. Use tool_check_transit_visa specifically for layover/transit visa requirements, not entry visas.

Args: passport_country: ISO 2-letter passport country code (e.g., "US", "GB", "IN") destination_country: ISO 2-letter destination country code (e.g., "JP", "TH", "BR")

List all countries a passport can enter without a traditional pre-arranged visa.

Read-only. No auth required. Data source: built-in curated dataset (static snapshot — verify with official embassy before travel). Returns a list of countries each with entry category, apply link, and notes. Invalid passport codes return an empty list. Territories and disputed regions may not be included.

Use this for broad destination discovery ("where can I go without a visa?"). Use tool_check_visa_requirement for a precise single-pair lookup. Use tool_check_transit_visa for transit/layover visa checks, not entry.

Args: passport_country: ISO 2-letter passport country code (e.g., "IN", "BR", "ZA") include_categories: Comma-separated filter — valid values: visa_free, visa_on_arrival, evisa, eta_required (default includes all four)

Load the stored traveler profile (home airports, passports, history).

ALWAYS call this at the start of a session. If onboarded=False, walk the user through onboard_traveler before doing anything else.

First-time setup. Saves the traveler profile for reuse every future session.

Args: name: First name home_airports: Comma-separated IATA (e.g., "JFK,EWR") passports: Comma-separated ISO-2 (e.g., "US" or "US,IN") home_currency: USD, EUR, GBP, INR, etc. travel_style: budget, moderate, luxury interests: Comma-separated (e.g., "food,history,beach") dietary: Comma-separated restrictions preferred_cabin: economy, premium_economy, business, first visas_held: ISO-2 dest codes with active visas (e.g., "IN,CN") eta_held: Active ETAs (e.g., "ESTA (US),UK ETA")

Update profile fields, manage cards, or log a trip. Pass only what changed.

Args: name: Update name home_airports: Replace home airports (comma-separated IATA) passports: Replace passports (comma-separated ISO-2) home_currency: Update home currency travel_style: budget, moderate, luxury interests: Replace interests (comma-separated) dietary: Replace dietary restrictions preferred_cabin: economy, premium_economy, business, first visas_held: Replace full visa list (comma-separated ISO-2 dest codes) eta_held: Replace ETA list add_visa: Append one ISO-2 dest code to visas_held add_card: Card key to add (e.g., "chase_sapphire_reserve", "amex_gold", "bilt_mastercard") add_card_nickname: Optional nickname for the card add_card_balance: Current points balance on this card's program remove_card: Card key to remove from portfolio add_trip_destination: Log a trip — destination name add_trip_from: Trip start YYYY-MM-DD add_trip_to: Trip end YYYY-MM-DD add_trip_purpose: tourism, business, family, other

View logged trip history for this traveler.

Args: limit: Max trips to return (most recent first)

Search bus, train, and ferry options between two cities.

Returns multi-modal route overview + direct booking links for Amtrak, FlixBus, Greyhound, Megabus, OurBus, BlaBlaCar, Busbud, Trainline, IRCTC, 12Go, and Rome2Rio. No API key required.

Args: origin_city: Departure city (e.g., "State College", "Paris", "Mumbai") destination_city: Destination city (e.g., "New York", "London", "Delhi") date: Departure date YYYY-MM-DD travelers: Number of travelers region: us, europe, india, sea — auto-detected if omitted

Complete bookable trip package in one call: flights, hotels, visa, weather, advisory, attractions, ground transport, cost estimate + booking URLs/checklist.

Use when the destination is decided; use score_destinations if still deciding.

Args: origin: Departure airport IATA or city (e.g., "DXB", "JFK", "New York") destination: Destination city (e.g., "Bali", "Tokyo", "Paris") departure_date: YYYY-MM-DD return_date: YYYY-MM-DD (auto-calculated from trip_length_days if omitted) trip_length_days: Nights (used when return_date omitted) travelers: Number of travelers passport_country: ISO-2 for visa check (e.g., "US", "IN", "GB") currency: Home currency for all prices budget_level: budget, moderate, luxury interests: Comma-separated (e.g., "beach,food,history") include_ground_transport: Also search buses/trains

Find restaurants/bars/pubs/cafes near a location: cuisine, price, hours, distance + links to Google Maps, Zomato, TripAdvisor, Yelp, OpenTable, Resy, Untappd, Foursquare. Ratings need FOURSQUARE_API_KEY (free tier).

Args: latitude: Location latitude longitude: Location longitude category: restaurant | bar | pub | cafe | nightlife | all radius_m: Walk radius in metres (default 1000 = ~12min walk) max_results: Max venues (1-30) cuisine: Filter by cuisine e.g. "italian", "japanese", "thai", "indian" city: City name for better search links e.g. "Tokyo", "Paris"

Generate a smart packing list tailored to destination, weather, and activities.

Fetches live weather to adapt clothing and gear suggestions.

Args: destination: City or country name start_date: YYYY-MM-DD end_date: YYYY-MM-DD activities: Comma-separated (e.g., "beach,hiking,business,nightlife") budget_level: budget, moderate, luxury travelers: Number of travelers latitude: Optional — auto-fetched if omitted longitude: Optional — auto-fetched if omitted

Find viewpoints, beaches, hiking trails, coworking spaces, and more.

Uses OpenStreetMap — no API key required.

Args: latitude: Location latitude longitude: Location longitude category: viewpoint | beach | hiking | coworking | waterfall | camping | market | hot_spring | museum | park radius_km: Search radius in km (1-100) max_results: Max places to return city: City name for richer search links (e.g., "Bali", "Cape Town")

Calculate jet lag severity and give a science-based recovery schedule.

Covers pre-departure schedule shift, on-plane tips, melatonin timing, and post-arrival light exposure strategy.

Args: origin: City or IATA code (e.g., "New York", "JFK") destination: City or IATA code (e.g., "Tokyo", "NRT") departure_date: YYYY-MM-DD flight_duration_hours: Flight time in hours (0 = auto-estimated)

Get a phrasebook for the local language at a destination.

Covers 17 languages with pronunciation guides and essential phrases.

Args: destination: City or country name (e.g., "Tokyo", "France", "Bangkok") language_code: Override language (ja, fr, es, it, de, pt, th, zh, ar, ko, hi, vi, id, tr, ms, sw) category: greeting | essential | food | transport | shopping | emergency | accommodation | numbers

Get a layover activity guide for a major hub airport.

Read-only. No auth required. Data source: built-in curated dataset for 10 hubs: IST, DXB, SIN, DOH, NRT, HND, CDG, HKG, ICN, AMS. Returns in-terminal activities, city excursion options (only suggested when layover_hours is sufficient for safe exit/re-entry), and transit visa status for the given passport. Unsupported airports return an error field with a list of supported IATA codes.

Use this when the user has a confirmed layover and wants to make use of the time. Use tool_check_transit_visa for a standalone transit visa check without activity content. Do not use for airports not in the supported list above.

Args: airport: IATA code of the layover airport (e.g., "DXB", "SIN", "IST") layover_hours: Total available layover time in decimal hours (e.g., 4.5) passport_country: ISO-2 passport code for transit visa check (e.g., "IN", "US") — omit to skip visa check

Get recent travel news and disruption alerts for a destination.

Scans Google News RSS for strikes, airport closures, entry bans, protests. No API key required.

Args: destination: City or country name (e.g., "Paris", "Thailand") days_lookback: Only news from last N days (1-30) max_results: Max articles to return

Health requirements, vaccine recommendations, and safety tips for a destination.

Covers required vaccines, CDC/WHO recommendations, water safety, mosquito risk, altitude sickness, food safety, and a pre-departure preparation timeline.

Args: destination_iso2: ISO 2-letter country code OR IATA airport code (e.g., "TH", "JP", "BKK", "DPS") trip_duration_days: Trip length (affects malaria prophylaxis advice etc.)

Score and rank cities for digital nomad / remote-work suitability.

Combines cost of living, safety advisory, internet speed index, weather comfort, visa ease, and lifestyle/coworking data into a single ranked score. No API key required.

Args: cities: Comma-separated city names (e.g., "Bali,Lisbon,Chiang Mai,Medellin") month: Month 1-12 to evaluate weather (default: current month) weights: Scoring weights as "dimension:percent" pairs summing to 100. Dimensions: cost, safety, internet, weather, visa, lifestyle

Check if you need a transit visa for a layover airport.

Covers the most common passport + layover combinations for 40+ major hubs: LHR, JFK, LAX, FRA, AMS, CDG, DXB, SIN, IST, DOH, NRT, ICN, HKG, YYZ, SYD, and more. This is a common trip-ruiner — carriers deny boarding if you lack the required transit document. Check BEFORE booking.

Args: passport_country: Your passport ISO2 code (e.g., "IN", "US", "NG") layover_airport: IATA code of layover airport (e.g., "LHR", "DXB", "JFK") connecting_to: Optional final destination airport IATA (for context)

Calculate CO2e carbon footprint for a flight.

Uses ICAO/DEFRA 2024 emission factors including radiative forcing (RFI ×1.9). Shows per-passenger and total emissions, carbon offset cost at Gold Standard prices ($18/tonne), and train/car comparison for short-to-medium routes. No API key required.

Args: origin: Origin airport IATA code (e.g., "JFK") destination: Destination airport IATA code (e.g., "LHR") passengers: Number of passengers cabin_class: economy | premium_economy | business | first trip_type: one_way | round_trip

PRICE timing (day-level): cheapest DAY to fly within ONE month.

Samples up to 15 departure dates in one month — day-of-week analysis, price tiers, best/worst weeks. For cheapest MONTH across a year use find_cheapest_month; for best weather use best_month_to_visit.

Args: origin: Origin airport IATA code (e.g., "JFK") destination: Destination airport IATA code (e.g., "LHR") year: Year (default: next occurrence of month) month: Month 1-12 (default: next month) adults: Number of passengers cabin_class: economy | premium_economy | business | first currency: Currency code (e.g., "USD", "EUR", "GBP") trip_length_days: If set, price as round-trip (return = departure + N days)

Find savings by booking two separate tickets through a hub (prices origin→hub and hub→destination independently). 20-60% off on competitive long-haul routes. ⚠️ Missed-connection risk is on the traveler — surface result risks before booking.

Args: origin: Origin airport IATA code (e.g., "SFO") destination: Destination airport IATA code (e.g., "DEL") departure_date: YYYY-MM-DD departure date adults: Number of passengers cabin_class: economy | premium_economy | business | first currency: Currency code min_connection_hours: Minimum buffer hours between tickets at hub

Rank passport strength, optionally compare two head-to-head: visa-free count, frictionless %, regional breakdown, Henley 2024 rank. With compare_with, shows which destinations each passport unlocks that the other doesn't.

Args: passport_country: Your passport ISO2 code (e.g., "US", "IN", "NG", "CN") compare_with: Optional second passport ISO2 for comparison (e.g., "GB")

Plan an open-jaw trip: fly into one city, overland, fly out from another (e.g. JFK→Rome, train to Paris, Paris→JFK). Shows total vs simple round-trip. Accepts IATA codes or city names.

Args: origin: Home airport IATA or city (e.g., "JFK" or "New York") fly_into: First destination IATA or city (e.g., "FCO" or "Rome") fly_out_from: Final departure IATA or city (e.g., "CDG" or "Paris") outbound_date: YYYY-MM-DD — fly origin → fly_into return_date: YYYY-MM-DD — fly fly_out_from → origin adults: Number of passengers cabin_class: economy | premium_economy | business | first currency: Currency code

PRICE timing (month-level): cheapest MONTH to fly across the next N months.

Samples the first Tuesday of each month, ranks months by price with season analysis. For cheapest DAY within one month use fare_calendar; for best weather use best_month_to_visit.

Args: origin: Origin airport IATA code (e.g., "JFK") destination: Destination airport IATA code (e.g., "BCN") months_ahead: Future months to scan (1-12, default 12) adults: Number of passengers cabin_class: economy | premium_economy | business | first currency: Currency code trip_length_days: Days for round-trip return leg (departure + N) trip_type: round_trip | one_way

Local SIM/eSIM guide for a country: operators, cost, data, where to buy, activation, tethering policy, duration advice. 25+ countries; falls back to Airalo/Holafly otherwise.

Args: country: Country name (e.g., "Thailand"), ISO2 code (e.g., "TH"), or city (e.g., "Bangkok") trip_duration_days: Trip length in days — affects local SIM vs eSIM recommendation data_heavy: True if you stream video, work remotely, or need constant hotspot

Save a trip the traveler is planning. Returns a trip_id + 8-item booking checklist.

Use when a traveler commits to a destination so progress persists across sessions.

Args: destination: City or country depart_date: YYYY-MM-DD return_date: YYYY-MM-DD origin: Home airport IATA travelers: Headcount passport_country: ISO2 for visa context purpose: leisure/business/etc notes: Free text

List the traveler's saved trips with checklist progress.

Args: status: Filter by planning/booked/completed/cancelled (omit for all)

Get a saved trip's full state + checklist progress. Look up by id or destination.

Args: trip_id: 8-char trip id destination: City/country if id unknown

Update a saved trip: change status/dates, tick checklist items, shortlist options.

Checklist keys: book_flights, book_hotel, check_visa, travel_insurance, book_ground_transport, check_advisory, pack, notify_bank.

Args: trip_id: 8-char trip id status: planning/booked/completed/cancelled depart_date: YYYY-MM-DD return_date: YYYY-MM-DD notes: Replace notes mark_done: Checklist key to mark done mark_undone: Checklist key to un-mark checklist_note: Note for the marked item shortlist_flight: Flight option dict to save shortlist_hotel: Hotel option dict to save

Delete a saved trip.

Args: trip_id: 8-char trip id

Create a fare watch that records a baseline price and alerts when a target is hit.

Writes to local profile store (~/.wander_agent/). No external auth required. Returns the created watch_id, baseline price fetched at creation time, and target_price (auto-set to 10% below baseline if not specified). The watch is passive — prices are only re-checked when tool_check_fare_watches is called.

Use this to begin monitoring a route. Use tool_check_fare_watches to poll for price changes. Use tool_list_fare_watches to see all active watches. Use tool_stop_fare_watch to pause or delete a watch when no longer needed.

Args: origin: Departure airport IATA code (e.g., "JFK") destination: Arrival airport IATA code (e.g., "LHR") depart_date: YYYY-MM-DD departure date return_date: YYYY-MM-DD return date for round trip; omit for one-way adults: Number of passengers (affects price baseline) currency: ISO currency code — USD, EUR, GBP, etc. target_price: Alert threshold; omit to auto-set at 10% below baseline

List saved fare watches with baseline/last/low prices.

Args: status: Filter active/paused/triggered (omit for all)

Re-price watched routes now and return buy-signal alerts.

Alerts: target_hit, price_drop, price_rise, no_change.

Args: watch_id: Check one watch, or omit to check all active watches

Pause or permanently delete a fare watch by its ID.

Writes to local profile store (~/.wander_agent/). No external auth required. Returns the updated watch record. Pausing (delete=False) keeps history but stops the watch from being checked by tool_check_fare_watches. Deleting (delete=True) removes it permanently with no recovery.

Use this when the user has booked the flight or no longer needs the alert. Use tool_list_fare_watches to find the watch_id if unknown. Use tool_check_fare_watches to re-price before deciding to stop.

Args: watch_id: ID of the watch to stop (from tool_list_fare_watches or tool_watch_fare) delete: False to pause (reversible); True to delete permanently

Rank flight/trip options on a 0-100 value score — price plus stops, duration, refundability, baggage and hassle — not price alone.

Pass a JSON array of option objects with any of: price, duration_minutes, stops, refundable, checked_bag_included, self_transfer, hidden_city, split_ticket, visa_required, transit_visa_required, label.

Args: options_json: JSON array of option objects priority: cheapest/fastest/easiest/flexible/balanced currency: Display currency

Is this award booking a good deal? Calculate cents-per-point and compare against baseline valuations for 20+ programs (Chase UR, Amex MR, airline miles, hotel points). Returns verdict: excellent/good/fair/poor.

Args: points_cost: Points/miles required for the award booking cash_price: What the same booking costs in cash program: Points program (e.g., "chase_ur", "amex_mr", "united_mp", "hyatt_woh") currency: Cash price currency taxes_fees: Taxes/fees still paid in cash on the award (e.g., fuel surcharges)

Show all airline and hotel transfer partners for a bank points program.

Maps Chase UR → United, Hyatt, BA, etc. Amex MR → Delta, ANA, Hilton, etc. Includes transfer ratios and transfer times. Sorted by partner value.

Args: program: Bank program key (e.g., "chase_ur", "amex_mr", "citi_typ", "capital_one", "bilt")

Should I pay cash or use points? Factors in cpp value, opportunity cost, and points-back earning on the cash payment. Returns a clear recommendation.

Args: cash_price: Cash price for the booking points_price: Points/miles price for the same booking program: Points program (e.g., "chase_ur", "united_mp") category: Spending category if paying cash (e.g., "travel", "dining") — affects earning calc card_key: Specific card to calculate earning (e.g., "chase_sapphire_reserve") currency: Cash price currency taxes_fees_on_award: Cash taxes/fees on the award redemption

Calculate points earned on a purchase for a specific credit card and spending category.

Read-only. No auth required. Uses static bonus multiplier data (standard published rates; does not reflect temporary promotions). Returns: points_earned, base_earn_rate, applied_multiplier, program name, and estimated_value_usd at mid-range cpp. Supports 9 cards: chase_sapphire_reserve, chase_sapphire_preferred, amex_platinum, amex_gold, capital_one_venture_x, citi_premier, bilt_mastercard, ink_preferred, amex_green.

Use this when the user wants to know which card to swipe for a specific purchase. Use tool_calculate_points_or_cash to decide whether to pay cash or redeem points. Use tool_estimate_points_value to evaluate a specific award booking's cpp.

Args: amount: Purchase amount (in the specified currency) card_key: Card identifier — chase_sapphire_reserve, amex_gold, bilt_mastercard, etc. category: Spending category — dining, travel, flights, restaurants, supermarkets, rent, general (default: general) currency: ISO currency code of the purchase (e.g., "USD", "EUR")

Curated list of the best-value award redemptions in the points game.

ANA first class for 120k VA miles (16.7cpp), Hyatt all-inclusive for 25k (2.4cpp), Turkish J to Europe for 45k (8.9cpp), Singapore Suites for 92k (16.3cpp), and more. Filters by your programs, cabin class, budget, or route.

Args: programs: Comma-separated program keys (e.g., "chase_ur,amex_mr") — omit to use profile cards cabin: Filter by cabin (economy, business, first, suites, hotel) max_points: Only show awards under this points threshold route_keyword: Filter by route (e.g., "Japan", "Europe", "Caribbean")

Which of my points programs gives the best value for this booking?

Compares estimated points cost across programs, portal vs transfer value, best transfer partner, and matching sweet spots. Uses profile cards if no programs specified.

Args: cash_price: What the booking costs in cash programs: Comma-separated (e.g., "chase_ur,amex_mr") — omit to use profile cards cabin: Target cabin class (economy, business, first) route: Route keyword to match sweet spots (e.g., "Japan", "Europe") currency: Cash price currency