Skip to main content
Glama

Search flights

mb_search_flights
Read-onlyIdempotent

Search bookable flights by origin, destination, and date, then compare fares, remaining seats, baggage, and schedules; filter by cabin, airline, direct routes, and departure time.

Instructions

Search flights for a date: every bookable flight with price, seats left, baggage and times.

price_toman is one adult's fare (taxes included); total_toman the whole party. Domestic round trips come back as two lists (outbound, return); international ones as packages priced for both ways. Unpriced flights are only counted in not_on_sale. Next: mb_flight_fare_details with the flight_id; to pick the day first, mb_flight_price_calendar.

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": {
      "origin": "<origin>",
      "destination": "<destination>",
      "date": "<date>"
    },
    "name": "mb_search_flights"
  }
}

Input Schema

NameRequiredDescriptionDefault
dateYesGregorian date YYYY-MM-DD.
sortNoOrder of the flights.cheapest
cabinNoCabin class filter.any
limitNoMax flights per list.
adultsNoAdults (12+).
originYesIATA airport or city code from mb_find_place(mode='flight'), e.g. 'THR', 'MHD', 'ISTALL' (all Istanbul airports).
infantsNoInfants (under 2).
airlinesNoOnly these airline codes, e.g. ['IR', 'W5'].
childrenNoChildren (2-11).
destinationYesIATA airport or city code from mb_find_place(mode='flight'), e.g. 'THR', 'MHD', 'ISTALL' (all Istanbul airports).
direct_onlyNoOnly flights without a connection.
return_dateNoReturn date YYYY-MM-DD; omit for one-way.
depart_afterNoLocal time HH:MM, e.g. '06:00'.
depart_beforeNoLocal time HH:MM, e.g. '06:00'.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed20 schema fields changedv0.5.0
    • removedInput schema / properties / airlines / anyOf
      Removed value: -[
      -  {
      -    "items": {
      -      "pattern": "^[A-Za-z0-9]{2,3}$",
      -      "type": "string"
      -    },
      -    "maxItems": 10,
      -    "type": "array"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • changedInput schema / properties / airlines / description
      Previous value: -"Only these airline codes, e.g. ['IR', 'W5'] (codes from results or mb_companies)."New value: +"Only these airline codes, e.g. ['IR', 'W5']."
    • addedInput schema / properties / airlines / items
      Added value: +{
      +  "pattern": "^[A-Za-z0-9]{2,3}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / airlines / maxItems
      Added value: +10
    • addedInput schema / properties / airlines / type
      Added value: +[
      +  "array",
      +  "null"
      +]
    • changedInput schema / properties / cabin / description
      Previous value: -"Cabin class filter (applied here; the API itself ignores it)."New value: +"Cabin class filter."
    • changedInput schema / properties / date / description
      Previous value: -"Gregorian date YYYY-MM-DD, e.g. '2026-10-20'."New value: +"Gregorian date YYYY-MM-DD."
    • removedInput schema / properties / depart_after / anyOf
      Removed value: -[
      -  {
      -    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / depart_after / pattern
      Added value: +"^([01]\\d|2[0-3]):[0-5]\\d$"
    • addedInput schema / properties / depart_after / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedInput schema / properties / depart_before / anyOf
      Removed value: -[
      -  {
      -    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedInput schema / properties / depart_before / pattern
      Added value: +"^([01]\\d|2[0-3]):[0-5]\\d$"
    • addedInput schema / properties / depart_before / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • changedInput schema / properties / destination / description
      Previous value: -"IATA airport or city code from mb_find_place(mode='flight'), e.g. 'THR', 'MHD', 'IKA' or 'ISTALL' (all Istanbul airports)."New value: +"IATA airport or city code from mb_find_place(mode='flight'), e.g. 'THR', 'MHD', 'ISTALL' (all Istanbul airports)."
    • changedInput schema / properties / origin / description
      Previous value: -"IATA airport or city code from mb_find_place(mode='flight'), e.g. 'THR', 'MHD', 'IKA' or 'ISTALL' (all Istanbul airports)."New value: +"IATA airport or city code from mb_find_place(mode='flight'), e.g. 'THR', 'MHD', 'ISTALL' (all Istanbul airports)."
    • removedInput schema / properties / return_date / anyOf
      Removed value: -[
      -  {
      -    "format": "date",
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • changedInput schema / properties / return_date / description
      Previous value: -"Return date YYYY-MM-DD for a round trip, e.g. '2026-10-23'; omit for one-way."New value: +"Return date YYYY-MM-DD; omit for one-way."
    • addedInput schema / properties / return_date / format
      Added value: +"date"
    • addedInput schema / properties / return_date / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedInput schema / title
      Removed value: -"mb_search_flightsArguments"
  2. Changed15 schema fields changedv0.3.0
    • removedInput schema / properties / adults / title
      Removed value: -"Adults"
    • removedInput schema / properties / airlines / title
      Removed value: -"Airlines"
    • removedInput schema / properties / cabin / title
      Removed value: -"Cabin"
    • removedInput schema / properties / children / title
      Removed value: -"Children"
    • removedInput schema / properties / date / title
      Removed value: -"Date"
    • removedInput schema / properties / depart_after / title
      Removed value: -"Depart After"
    • removedInput schema / properties / depart_before / title
      Removed value: -"Depart Before"
    • removedInput schema / properties / destination / title
      Removed value: -"Destination"
    • removedInput schema / properties / direct_only / title
      Removed value: -"Direct Only"
    • removedInput schema / properties / infants / title
      Removed value: -"Infants"
    • removedInput schema / properties / limit / title
      Removed value: -"Limit"
    • removedInput schema / properties / origin / title
      Removed value: -"Origin"
    • removedInput schema / properties / return_date / title
      Removed value: -"Return Date"
    • removedInput schema / properties / sort / title
      Removed value: -"Sort"
    • changedOutput schema / (root)
      Previous value: -{
      -  "additionalProperties": true,
      -  "title": "mb_search_flightsDictOutput",
      -  "type": "object"
      -}New value: +null
  3. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already declare a safe, idempotent, open-world read; the description goes well beyond them by explaining the pricing model (price_toman = one adult, taxes included; total_toman = whole party), that domestic round trips return two lists while international ones return packages priced for both directions, and that unpriced flights appear only in not_on_sale. These are exactly the non-obvious output behaviors an agent needs before calling.

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?

Purpose and return contents are front-loaded, followed by pricing semantics and next-step routing. Every sentence carries information, but the middle pricing block is dense and could be split for readability, so it stops short of a perfect score.

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 14 parameters and no output schema, the description does real work by sketching the response shape (two lists vs. packages, not_on_sale). It is nearly complete; the missing pieces are pagination/limit behavior and whether results are cached or live, which matter for an open-world search but are not critical.

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 origin/destination patterns, date formats, cabin and sort enums are fully documented in structured fields. The description adds modest semantic value by tying 'whole party' to the passenger parameters and clarifying what return_date produces, but says nothing about limit, direct_only, or the depart_after/depart_before window, so baseline 3 applies.

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?

Opens with a specific verb+resource and scope ('Search flights for a date') and enumerates what comes back: price, seats left, baggage, times. It is unmistakably the flight counterpart to mb_search_buses/mb_search_trains in the sibling list, so no schema comparison is needed to identify it.

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 explicit routing: call mb_flight_price_calendar first to pick the day, and mb_flight_fare_details afterwards with the returned flight_id. That is strong alternative/navigation guidance, though it never states when this tool should NOT be used (e.g. versus mb_alternative_routes) or prerequisites like obtaining codes from mb_find_place, which only the schema mentions.

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