Plan a multi-city trip
plan_tripPlans a multi-city trip with Stopover. Given a home city, 2 to 7 cities to visit and a date window, it prices every order of the cities and finds the one that costs least (or balances price and travel time, or is fastest), with the dates and the flight or train for each leg. Fares come from free sources (Kiwi.com, Ryanair and recently seen fares) and are estimates at the time shown. Takes about 10 to 90 seconds. Returns the recommended order and dates, the nights in each city, the total per person in USD and how each fare was priced, the saving against the order the cities were listed in, other orders with their prices, each leg with booking links, and a link to the full plan on flystopover.com. A plan still running after about 200 seconds comes back as a plan id to look up later. Does not book anything.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"home": "<home>",
"cities": "<cities>",
"start_date": "<start_date>",
"end_date": "<end_date>"
},
"name": "plan_trip"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| home | Yes | Where the trip starts, and ends unless end_at is set: a city name or airport code, like "Dallas" or "DFW". | |
| mode | No | What to optimize: cheapest (lowest total price), balanced (price and travel time, the default) or fastest. | |
| cities | Yes | The 2 to 7 cities to visit, as city names or airport codes, like ["Lisbon", "Madrid", "Paris"]. Any order unless fixed_order is true. | |
| end_at | No | Where the trip finishes when it is not back home, like "Chicago" for a trip that starts in Dubai. | |
| nights | No | Nights in each city, as a range, like {"min": 2, "max": 4}. Without it the planner uses 2 to 4. | |
| end_date | Yes | The last day the trip may end (the day back home), YYYY-MM-DD. | |
| flexible | No | true (the default): the trip may start and end on any days inside the window, chosen for price. false: leave on start_date and come back on end_date exactly. | |
| max_days | No | The longest the whole trip may be, in days, when the window is wider than the trip should be. Only with flexible dates. | |
| max_stops | No | The most stops one flight may make: 0 for nonstop only, 1 or 2. | |
| travelers | No | How many people travel together on the same flights, 1 to 9. Default 1. Prices are given per person and for the group. | |
| must_be_in | No | Nights that must be spent in a given city, like a wedding in Paris on 2027-06-14: [{"city": "Paris", "date": "2027-06-14"}]. | |
| start_date | Yes | The first day the trip may start, YYYY-MM-DD. | |
| fixed_order | No | true: visit the cities in the order listed, and only choose dates and flights. Default false, which lets the planner choose the order. | |
| flights_only | No | true: flights only, no trains or buses between cities. Default false, which lets a train or bus take a leg when it is the better buy. | |
| airlines_only | No | true: book with airlines only. Leaves out fares sold by booking sites like Kiwi.com, so every ticket is bought from the airline and no link goes to a booking site. Default false. | |
| avoid_airlines | No | Airlines not to fly, as names or two letter codes, like ["Ryanair", "W6"]. | |
| nights_by_city | No | Nights for particular cities, overriding nights for those cities, like [{"city": "Paris", "min": 3, "max": 3}]. | |
| protected_only | No | true: only tickets sold as one booking, so a missed connection is the airline's problem. Leaves out self-transfer combinations. Default false. | |
| max_layover_hours | No | The longest layover allowed on a flight, in hours, 1 to 24. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| demo | No | ||
| legs | No | ||
| mode | No | ||
| notes | No | ||
| order | No | ||
| stays | No | ||
| status | Yes | ||
| message | No | ||
| plan_id | No | ||
| end_date | No | ||
| plan_url | No | ||
| priced_at | No | ||
| travelers | No | ||
| fare_basis | No | ||
| start_date | No | ||
| start_days | No | ||
| alternatives | No | ||
| per_person_usd | No | ||
| group_total_usd | No | ||
| saving_vs_typed_order_usd | No | ||
| typed_order_per_person_usd | No |