aviasales-mcp

Overview Schema Source Related Servers Discussions Admin

search_flights

Read-onlyIdempotent

Find flight fares between two cities for a date or month, returning prices and booking links, with filters for direct flights, one-way, passengers, and departure times.

Instructions

Search flight prices between two cities on a date or across a month.

Use when the user names both ends of a route and wants fares, a booking link, or only departures inside a time window. For the cheapest day in a month use get_prices_calendar; for the days around dates already chosen use get_flexible_date_prices; for a budget with no destination use search_by_price_range.

Both codes must be IATA — call lookup_cities first if you only have a city name. For nearby airports use get_alternative_directions. A multi-city trip needs one call per leg.

Note on passengers: the price data comes from a cache of recent searches and is always PER ADULT in economy. The adults/children/infants/trip_class parameters are encoded into each ticket's booking_link, so the link opens Aviasales with the full party pre-filled and shows the real total price.

Durations: each ticket reports duration_total (full door-to-door travel time), duration_to/duration_back (pure flight time per direction) and layover_minutes (combined ground time between connecting flights; 0 for direct flights). All values are in minutes.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Max number of results (1-100, default 10).
`adults`	No	Number of adult passengers, 1-9 (default 1).
`direct`	No	If True, show only non-stop flights.
`market`	No	2-letter market whose price cache to read (e.g. "us", "ru", "th"). The same route in the same currency is priced differently per market, so set this to the traveller's country. Defaults to the server's configured market.
`origin`	Yes	Origin city IATA code (e.g. "MOW", "LED").
`infants`	No	Number of infants under 2, 0-8 (default 0). Cannot exceed the number of adults; the excess is trimmed.
`one_way`	No	If True, search one-way tickets only.
`children`	No	Number of children 2-11 years, 0-8 (default 0). Adults plus children cannot exceed 9; the excess is trimmed.
`currency`	No	Price currency code (3 letters, e.g. "rub", "usd"). Defaults to the server's configured currency.
`return_at`	No	Return date or month (YYYY-MM-DD or YYYY-MM). Optional.
`trip_class`	No	"economy", "comfort", "business" or "first" (default "economy").	economy
`destination`	Yes	Destination city IATA code (e.g. "IST", "BCN").
`depart_after`	No	Keep only flights departing at or after this local time ("HH:MM", 24-hour). Optional.
`departure_at`	No	Departure date or month (YYYY-MM-DD or YYYY-MM). Optional; a month searches every day in it.
`depart_before`	No	Keep only flights departing at or before this local time ("HH:MM", 24-hour). Optional. Combined with depart_after and set earlier than it, the window wraps midnight (e.g. 22:00-06:00).

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.5.3Oct 15, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description still adds non-obvious behaviour: prices come from a cache of recent searches, are always PER ADULT in economy, and the party size/trip class are only encoded into the booking_link. That is a genuine gotcha an agent would otherwise mis-handle. It stops short of describing result-paging or no-results behaviour.

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-loaded and well-paragraphed: purpose, then sibling routing, then prerequisites, then caveats. Slight redundancy in the closing 'Durations' paragraph, which explains return fields already covered by the output schema, but every other sentence drives a routing or invocation decision.

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?

For a 15-parameter, open-world search tool this is complete: routing, prerequisites, passenger/pricing semantics, and multi-leg handling are all covered. Safety is carried by annotations, parameter detail by a 100%-covered schema, and return shape by the output schema, so nothing an agent needs to call it correctly 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 baseline is 3, but the description adds real meaning beyond it: the passengers/trip_class parameters do NOT change the returned price, they only pre-fill the booking link and reveal the true total. The IATA-code constraint on origin/destination is also reinforced in prose. It adds semantics the schema's field descriptions do not convey.

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+scope: 'Search flight prices between two cities on a date or across a month.' It immediately distinguishes itself from four named siblings (get_prices_calendar, get_flexible_date_prices, search_by_price_range), so an agent can route without opening any schema.

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?

Explicit when-to-use ('user names both ends of a route and wants fares, a booking link, or only departures inside a time window') plus named alternatives with the exact condition that selects each. Prerequisites are also stated: both codes must be IATA, call lookup_cities first, one call per leg for multi-city, get_alternative_directions for nearby airports.

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

Deploy Server