Skip to main content
Glama
negm17111995

MAQAMI Travel

by negm17111995
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Search flights

post_flights_rates
Read-only

Overview

Instructions

Overview

Search for available flights with real-time pricing from multiple providers. The itinerary must be sent as a non-empty legs array. Each leg follows the provider SearchLeg shape: required origin, destination, and date (YYYY-MM-DD); optional direction (OUTBOUND or INBOUND); optional per-leg filters that override global filters for that leg only.

Not supported: top-level origin, destination, departureDate, or returnDate — use legs only.

When to Use

  • Listings — live prices for search results UI

  • One-way, round-trip, or multi-city — one leg per segment, in order

  • Filtering — cabin class, stops, price, refundability, times (globally or per leg)

What You Get

  • Offers from multiple providers

  • Itineraries with segments, layovers, and durations

  • Price breakdown (fares, taxes, fees) and baggage hints

Key Features

  • Multi-provider aggregation in one request

  • Global filters, sort

Quick Start

Required: legs (at least one object with origin, destination, date), adults (≥ 1), currency

Date limit: each leg date must not be more than 11 months from today.

Round-trip: two legs (e.g. outbound then return with direction OUTBOUND / INBOUND). One-way: one leg.

Booking

The response includes searchUrl, the same search on book.maqami.co. Flights are booked and paid only on MAQAMI's website: post_flights_verify re-prices the chosen offer and returns its checkoutUrl.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
legsYesOrdered itinerary legs (provider SearchLeg). One-way: one entry. Round-trip: outbound then inbound. Multi-city / open-jaw: additional legs in travel order.
sortNoSort options for results
adultsYesNumber of adults (12+)
countryNoOptional ISO 3166-1 alpha-2 country code for point of sale
filtersNoOptional filters to refine search results
infantsNoNumber of infants (<2)
childrenNoNumber of children (2-11)
currencyYesISO 4217 currency code
cabinClassNoCabin class (provider SearchFilters codes only). Same enum as filters.cabinClass.
infantAgesNoAge of each infant (under 2, per IATA). Length must equal infants count. Optional — omit if ages are not relevant.
childrenAgesNoAge of each child (2–11 inclusive, per IATA). Length must equal children count. Optional — omit if ages are not relevant.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv1.0.10
    • addedInput schema / properties / filters / properties / excludeAirlines
      Added value: +{
+  "description": "Exclude airlines (2-character IATA airline codes, case-insensitive): a journey is removed when any of its flights is marketed or operated by one of them (codeshares included), and an offer is removed when one of them is its validating (ticketing) carrier. A leg's own filters.excludeAirlines replaces this list on that leg. Airlines excluded on your account are always excluded in addition to this list.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • changedInput schema / properties / legs / items / properties / date / description
      Previous value: -"Departure date for this leg (YYYY-MM-DD)"New value: +"Departure date for this leg (YYYY-MM-DD). Must not be more than 11 months from today."
    • addedInput schema / properties / legs / items / properties / filters / properties / excludeAirlines
      Added value: +{
+  "description": "Exclude airlines on this leg only (2-character IATA airline codes, case-insensitive): a journey is removed when a flight on this leg is marketed or operated by one of them. Replaces the top-level filters.excludeAirlines on this leg; airlines excluded on your account are always excluded.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / legs / items / properties / filters / properties / excludeConnectionAirports / description
      Added value: +"Exclude layovers at these airports (e.g. IST, DOH)"
    • addedInput schema / properties / legs / items / properties / filters / properties / excludeOvernight / description
      Added value: +"Exclude red-eye flights and overnight layovers"
    • addedInput schema / properties / legs / items / properties / filters / properties / flightNumbers / description
      Added value: +"Filter by flight numbers (e.g. SK500, AF123)"
  2. Changed2 schema fields changedv1.0.6
    • changedInput schema / properties / filters / properties / maxStops / description
      Previous value: -"Maximum number of stops: -1 or omit = any, 0 = nonstop, 1 = 1 or fewer, 2 = 2 or fewer"New value: +"Maximum number of stops: -1 or omit = any, 0 = genuinely non-stop, 1 = 1 or fewer, 2 = 2 or fewer. Stops include both connections between segments and en-route technical stops inside a segment (segments[].stopCount), so a single flight number with a technical landing is excluded by maxStops: 0."
    • addedInput schema / properties / legs / items / properties / filters / properties / maxStops / description
      Added value: +"Max stops for this leg. Counts connections between segments and en-route technical stops inside a segment (segments[].stopCount); 0 = genuinely non-stop."
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations declare readOnlyHint=true/openWorldHint=true, so safety is covered; the description adds real constraints beyond that — the 11-month date limit, non-empty legs requirement, the fact that top-level origin/destination/departureDate/returnDate are unsupported, per-leg filter override behavior, and that the response carries a searchUrl. It stops short of describing pagination/result-size behavior, so it is strong but not exhaustive.

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 with an Overview and organized under clear headers, with required fields and the date limit called out. It is somewhat long and slightly repetitive (booking/checkout is mentioned twice), but nearly every sentence contributes actionable information.

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?

There is no output schema, and the 'What You Get' section compensates by listing offers, itineraries with segments/layovers/durations, price breakdown, baggage hints, and the searchUrl. For a high-complexity, nested-parameter search tool, the description covers the input contract and the expected return shape adequately.

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 baseline is 3, but the description adds meaning the schema does not: the explicit 'Not supported: top-level origin, destination, departureDate, returnDate — use legs only' warning, the round-trip OUTBOUND/INBOUND ordering convention, and the per-leg filters overriding global filters. These go beyond restating schema fields.

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?

States a specific verb and resource ('Search for available flights with real-time pricing from multiple providers') and implicitly distinguishes itself from siblings such as post_flights_verify (re-pricing/booking) and the get_data_flights_* reference lookups. An agent can identify it as the live availability/pricing search without opening the 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?

A dedicated 'When to Use' section names the scenarios (listings, one-way, round-trip, multi-city, filtering) and the Booking section explicitly routes the agent to post_flights_verify for re-pricing and checkout. The alternative and the condition that selects it are both spelled out.

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

Deploy Server

Other Tools