Travel Brief

Travel Brief

Overview

This skill is the presentation layer: it re-runs the search itself under one fresh timestamp — rather than reformatting numbers quoted earlier in the conversation — and lays the results out the way a human travel agent would send them to a client: recommendation first, then a comparison table, then the price verdict, then the links, then the timestamp. Use travel-data-api for auth, base URL, and endpoint details, and prefer the hosted MCP tools when a client is configured. Both trip types carry buy_link, price_range_in_relation_to_other_periods, price_insights_low, and price_insights_high. The rest of the table is built from different keys per trip type: one-way items give price / price_as_number, airline, stops, duration, departure_description, and arrival_description; round-trip items give total_price / total_price_as_number, total_stops, total_duration_seconds, and per-leg fields such as departure_flight_airline, departure_flight_stops, departure_flight_duration, departure_flight_departure_description, and their return_flight_* counterparts. Hotel shortlist items from POST /search give name, price_string, price, review_score, review_count, room_type, location, image_url, and link; POST /hotel_by_name returns those for a single property plus available and nights.

Sources for a Brief

Flights host: google-flights-live-api.p.rapidapi.com. Hotels host: booking-live-api.p.rapidapi.com.

Workflow

1. Refetch, never reformat old data. If the results are more than a few minutes old, or came from an earlier message, run the search again. A brief is a document someone will act on, so it must carry a fresh fetch and the moment it happened.
2. Stamp the fetch time before you call, in UTC, and carry that one timestamp through the whole brief.
3. Pick the recommendation yourself. Choose one option and say why in one sentence — cheapest, shortest, non-stop, best value against the historical band. A list with no pick is not a brief.
4. Build the comparison table from at most 3–5 options, sorted client-side on price_as_number or total_price_as_number.
5. Read the verdict off the recommended item: price_range_in_relation_to_other_periods plus the price_insights_low–price_insights_high band, and put it in its own line.
6. Close with the links, the checked-at line, and the non-affiliation line.

Fetching the Brief's Data

Substitute your own key for YOUR_RAPIDAPI_KEY; nothing else needs editing.

export RAPIDAPI_KEY="YOUR_RAPIDAPI_KEY"
CHECKED_AT="$(date -u +'%Y-%m-%d %H:%M UTC')"

curl -sS -X POST 'https://google-flights-live-api.p.rapidapi.com/api/google_flights/roundtrip/v1' \
  -H "x-rapidapi-key: $RAPIDAPI_KEY" \
  -H 'x-rapidapi-host: google-flights-live-api.p.rapidapi.com' \
  -H 'Content-Type: application/json' \
  -d '{
        "from_airport": "BER",
        "to_airport": "CDG",
        "departure_date": "2026-11-12",
        "return_date": "2026-11-16",
        "currency": "USD",
        "limit": 5
      }'

printf '\nPrices checked at %s — fares go stale in minutes.\n' "$CHECKED_AT"

Refreshing a Brief Before You Send It

Re-run flights and the hotel line together, under one timestamp, right before the brief goes out. Two billed requests — say that before running it.

export RAPIDAPI_KEY="YOUR_RAPIDAPI_KEY"
CHECKED_AT="$(date -u +'%Y-%m-%d %H:%M UTC')"

curl -sS -X POST 'https://google-flights-live-api.p.rapidapi.com/api/google_flights/roundtrip/v1' \
  -H "x-rapidapi-key: $RAPIDAPI_KEY" \
  -H 'x-rapidapi-host: google-flights-live-api.p.rapidapi.com' \
  -H 'Content-Type: application/json' \
  -d '{"from_airport":"BER","to_airport":"CDG","departure_date":"2026-11-12","return_date":"2026-11-16","currency":"USD","limit":5}'

curl -sS -X POST 'https://booking-live-api.p.rapidapi.com/hotel_by_name' \
  -H "x-rapidapi-key: $RAPIDAPI_KEY" \
  -H 'x-rapidapi-host: booking-live-api.p.rapidapi.com' \
  -H 'Content-Type: application/json' \
  -d '{"hotel_name":"Hilton","area":"Paris","checkin_date":"2026-11-12","checkout_date":"2026-11-16","adults":2,"currency":"USD"}'

printf '\nPrices checked at %s — fares go stale in minutes.\n' "$CHECKED_AT"

On the hosted MCP, one user intent is one tool call: pass departure_date_from / departure_date_to and a list of destinations rather than looping a date at a time.

Common Pitfalls

• An empty array is not an error — but say which kind of empty it is. The flights endpoints return [] with HTTP 200. When X-Search-Status is ok or empty, write "no flights returned for this route and date" into the brief as a real finding, without retrying in a loop. When it is degraded, the search did not complete: that option is unchecked, not unavailable, and a brief that silently downgrades it to "no options" is telling the client something untrue.
• A sold-out hotel is available: false with null price fields, which is a valid answer from POST /hotel_by_name. Put it in the table as "sold out for these dates" rather than dropping the row silently — the client asked about that property.
• Never let API result order become the table order. sort_type is honoured on both endpoints, but a brief almost always merges several searches, and nothing sorts across them. Sort on price_as_number / total_price_as_number yourself, or the "cheapest" row in the brief will be wrong.
• use_fallback currently does nothing — it is accepted but selects a data source that is not switched on for this API. Before writing "no options exist", check X-Search-Status instead.
• Every combination is a billed request. One route × one date × one cabin × one passenger set = one request, and each hotel in the shortlist is another. Give the request count before rebuilding a brief, never after.
• Never rebuild a brief from prices quoted earlier in the conversation. Fares go stale in minutes; a reformatted old number reads as a live quote and is the one failure a client will notice.

Output Standards

• Fixed order, every time: recommendation → comparison table → price verdict → booking links → checked-at line → non-affiliation line. One sentence of recommendation, naming the option and the reason, before any table.
• Flight table columns: Option | Price | Airline | Stops | Duration | Departs / Arrives — filled from airline / stops / duration on one-way items and from the departure_flight_* and return_flight_* fields on round-trip items, one row per leg or a combined row, never by reading one-way key names off a round-trip item. Hotel table columns: Property | Price for stay | Review score (count) | Room type | Status. 3–5 rows maximum; mark the recommended row.
• The verdict gets its own line and uses the API's own words, not a guess: "$209 round-trip is typical for this route and period — Google's historical range here is $180–$260." If the verdict is high, say so even when it is the cheapest option found.
• Booking links go in full as buy_link (flights) and link (hotels). Never describe a link as a held, locked, or guaranteed fare, and never present the brief as a booking.
• Close with the literal line "Prices checked at YYYY-MM-DD HH:MM UTC — fares go stale in minutes." using the timestamp from the fetch, followed by: this brief uses an independent API that returns publicly available flight and hotel pricing; it is not affiliated with, endorsed by, or sponsored by Google or Booking.com.