Skip to main content
Glama

Google Flights Search (Real-Time Fares)

by com.flightpowers

Search round-trip flights

search_roundtrip_flights
Read-only

Search real-time round-trip flights on Google Flights, priced as paired legs rather than two separate one-ways. Input: origin and destination IATA codes (destination may be a list), a departure date or range, and either a return date or a trip length in nights. Returns the total price for both legs, per-leg airline, stops and duration, and a single bookable buy_link for the trip.

Use it for any return-trip fare question. For a flexible search make ONE call: pass departure_date_from / departure_date_to for the outbound range and nights instead of return_date to compare trip lengths -- '5 to 7 nights in Rome sometime in May' is one call.

Requires the caller's own RapidAPI key. Each date/destination combination is one billed request; the count and the plan's remaining quota come back in api_usage.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum trips to return, after merging and sorting.
nightsNoTrip length in nights; a number, or a list like [5, 6, 7]. The return date is derived from each departure date.
sort_byNo"best", "price", or "duration". Applied across all results.best
currencyNoISO currency code, default "usd".usd
max_priceNoOnly return trips at or below this total price.
seat_typeNo1 economy, 2 premium economy, 3 business, 4 first.
passengersNoPassenger counts as [adults, children, infants].
to_airportYesDestination IATA code, or a list of them to compare.
return_dateNoFixed return date. Use this OR nights, not both.
from_airportYesOrigin IATA code, e.g. "TLV".
max_searchesNoCap the billed requests this call may make. Lower it to spend less of the plan's quota on a wide search; the range is then sampled evenly rather than cut short.
use_fallbackNoLeave unset. Switches the search to a second, independent flight data source instead of the usual Google Flights page read. Unset already escalates to that source once, automatically, after a search's retries have failed. true forces it inline on every attempt -- much slower, and it can time out. false disables it entirely, that automatic retry included.
departure_dateNoSingle outbound date, "YYYY-MM-DD".
max_return_stopsNoMaximum stops on the return leg.
departure_date_toNoLast date of an outbound range.
departure_date_fromNoFirst date of an outbound range.
max_departure_stopsNoMaximum stops on the outbound leg.
return_airline_codesNoRestrict the return leg to these airlines.
departure_airline_codesNoRestrict the outbound leg to these airlines.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
messageNoPresent when there is something the model must relay to the user rather than silently absorb -- no results, a degraded search, a missing key or a spent quota.
partialNoPresent when some searches failed but others succeeded. Plain text saying how much of the request the results cover.
resultsYesThe itineraries or properties found, already sorted and deduplicated. An empty array is only meaningful when search_status is 'empty'.
api_usageNoWhat this call cost the caller's own RapidAPI plan, and what remains on it. Present on every response that reached the upstream, including a degraded one -- a search that failed was still billed.
signup_urlNoWhere the caller subscribes or changes plan.
result_countNo
needs_api_keyNoTrue when no usable RapidAPI key arrived with the call, or the upstream rejected the one that did. No search was run and nothing was billed; signup_url and message say how to fix it.
search_statusNoWhether the underlying search actually completed, read from the backend's X-Search-Status header. 'ok': every combination searched returned results. 'empty': the search completed and Google genuinely has no itineraries for it -- a real answer, not a failure. 'partial': some combinations returned results and some failed, so the list is incomplete. 'degraded': every combination failed, so the search did not happen and an empty list means nothing; this case is also flagged with isError: true and is safe to retry.
quota_exhaustedNoTrue when the caller's RapidAPI plan has no requests left for the current period.
search_coverageNoWhat was actually searched. Present whether or not the request was truncated, so a model can state honestly what its answer rests on.

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the read-only annotation, the description discloses substantial behavioral context: the search is real-time, requires the caller's own RapidAPI key, each date/destination combination is one billed request, and quota details come back in api_usage. It also explains the output shape (total price, per-leg airline, stops, duration, buy_link), which adds real value beyond the annotations.

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

Conciseness5/5

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

The description is dense but every sentence earns its place: it front-loads the core purpose, then covers inputs/outputs, use-case guidance, flexible search pattern, and billing/auth requirements. There is no filler or redundant restating of the 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?

Given the high parameter count, the rich schema, and the presence of an output schema, the description covers all high-level calling needs: what the tool does, how to use ranges and nights, what the response contains, and the auth/billing implications. Nothing an agent needs to decide whether and how to call it is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the schema already documents all 19 parameters. The description adds meaningful combinatorial guidance not present in the schema, such as using departure_date_from/departure_date_to with nights for flexible one-call searches, and clarifying that destination may be a list. This lifts it above the baseline.

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 opens with a specific verb and resource: 'Search real-time round-trip flights on Google Flights'. It also distinguishes itself from the one-way sibling by explicitly framing the fare as 'priced as paired legs rather than two separate one-ways', so an agent can tell it apart from search_oneway_flights.

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: 'Use it for any return-trip fare question' and implies the exclusion of one-way searches. However, it never explicitly names the sibling tool as the alternative for one-way queries, so the routing guidance is strong but not fully explicit.

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

All Google Flights Search (Real-Time Fares) toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.7/5.0
Disambiguation5/5

The two tools are cleanly separated by trip type: one-way versus round-trip. Each has distinct input requirements and returns different pricing semantics, so there is no ambiguity about which tool to use for a given query.

Naming Consistency5/5

Both tools follow the exact same verb_noun pattern: search_<trip_type>_flights. The naming is predictable, symmetrical, and easy for an agent to reason about.

Tool Count4/5

Only two tools exist, which is slightly lean, but each one earns its place by covering a fundamental flight-search mode. The server is narrowly scoped to Google Flights fare searches, so the small count does not feel wasteful or cluttered.

Completeness4/5

One-way and round-trip searches cover the core fare-search lifecycle, and flexible date/destination inputs add substantial depth. The main gap is the lack of multi-city or more advanced trip-search modes, but that is a reasonable omission for the stated purpose.

Resources