PriceWin

Search Flights Live

search_flights_live

Starts a live flight search for a route and date, with an optional return date. The two directions are priced as separate one-way tickets. Fares come from Agoda, Trip.com, Booking.com, Traveloka, Kiwi.com, Mytour.vn, Vietravel Airlines and Google Flights. Origin and destination are 3-letter IATA airport codes (for example SGN, HAN, DAD). Returns a session ID; poll_flight_results returns the results. When the route or date is missing, the result is a question for the user instead of a search.

Input Schema

Name	Required	Description	Default
`cabin`	No	Cabin class (default economy)	economy
`adults`	No	Number of adults (default 1)
`origin`	No	Departure airport IATA code, e.g. 'SGN'. When omitted, the result asks the user for it.
`language`	No	Preferred UI language (en/vi/de/ja/ko/zh/fr/es/ru/th/id).
`queryText`	No	Optional short excerpt of the current request, used only to detect the UI language; it is not stored or forwarded.
`returnDate`	No	Optional return date YYYY-MM-DD. Results include a separate one-way search for the return direction; a pair is not one combined round-trip ticket.
`destination`	No	Arrival airport IATA code, e.g. 'HAN'. When omitted, the result asks the user for it.
`departureDate`	No	Departure date YYYY-MM-DD, today or later. When omitted, the result asks the user for it.

Output Schema

Name	Required	Description	Default
`cabin`	Yes
`adults`	Yes
`cached`	Yes
`origin`	Yes
`status`	Yes
`language`	No
`tripType`	Yes
`sessionId`	Yes
`returnDate`	No
`destination`	Yes
`totalReturn`	Yes
`departureDate`	Yes
`returnFlights`	Yes
`totalOutbound`	Yes
`outboundFlights`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 27, 2026

changedInput schema / properties / returnDate / description

Previous value: -"Return date YYYY-MM-DD. Return flights are not searched at the moment: the result lists outbound flights only."New value: +"Optional return date YYYY-MM-DD. Results include a separate one-way search for the return direction; a pair is not one combined round-trip ticket."

Changed2 schema fields changedOct 25, 2026

addedOutput schema / properties / outboundFlights / items / properties / agent
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / outboundFlights / items / properties / offers

Added value: +{
+  "items": {
+    "additionalProperties": true,
+    "properties": {
+      "agent": {
+        "type": "string"
+      },
+      "agentCode": {
+        "type": "string"
+      },
+      "bookingUrl": {
+        "type": "string"
+      },
+      "currency": {
+        "type": "string"
+      },
+      "price": {
+        "type": "number"
+      },
+      "pricePerTraveler": {
+        "type": "number"
+      }
+    },
+    "required": [
+      "agent",
+      "agentCode",
+      "price",
+      "pricePerTraveler",
+      "currency",
+      "bookingUrl"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed3 schema fields changedOct 24, 2026

addedInput schema / properties / returnDate / anyOf

Added value: +[
+  {
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+    "type": "string"
+  },
+  {
+    "const": "",
+    "type": "string"
+  }
+]

removedInput schema / properties / returnDate / pattern
```
Removed value: -"^\\d{4}-\\d{2}-\\d{2}$"
```
removedInput schema / properties / returnDate / type
```
Removed value: -"string"
```

Changed1 schema field changedOct 18, 2026

changedInput schema / properties / returnDate / description

Previous value: -"Return date YYYY-MM-DD (omit for one-way). Must be on or after departureDate."New value: +"Return date YYYY-MM-DD. Return flights are not searched at the moment: the result lists outbound flights only."

First observedOct 3, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations cover the safety profile (readOnly=false, destructive=false, openWorld=true), and the description adds real context: fares are sourced across eight providers, the two directions are priced as separate one-way tickets, and a missing-input case returns a clarifying question rather than a search. It omits anything on auth, rate limits, or session lifetime.

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 the core action and workflow before details. The list of eight fare providers is slightly verbose but earns its place by conveying data provenance; otherwise efficient.

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?

An output schema exists, so return values need not be explained in depth, yet it still names the returned session ID and the follow-up poll step. For an 8-param, zero-required search tool the description plus schema covers everything needed to call it correctly.

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 coverage is 100%, so all eight parameters (including the IATA pattern and date formats) are already documented. The description only echoes the IATA-code convention and the separate-one-way return behavior, adding little beyond the schema.

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 ("Starts a live flight search for a route and date") and explicitly distinguishes the polling sibling by noting it returns a session ID while poll_flight_results returns results. An agent can tell what this does and how it relates to the sibling 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 Guidelines4/5

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

Clearly implies the start-then-poll workflow by naming poll_flight_results as the consumer of the session ID, and adds the fallback condition (missing route/date yields a question). It stops short of excluding other flight siblings like get_flight_fare_calendar or get_flight_price_insight.

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

All PriceWin tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?