Skip to main content
Glama

Stopover

Plan a multi-city trip

plan_trip
Idempotent

Plans 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

NameRequiredDescriptionDefault
homeYesWhere the trip starts, and ends unless end_at is set: a city name or airport code, like "Dallas" or "DFW".
modeNoWhat to optimize: cheapest (lowest total price), balanced (price and travel time, the default) or fastest.
citiesYesThe 2 to 7 cities to visit, as city names or airport codes, like ["Lisbon", "Madrid", "Paris"]. Any order unless fixed_order is true.
end_atNoWhere the trip finishes when it is not back home, like "Chicago" for a trip that starts in Dubai.
nightsNoNights in each city, as a range, like {"min": 2, "max": 4}. Without it the planner uses 2 to 4.
end_dateYesThe last day the trip may end (the day back home), YYYY-MM-DD.
flexibleNotrue (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_daysNoThe longest the whole trip may be, in days, when the window is wider than the trip should be. Only with flexible dates.
max_stopsNoThe most stops one flight may make: 0 for nonstop only, 1 or 2.
travelersNoHow many people travel together on the same flights, 1 to 9. Default 1. Prices are given per person and for the group.
must_be_inNoNights that must be spent in a given city, like a wedding in Paris on 2027-06-14: [{"city": "Paris", "date": "2027-06-14"}].
start_dateYesThe first day the trip may start, YYYY-MM-DD.
fixed_orderNotrue: visit the cities in the order listed, and only choose dates and flights. Default false, which lets the planner choose the order.
flights_onlyNotrue: 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_onlyNotrue: 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_airlinesNoAirlines not to fly, as names or two letter codes, like ["Ryanair", "W6"].
nights_by_cityNoNights for particular cities, overriding nights for those cities, like [{"city": "Paris", "min": 3, "max": 3}].
protected_onlyNotrue: only tickets sold as one booking, so a missed connection is the airline's problem. Leaves out self-transfer combinations. Default false.
max_layover_hoursNoThe longest layover allowed on a flight, in hours, 1 to 24.

Output Schema

NameRequiredDescriptionDefault
demoNo
legsNo
modeNo
notesNo
orderNo
staysNo
statusYes
messageNo
plan_idNo
end_dateNo
plan_urlNo
priced_atNo
travelersNo
fare_basisNo
start_dateNo
start_daysNo
alternativesNo
per_person_usdNo
group_total_usdNo
saving_vs_typed_order_usdNo
typed_order_per_person_usdNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing runtime (10 to 90 seconds), the ~200 second timeout behavior that returns a plan id, fare sources (Kiwi.com, Ryanair, recently seen fares), and that fares are estimates at time of display. It also clarifies the tool does not book, which complements destructiveHint=false and idempotentHint=true with concrete operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose and optimization behavior, then moves into runtime, data sources, and return contents in a logical order. It is dense but nearly every clause carries useful information; the return-value enumeration is long, though it largely duplicates the output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 19-parameter, nested-schema tool with an output schema, the description covers timing, sourcing, partial-result handling, and non-booking behavior. An agent has everything needed to call it correctly and to anticipate the response, including the asynchronous plan-id path.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so every parameter already carries its own description. The description reinforces a few semantics, such as the three optimization modes and that city order is free unless fixed_order is true, but it does not add meaning beyond what the schema already documents. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Plans a multi-city trip with Stopover') and immediately explains the core optimization: pricing every order of the cities to find the cheapest, balanced, or fastest itinerary. An agent can distinguish this from the sibling get_plan because the description notes that a plan still running comes back as an id to look up later.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for when this tool applies: a home city, 2 to 7 cities, and a date window, with explicit optimization modes. It also states 'Does not book anything', which tells the agent this is a planning step rather than a purchase. It stops short of an explicit when-not-to-use or a named hand-off to get_plan beyond the timeout case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources