Skip to main content
Glama

Search flights

search_flights
Read-onlyIdempotent

Searches live flights on Paytm and shows an interactive results card (airlines, logos, timings, stops, fares). Origin and destination are IATA codes (e.g. DEL, BOM, DXB) and dates are ISO (YYYY-MM-DD). A round trip uses trip_type='round_trip' with return_date. Filters: non_stop, airlines, max_price, time_slot, refundable; sort_by: best, cheapest or fastest. This is the tool for requests to show, find or list flights (e.g. 'cheapest flights next weekend', 'flights this Saturday', 'show me flights HYD to BLR'); fare_calendar on its own covers cheapest dates and lists no flights. It needs one concrete departure date: a relative date the traveller stated ('tomorrow', 'next Friday') resolves to YYYY-MM-DD for the call, and the traveller sees results only once the search runs. TIME WINDOWS: time_slot is one same-day bucket (early_morning 00:00-06:00, morning 06:00-12:00, afternoon 12:00-18:00, evening 18:00-24:00; there is no night slot) and applies to the OUTBOUND leg only. A narrower ask than a bucket ('between 6 and 9 am', 'after 9pm', 'around 6:30') maps to depart_after / depart_before (an hour or "HH:MM"; depart_before is exclusive, so 4-7 AM is 04:00 to 07:00). A window that crosses midnight is not one call. The RETURN leg of a round trip uses return_time_slot and return_depart_after / return_depart_before, so 'leave 6-9am, come back 7-10pm' is depart_after=6, depart_before=9, return_depart_after=19, return_depart_before=22. A bucket wider than a stated window is an approximation, and the traveller is told when one is used. AIRPORTS: results contain only the exact airports requested. Nearby-airport options (e.g. DXN Noida or HDO Hindon for DEL, NMI for BOM, AUH/SHJ for DXB) are excluded server-side and counted in search.excludedAlternateAirports, which matters when the traveller might want them; each flight is from the airport it actually uses, not from a nearby city. BUDGET: for a round trip, max_price is the COMBINED both-legs total, not per leg (search.maxPriceScope confirms which). Every applied filter is echoed under structured_content.search (timeSlot, returnTimeSlot, departAfter/Before, returnDepartAfter/Before, maxPrice, airlines, refundable), so whether a constraint was met, or could not be, is readable from the result. Invalid filter values are rejected with an error rather than silently ignored. Domestic round trips come back only as schedule-valid pairs (no overlap between legs, and ≥2 hours between onward arrival and return departure), to be compared on the traveller's preferences (price, airline, timing). International round trips come back as Paytm's pre-stitched combinations; free onward×return mixes are not valid itineraries. Refining the current results (morning/evening/afternoon departures, non-stop only, fastest, refundable) is a new search with the changed filters and the same route, date and passengers; cheaper dates come from fare_calendar. The card's suggestion chips send exactly such a request as a new turn, so a refine request is answered with new results rather than text suggestions or a pointer to the chips. For a short window (a weekend or a few days), the results card for one concrete date in that window (the Sunday or last day when none is preferred), sorted cheapest, is designed to appear above fare_calendar for the same window: search first, calendar second. Results carry summary fares only, without branded fare families or baggage/cancellation/reschedule policies. Those are keyed by the signed offerToken in this result: get_fare_family answers WHICH FARE to buy (fare families, Saver vs Flexi, what more money buys); get_flight_details answers POLICY (baggage, cancellation, reschedule rules).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
cabinNoeconomy | premium economy | business | first (default economy).economy
originYesDeparture IATA code, e.g. "DEL".
infantsNoNumber of infant travellers (default 0).
sort_byNobest | cheapest | fastest (default cheapest).cheapest
airlinesNoRestrict to these airline names or codes, e.g. ["IndiGo","6E"].
childrenNoNumber of child travellers (default 0).
non_stopNoOnly non-stop flights.
max_priceNoBudget cap in INR. For one_way this is the per-flight fare; for round_trip it is the COMBINED both-legs total.
time_slotNoOUTBOUND departure bucket: early_morning [00:00, 06:00) | morning [06:00, 12:00) | afternoon [12:00, 18:00) | evening [18:00, 24:00). Applies to the outbound leg only. "early morning" is accepted. "night" is rejected. An unrecognised value is rejected, not ignored.
trip_typeNo"one_way" or "round_trip" (round_trip needs return_date).one_way
passengersNoNumber of adult travellers (default 1).
refundableNoOnly refundable fares.
destinationYesArrival IATA code, e.g. "DXB".
return_dateNoReturn date YYYY-MM-DD (required for round_trip).
depart_afterNoEarliest outbound departure hour, e.g. 6 or "06:00" (inclusive). Use with depart_before for a narrow window that the coarse time_slot buckets cannot express.
depart_beforeNoExclusive end — "09:00" means the last acceptable departure is 08:59. 9 and "09:00" are the same instant. "09:30" keeps 09:15. A window whose end is earlier than its start is rejected; this search does not cross midnight.
departure_dateYesOutbound date as YYYY-MM-DD.
return_time_slotNoSame buckets, for the RETURN leg of a round trip. Omit to leave the return leg unfiltered by time.
return_depart_afterNoEarliest RETURN departure hour, e.g. "19:00".
return_depart_beforeNoLatest RETURN departure hour, exclusive.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
searchYes
flightsYes
currencyNoINR
followupsNo
sortRanksNo
disclaimerNo
flightPairsNo
moreFlightsNo
returnFlightsNo
serverProcessingMsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive behavior: nearby airports excluded server-side and counted in search.excludedAlternateAirports, invalid filter values rejected with an error, round-trip pair validity rules (no overlap, ≥2h buffer), international itineraries only as pre-stitched combos, and that every filter is echoed in structured_content.search.

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 purpose and filters before deep sections, and nearly every sentence carries actionable constraint detail (buckets, airports, budget, refinement). It is nonetheless very long and could be tightened, with some redundancy between the schema descriptions and the prose transport of the same rules.

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?

Output schema exists, so return values need not be restated; the description instead covers the complex behaviors an agent needs — date resolution, time-window mapping, airport exclusion, budget scope, and refinement semantics. Nothing material for correct invocation is missing.

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

Parameters5/5

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

Schema coverage is 100% (baseline 3), but the description adds real meaning beyond it: time_slot buckets with no night slot and outbound-only scope, depart_before exclusivity with worked examples, midnight-crossing rule, return-leg equivalents, and that max_price is the COMBINED both-legs total on round trips.

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+output: 'Searches live flights on Paytm and shows an interactive results card (airlines, logos, timings, stops, fares).' It explicitly claims the 'show/find/list flights' intent and distinguishes itself from fare_calendar, get_fare_family, and get_flight_details, so an agent can route without opening sibling schemas.

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

Usage Guidelines5/5

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

Gives trigger phrasing ('show me flights HYD to BLR'), an explicit exclusion ('fare_calendar on its own covers cheapest dates and lists no flights'), and named alternatives for fare-family and policy questions. It also states that refining results is a new search with changed filters, not a pointer to suggestion chips.

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