Skip to main content
Glama

search_deals

Read-onlyIdempotent

Search the flight fares Sparkflights has found, ranked by cost per mile against each market's limit. Each deal shows when its price was last checked, and prices can change after that; an empty result means Sparkflights has no fare that matches, not that no flights exist. Each deal has the price text of its Sparkflights fare page; url, the fare page; route_url, the route page, which lists the route's fares and price history; and feed_url, the route's JSON feed of new fares. A search naming an origin or destination also returns fares when its deals are fewer than limit: the lowest fares Sparkflights has seen for that place, each with its price, dates, airline, seen_at (when it was seen) and route_url, its route page. A fare has no id or fare page yet.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_deals"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNoSort order: cpm (default; cost per mile against its market's CPM ceiling, lowest first) or recent (newest first; newest is the same)
cabinNoCabin classes, one or more of: economy, premium_economy, business, first
limitNoMax results, 1-25. Default 10.
originNoWhere the trip starts: an IATA airport code (JFK) for that airport, or a city for every airport the city's route pages cover: its name (New York), a metro code (NYC), or its name with its country or state (London, UK; Portland, Oregon)
low_costNotrue returns only budget/low-cost carrier deals; overrides include_budget
max_priceNoUS dollars: only deals listed at or under this price
destinationNoWhere the trip goes: an IATA airport code (NRT) for that airport, or a city for every airport the city's route pages cover: its name (Tokyo), a metro code (TYO), or its name with its country or state (London, UK; Portland, Maine)
depart_monthNoYYYY-MM, for example 2026-12: only deals whose first departure date is in that month
origin_regionNoDeparture regions, one or more of: africa, asia, caribbean, europe, north_america, oceania, south_america. Default: the regions the deal board lists, or every region when origin is given
include_budgetNoAdd budget/low-cost carrier deals (Spirit, Frontier, etc.) to the others. Default false — budget deals are on /flights/budget.
destination_regionNoDestination regions, one or more of: africa, asia, caribbean, europe, north_america, oceania, south_america

Output Schema

NameRequiredDescriptionDefault
dealsNo
errorNo
faresNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "description": "The deals the card shows, the route fares sighted without a deal page, or an error.",
      +  "properties": {
      +    "deals": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "airline": {
      +            "type": "string"
      +          },
      +          "cabin_class": {
      +            "type": "string"
      +          },
      +          "date_options": {
      +            "items": {
      +              "additionalProperties": false,
      +              "properties": {
      +                "price_usd": {
      +                  "type": "number"
      +                },
      +                "return_date": {
      +                  "type": "string"
      +                },
      +                "start_date": {
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "start_date",
      +                "price_usd"
      +              ],
      +              "type": "object"
      +            },
      +            "type": "array"
      +          },
      +          "destination": {
      +            "type": "string"
      +          },
      +          "destination_city": {
      +            "type": "string"
      +          },
      +          "destination_image_url": {
      +            "type": "string"
      +          },
      +          "id": {
      +            "type": "integer"
      +          },
      +          "origin": {
      +            "type": "string"
      +          },
      +          "origin_city": {
      +            "type": "string"
      +          },
      +          "photo_credit": {
      +            "additionalProperties": false,
      +            "properties": {
      +              "photographer": {
      +                "type": "string"
      +              },
      +              "photographer_url": {
      +                "type": "string"
      +              },
      +              "unsplash_url": {
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "photographer",
      +              "photographer_url",
      +              "unsplash_url"
      +            ],
      +            "type": "object"
      +          },
      +          "price_panel": {
      +            "additionalProperties": false,
      +            "properties": {
      +              "airline_direct": {
      +                "type": "string"
      +              },
      +              "checked_at": {
      +                "format": "date-time",
      +                "type": "string"
      +              },
      +              "cost_per_mile": {
      +                "type": "string"
      +              },
      +              "departs": {
      +                "type": "string"
      +              },
      +              "fare_brand": {
      +                "type": "string"
      +              },
      +              "local_price": {
      +                "type": "string"
      +              },
      +              "lower_cabin": {
      +                "type": "string"
      +              },
      +              "price": {
      +                "type": "string"
      +              },
      +              "returns": {
      +                "type": "string"
      +              },
      +              "seller": {
      +                "type": "string"
      +              },
      +              "seller_type": {
      +                "type": "string"
      +              },
      +              "ticketing_note": {
      +                "type": "string"
      +              },
      +              "trip": {
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "price",
      +              "trip"
      +            ],
      +            "type": "object"
      +          },
      +          "route_url": {
      +            "type": "string"
      +          },
      +          "url": {
      +            "type": "string"
      +          },
      +          "verified_at": {
      +            "format": "date-time",
      +            "type": "string"
      +          },
      +          "watch_url": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "id",
      +          "url",
      +          "origin",
      +          "origin_city",
      +          "destination",
      +          "destination_city",
      +          "airline",
      +          "cabin_class",
      +          "price_panel"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "error": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "code": {
      +          "type": "string"
      +        },
      +        "message": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "code",
      +        "message"
      +      ],
      +      "type": "object"
      +    },
      +    "fares": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "airline": {
      +            "type": "string"
      +          },
      +          "cabin_class": {
      +            "type": "string"
      +          },
      +          "cost_per_mile": {
      +            "type": "number"
      +          },
      +          "depart_date": {
      +            "type": "string"
      +          },
      +          "destination": {
      +            "type": "string"
      +          },
      +          "destination_city": {
      +            "type": "string"
      +          },
      +          "low_cost": {
      +            "type": "boolean"
      +          },
      +          "origin": {
      +            "type": "string"
      +          },
      +          "origin_city": {
      +            "type": "string"
      +          },
      +          "price_usd": {
      +            "type": "number"
      +          },
      +          "return_date": {
      +            "type": "string"
      +          },
      +          "route_url": {
      +            "type": "string"
      +          },
      +          "seen_at": {
      +            "format": "date-time",
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "route_url",
      +          "origin",
      +          "origin_city",
      +          "destination",
      +          "destination_city",
      +          "price_usd",
      +          "cabin_class",
      +          "low_cost",
      +          "cost_per_mile",
      +          "seen_at"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Changed4 schema fields changed
    • changedInput schema / properties / destination_region / description
      Previous value: -"Destination regions, one or more of: africa, asia, europe, north_america, oceania, south_america"New value: +"Destination regions, one or more of: africa, asia, caribbean, europe, north_america, oceania, south_america"
    • changedInput schema / properties / destination_region / items / enum
      Previous value: -[
      -  "africa",
      -  "asia",
      -  "europe",
      -  "north_america",
      -  "oceania",
      -  "south_america"
      -]New value: +[
      +  "africa",
      +  "asia",
      +  "caribbean",
      +  "europe",
      +  "north_america",
      +  "oceania",
      +  "south_america"
      +]
    • changedInput schema / properties / origin_region / description
      Previous value: -"Departure regions, one or more of: africa, asia, europe, north_america, oceania, south_america. Default: the regions the deal board lists, or every region when origin is given"New value: +"Departure regions, one or more of: africa, asia, caribbean, europe, north_america, oceania, south_america. Default: the regions the deal board lists, or every region when origin is given"
    • changedInput schema / properties / origin_region / items / enum
      Previous value: -[
      -  "africa",
      -  "asia",
      -  "europe",
      -  "north_america",
      -  "oceania",
      -  "south_america"
      -]New value: +[
      +  "africa",
      +  "asia",
      +  "caribbean",
      +  "europe",
      +  "north_america",
      +  "oceania",
      +  "south_america"
      +]
  3. Changed11 schema fields changed
    • changedInput schema / properties / cabin / description
      Previous value: -"Cabin class, or a comma-separated list: economy, premium_economy, business, first"New value: +"Cabin classes, one or more of: economy, premium_economy, business, first"
    • addedInput schema / properties / cabin / items
      Added value: +{
      +  "enum": [
      +    "economy",
      +    "premium_economy",
      +    "business",
      +    "first"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / cabin / type
      Previous value: -"string"New value: +"array"
    • changedInput schema / properties / destination / description
      Previous value: -"Where the trip goes: an IATA airport code (NRT) for that airport, or a city (Tokyo, london) for every airport the city's route pages cover. Not a metro code such as NYC or LON"New value: +"Where the trip goes: an IATA airport code (NRT) for that airport, or a city for every airport the city's route pages cover: its name (Tokyo), a metro code (TYO), or its name with its country or state (London, UK; Portland, Maine)"
    • changedInput schema / properties / destination_region / description
      Previous value: -"Destination region, or a comma-separated list: africa, asia, europe, north_america, oceania, south_america"New value: +"Destination regions, one or more of: africa, asia, europe, north_america, oceania, south_america"
    • addedInput schema / properties / destination_region / items
      Added value: +{
      +  "enum": [
      +    "africa",
      +    "asia",
      +    "europe",
      +    "north_america",
      +    "oceania",
      +    "south_america"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / destination_region / type
      Previous value: -"string"New value: +"array"
    • changedInput schema / properties / origin / description
      Previous value: -"Where the trip starts: an IATA airport code (JFK) for that airport, or a city (New York, new-york-city) for every airport the city's route pages cover. Not a metro code such as NYC or LON"New value: +"Where the trip starts: an IATA airport code (JFK) for that airport, or a city for every airport the city's route pages cover: its name (New York), a metro code (NYC), or its name with its country or state (London, UK; Portland, Oregon)"
    • changedInput schema / properties / origin_region / description
      Previous value: -"Departure region, or a comma-separated list: africa, asia, europe, north_america, oceania, south_america. Default: the regions the deal board lists, or every region when origin is given"New value: +"Departure regions, one or more of: africa, asia, europe, north_america, oceania, south_america. Default: the regions the deal board lists, or every region when origin is given"
    • addedInput schema / properties / origin_region / items
      Added value: +{
      +  "enum": [
      +    "africa",
      +    "asia",
      +    "europe",
      +    "north_america",
      +    "oceania",
      +    "south_america"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / origin_region / type
      Previous value: -"string"New value: +"array"
  4. Changed3 schema fields changed
    • changedInput schema / properties / limit / type
      Previous value: -"number"New value: +"integer"
    • changedInput schema / properties / sort / description
      Previous value: -"Sort order: cpm (default; cost per mile against its market's CPM ceiling, lowest first) or recent (newest first)"New value: +"Sort order: cpm (default; cost per mile against its market's CPM ceiling, lowest first) or recent (newest first; newest is the same)"
    • changedInput schema / properties / sort / enum
      Previous value: -[
      -  "cpm",
      -  "recent"
      -]New value: +[
      +  "cpm",
      +  "recent",
      +  "newest"
      +]
  5. Changed8 schema fields changed
    • changedInput schema / properties / depart_month / description
      Previous value: -"YYYY-MM: only deals whose first departure date is in that month"New value: +"YYYY-MM, for example 2026-12: only deals whose first departure date is in that month"
    • addedInput schema / properties / depart_month / pattern
      Added value: +"^[0-9]{4}-(0[1-9]|1[0-2])$"
    • changedInput schema / properties / destination / description
      Previous value: -"Where the trip goes: an IATA airport code (NRT) for that airport, or a city (Tokyo, london) for every airport the city's route pages cover"New value: +"Where the trip goes: an IATA airport code (NRT) for that airport, or a city (Tokyo, london) for every airport the city's route pages cover. Not a metro code such as NYC or LON"
    • changedInput schema / properties / destination_region / description
      Previous value: -"Destination region, or a comma-separated list: north_america, europe, asia, africa, oceania, south_america"New value: +"Destination region, or a comma-separated list: africa, asia, europe, north_america, oceania, south_america"
    • changedInput schema / properties / origin / description
      Previous value: -"Where the trip starts: an IATA airport code (JFK) for that airport, or a city (New York, new-york-city) for every airport the city's route pages cover"New value: +"Where the trip starts: an IATA airport code (JFK) for that airport, or a city (New York, new-york-city) for every airport the city's route pages cover. Not a metro code such as NYC or LON"
    • changedInput schema / properties / origin_region / description
      Previous value: -"Departure region, or a comma-separated list, same values as destination_region. Default: the regions the deal board lists"New value: +"Departure region, or a comma-separated list: africa, asia, europe, north_america, oceania, south_america. Default: the regions the deal board lists, or every region when origin is given"
    • addedInput schema / properties / sort / enum
      Added value: +[
      +  "cpm",
      +  "recent"
      +]
    • addedInput schema / required
      Added value: +[]
  6. First observed

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already establish readOnly/idempotent/no-open-world safety, but the description adds genuinely non-obvious behavior: prices are timestamped and can change, an empty result means no matching fare rather than no flights, and named-place searches silently return a second class of lower-confidence fares with no id or fare page. That last point is important context an agent would otherwise misread as a deal.

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

Conciseness3/5

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

The purpose and the empty-result caveat are front-loaded well, but the middle sentence enumerating url, route_url and feed_url is a dense, semicolon-heavy field dump that largely restates the output schema. Roughly a third of the text could be cut without losing selection-relevant information.

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?

With an output schema and full annotation coverage, the description carries only the semantic load, and it does that well: staleness, empty-result interpretation, and the two-tier result behavior are all disclosed. The main gap is that it never positions the tool against get_deal or watch_route.

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 description coverage is 100%, so all 11 parameters are already documented with enums, defaults and formats. The description adds only marginal meaning, mainly tying the cpm default to the market CPM ceiling and explaining that limit also governs the fallback fare list; it does not clarify the region-filter defaults beyond what the schema says.

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

Purpose4/5

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

The description opens with a specific verb and resource ("Search the flight fares Sparkflights has found") and adds a ranking rule (cost per mile against each market's limit), so the agent knows exactly what this returns. It never names or contrasts with siblings get_deal or watch_route, so it falls short of full sibling differentiation.

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

Usage Guidelines3/5

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

Usage context is implied rather than stated: the note that an empty result means no matching fare, and the fallback that naming an origin or destination also returns lowest-seen fares when deals are fewer than limit, tells the agent how to interpret output but not when to pick this over get_deal. No explicit when-not or alternative routing is given.

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.