Skip to main content
Glama

Route fares

route_fares
Read-only

Use this when someone asks about flights, flight prices, airfare or cheap plane tickets between two airports or cities (for example Seoul to Tokyo; find_airports turns a city into its airports). Returns the fares for one airport pair: the cheapest one-way, the cheapest round trip of a 3 to 21 day stay, a fare calendar of the cheapest one-way by departure date, the cheapest one-way in each month, and the cheapest round trips. A one-way may carry typical_price, the route's typical one-way fare, and pct_below_typical. When the pair has no fares yet, it looks the route up; if the fares are not back in time it answers status "pricing", and asking again a minute later reads them.

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": {
      "from": "<from>",
      "to": "<to>"
    },
    "name": "route_fares"
  }
}

Input Schema

NameRequiredDescriptionDefault
toYeswhere the flight lands: destination IATA airport code
fromYeswhere the flight leaves from: origin IATA airport code (an airport, not a city code)
monthNoYYYY-MM: keep only departure dates in that month

Output Schema

NameRequiredDescriptionDefault
toYes
fromYes
datesNothe cheapest one-way fares by departure date, cheapest first
monthsNothe cheapest one-way fare in each month
statusYesheld: fares below; pricing: the route is still being looked up, ask again in a minute; none: no fares for it yet
returnsNothe cheapest round trips, any stay, cheapest first
cheapestNothe cheapest one-way; absent when the pair has no dated one-way
currencyNo
page_urlYes
cheapest_returnNothe cheapest round trip of a 3 to 21 day stay; absent when the pair has none, and page_url then offers a return search

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed34 schema fields changed
    • changedOutput schema / properties / cheapest / description
      Previous value: -"the cheapest one-way; absent when we hold no dated one-way"New value: +"the cheapest one-way; absent when the pair has no dated one-way"
    • changedOutput schema / properties / cheapest / properties / book_url / description
      Previous value: -"opens the seller's booking page for this fare"New value: +"opens the seller's booking page for this fare, where the final price and bag fees appear at checkout"
    • changedOutput schema / properties / cheapest / properties / checked / description
      Previous value: -"the day we last checked this route — not the day the price was seen, which can be days earlier"New value: +"YYYY-MM-DD: the day this route was last checked; found_at, when present, is the day this fare was found"
    • addedOutput schema / properties / cheapest / properties / found_at
      Added value: +{
      +  "description": "YYYY-MM-DD: the day this fare was found; absent when only checked is known",
      +  "type": "string"
      +}
    • addedOutput schema / properties / cheapest / properties / pct_below_typical
      Added value: +{
      +  "description": "one-way only: how many percent this fare is under typical_price; present only when 10 or more",
      +  "type": "integer"
      +}
    • removedOutput schema / properties / cheapest / properties / seen
      Removed value: -{
      -  "description": "the day this price was seen; absent when we know only the day we last checked it",
      -  "type": "string"
      -}
    • addedOutput schema / properties / cheapest / properties / typical_price
      Added value: +{
      +  "description": "one-way only: the route's typical one-way fare, the median of each departure date's cheapest one-way, in currency",
      +  "type": "number"
      +}
    • changedOutput schema / properties / cheapest_return / description
      Previous value: -"the cheapest round trip of a 3 to 21 day stay; absent when we hold none, and page_url then offers a live return search"New value: +"the cheapest round trip of a 3 to 21 day stay; absent when the pair has none, and page_url then offers a return search"
    • changedOutput schema / properties / cheapest_return / properties / book_url / description
      Previous value: -"opens the seller's booking page for this fare"New value: +"opens the seller's booking page for this fare, where the final price and bag fees appear at checkout"
    • changedOutput schema / properties / cheapest_return / properties / checked / description
      Previous value: -"the day we last checked this route — not the day the price was seen, which can be days earlier"New value: +"YYYY-MM-DD: the day this route was last checked; found_at, when present, is the day this fare was found"
    • addedOutput schema / properties / cheapest_return / properties / found_at
      Added value: +{
      +  "description": "YYYY-MM-DD: the day this fare was found; absent when only checked is known",
      +  "type": "string"
      +}
    • addedOutput schema / properties / cheapest_return / properties / pct_below_typical
      Added value: +{
      +  "description": "one-way only: how many percent this fare is under typical_price; present only when 10 or more",
      +  "type": "integer"
      +}
    • removedOutput schema / properties / cheapest_return / properties / seen
      Removed value: -{
      -  "description": "the day this price was seen; absent when we know only the day we last checked it",
      -  "type": "string"
      -}
    • addedOutput schema / properties / cheapest_return / properties / typical_price
      Added value: +{
      +  "description": "one-way only: the route's typical one-way fare, the median of each departure date's cheapest one-way, in currency",
      +  "type": "number"
      +}
    • changedOutput schema / properties / dates / items / properties / book_url / description
      Previous value: -"opens the seller's booking page for this fare"New value: +"opens the seller's booking page for this fare, where the final price and bag fees appear at checkout"
    • changedOutput schema / properties / dates / items / properties / checked / description
      Previous value: -"the day we last checked this route — not the day the price was seen, which can be days earlier"New value: +"YYYY-MM-DD: the day this route was last checked; found_at, when present, is the day this fare was found"
    • addedOutput schema / properties / dates / items / properties / found_at
      Added value: +{
      +  "description": "YYYY-MM-DD: the day this fare was found; absent when only checked is known",
      +  "type": "string"
      +}
    • addedOutput schema / properties / dates / items / properties / pct_below_typical
      Added value: +{
      +  "description": "one-way only: how many percent this fare is under typical_price; present only when 10 or more",
      +  "type": "integer"
      +}
    • removedOutput schema / properties / dates / items / properties / seen
      Removed value: -{
      -  "description": "the day this price was seen; absent when we know only the day we last checked it",
      -  "type": "string"
      -}
    • addedOutput schema / properties / dates / items / properties / typical_price
      Added value: +{
      +  "description": "one-way only: the route's typical one-way fare, the median of each departure date's cheapest one-way, in currency",
      +  "type": "number"
      +}
    • changedOutput schema / properties / months / items / properties / book_url / description
      Previous value: -"opens the seller's booking page for this fare"New value: +"opens the seller's booking page for this fare, where the final price and bag fees appear at checkout"
    • changedOutput schema / properties / months / items / properties / checked / description
      Previous value: -"the day we last checked this route — not the day the price was seen, which can be days earlier"New value: +"YYYY-MM-DD: the day this route was last checked; found_at, when present, is the day this fare was found"
    • addedOutput schema / properties / months / items / properties / found_at
      Added value: +{
      +  "description": "YYYY-MM-DD: the day this fare was found; absent when only checked is known",
      +  "type": "string"
      +}
    • addedOutput schema / properties / months / items / properties / pct_below_typical
      Added value: +{
      +  "description": "one-way only: how many percent this fare is under typical_price; present only when 10 or more",
      +  "type": "integer"
      +}
    • removedOutput schema / properties / months / items / properties / seen
      Removed value: -{
      -  "description": "the day this price was seen; absent when we know only the day we last checked it",
      -  "type": "string"
      -}
    • addedOutput schema / properties / months / items / properties / typical_price
      Added value: +{
      +  "description": "one-way only: the route's typical one-way fare, the median of each departure date's cheapest one-way, in currency",
      +  "type": "number"
      +}
    • changedOutput schema / properties / returns / description
      Previous value: -"the cheapest round trips held, any stay, cheapest first"New value: +"the cheapest round trips, any stay, cheapest first"
    • changedOutput schema / properties / returns / items / properties / book_url / description
      Previous value: -"opens the seller's booking page for this fare"New value: +"opens the seller's booking page for this fare, where the final price and bag fees appear at checkout"
    • changedOutput schema / properties / returns / items / properties / checked / description
      Previous value: -"the day we last checked this route — not the day the price was seen, which can be days earlier"New value: +"YYYY-MM-DD: the day this route was last checked; found_at, when present, is the day this fare was found"
    • addedOutput schema / properties / returns / items / properties / found_at
      Added value: +{
      +  "description": "YYYY-MM-DD: the day this fare was found; absent when only checked is known",
      +  "type": "string"
      +}
    • addedOutput schema / properties / returns / items / properties / pct_below_typical
      Added value: +{
      +  "description": "one-way only: how many percent this fare is under typical_price; present only when 10 or more",
      +  "type": "integer"
      +}
    • removedOutput schema / properties / returns / items / properties / seen
      Removed value: -{
      -  "description": "the day this price was seen; absent when we know only the day we last checked it",
      -  "type": "string"
      -}
    • addedOutput schema / properties / returns / items / properties / typical_price
      Added value: +{
      +  "description": "one-way only: the route's typical one-way fare, the median of each departure date's cheapest one-way, in currency",
      +  "type": "number"
      +}
    • changedOutput schema / properties / status / description
      Previous value: -"held: fares below; pricing: the route is still being looked up, ask again in a minute; none: we hold no fare for it"New value: +"held: fares below; pricing: the route is still being looked up, ask again in a minute; none: no fares for it yet"
  2. Changed2 schema fields changed
    • changedInput schema / properties / from / description
      Previous value: -"origin IATA airport code (an airport, not a city code)"New value: +"where the flight leaves from: origin IATA airport code (an airport, not a city code)"
    • changedInput schema / properties / to / description
      Previous value: -"destination IATA airport code"New value: +"where the flight lands: destination IATA airport code"
  3. Changed1 schema field changed
    • changedOutput schema / properties / status / description
      Previous value: -"held: fares below; pricing: we just started pricing this route, ask again in a minute; none: we hold no fare for it"New value: +"held: fares below; pricing: the route is still being looked up, ask again in a minute; none: we hold no fare for it"
  4. Changed10 schema fields changed
    • changedOutput schema / properties / cheapest / properties / checked / description
      Previous value: -"the day this price was last seen"New value: +"the day we last checked this route — not the day the price was seen, which can be days earlier"
    • addedOutput schema / properties / cheapest / properties / seen
      Added value: +{
      +  "description": "the day this price was seen; absent when we know only the day we last checked it",
      +  "type": "string"
      +}
    • changedOutput schema / properties / cheapest_return / properties / checked / description
      Previous value: -"the day this price was last seen"New value: +"the day we last checked this route — not the day the price was seen, which can be days earlier"
    • addedOutput schema / properties / cheapest_return / properties / seen
      Added value: +{
      +  "description": "the day this price was seen; absent when we know only the day we last checked it",
      +  "type": "string"
      +}
    • changedOutput schema / properties / dates / items / properties / checked / description
      Previous value: -"the day this price was last seen"New value: +"the day we last checked this route — not the day the price was seen, which can be days earlier"
    • addedOutput schema / properties / dates / items / properties / seen
      Added value: +{
      +  "description": "the day this price was seen; absent when we know only the day we last checked it",
      +  "type": "string"
      +}
    • changedOutput schema / properties / months / items / properties / checked / description
      Previous value: -"the day this price was last seen"New value: +"the day we last checked this route — not the day the price was seen, which can be days earlier"
    • addedOutput schema / properties / months / items / properties / seen
      Added value: +{
      +  "description": "the day this price was seen; absent when we know only the day we last checked it",
      +  "type": "string"
      +}
    • changedOutput schema / properties / returns / items / properties / checked / description
      Previous value: -"the day this price was last seen"New value: +"the day we last checked this route — not the day the price was seen, which can be days earlier"
    • addedOutput schema / properties / returns / items / properties / seen
      Added value: +{
      +  "description": "the day this price was seen; absent when we know only the day we last checked it",
      +  "type": "string"
      +}
  5. Changed1 schema field changed
    • changedOutput schema / properties / cheapest / description
      Previous value: -"the cheapest one-way"New value: +"the cheapest one-way; absent when we hold no dated one-way"
  6. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Beyond the annotations it discloses the non-obvious behavior that matters: the call has a lazy lookup side effect when a pair has no fares yet, and it can return status 'pricing' asynchronously, with the instruction to re-ask a minute later. This explains why idempotentHint is false and tells the agent how to handle the intermediate state, which the structured fields do not convey.

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?

The trigger and prerequisites are front-loaded and the sentences are dense rather than padded. The mid-section enumerating return shapes is somewhat redundant given an output schema exists, but it is compact and readable.

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

Completeness4/5

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

For a read-only tool with full schema coverage, annotations, and an output schema, the description covers the essentials including the async 'pricing' state. Minor gaps remain, such as whether fares are per passenger and in what currency, and how many round-trip options are returned.

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 the schema already defines from, to, and month, including the airport-not-city-code restriction that the description merely echoes. The description adds no detail on the month filter syntax or its interaction with the fare calendar, so this is baseline territory.

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?

The description names a specific verb and resource ('Returns the fares for one airport pair') and enumerates the exact fare shapes returned: cheapest one-way, cheapest round trip of a 3-21 day stay, fare calendar, monthly cheapest, and cheapest round trips. It also distinguishes itself from the sibling find_airports by assigning that tool the city-to-airport conversion role.

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?

It gives an explicit trigger set ('when someone asks about flights, flight prices, airfare or cheap plane tickets') plus a worked example and the prerequisite chain via find_airports. It stops short of saying when not to use it (e.g., multi-city itineraries or one-way-only searches), so it is clear but not exclusionary.

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