Cleartrip

`create_itinerary` - Create a bookable itinerary from flat parameter values. Accepts simple scalar values — `search_id`, `data_id`, `origin`, `destination`, `depart_date`, `travel_option_id`, `fare_id`, `price`, optional `card_id` / `return_card_id`, and optional passenger/cabin/return-leg parameters — and assembles the Cleartrip payload internally. When to use: After `search_flight` → `fetch_fare_options` → user picks a fare → `create_itinerary`. Get `fare_id` and `price` from `fareSelectionGuide.fares[]` in the `fetch_fare_options` response — **never copy directly from `fareOptions[]`; never invent or guess these values**. Get `travel_option_id` from `nextSteps.params.travel_option_id` (pre-filled) in the `fetch_fare_options` response. All other required params (`search_id`, `data_id`, `origin`, `destination`, `depart_date`) are also pre-filled in `nextSteps`. When NOT to use: Do **not** use while the user is still comparing fare families/flights without explicit fare selection. Flow position: * Requires: `search_flight` and `fetch_fare_options` have already run and the user has selected a fare. * Next step: On success, direct the user to the `info_url` link to complete their booking (traveller details, payment) on Cleartrip. Do NOT ask for passenger details or attempt to call any other booking tools — the booking is completed on Cleartrip's website. Returns (external response): * `itinerary_id`: Unique itinerary ID created for this booking. * `info_url`: Cleartrip booking page URL — direct the user here to complete traveller details and payment. * `next_steps`: Guidance confirming to open `info_url` immediately. Constraints: ⚠️ Special Restrictions: * `depart_date` / `return_date` are date values converted inside the tool for the itinerary API. * One-way: omit all `return_*` parameters. * Round-trip: provide `return_date` plus `return_travel_option_id`, `return_fare_id`, `return_price`. `card_id` and `return_card_id` are optional; if either is set for round-trip, set both. Return-leg origin/destination are auto-swapped from the outbound. * `fare_id` / `return_fare_id` must be copied in full from `fetch_fare_options` (including any `~~V2` suffix); truncation causes backend errors. * **`data_id`** must be the complete top-level **`dataId`** from the same search response as `fetch_fare_options` (mandatory; same rule). Do not pass `searchId`. Do not truncate or retype.

create_itinerary

`fetch_fare_options` - Fetch fare options (fare families/cards) for a specific flight selection. Accepts simple parameters and returns fare options directly. When to use: After `search_flight` has been called and the user has selected a specific flight from the presented options. All required parameters (`travel_option_id`, `data_id`, `origin`, `destination`, `departure_date`) are available in the `search_flight` response — extract and pass them directly. No additional search or session data is needed. When NOT to use: Do not call for all flights at once; only fetch for the user's explicit selection. Flow position: * Requires: A prior `search_flight` response in context. Required params: - `travel_option_id`: copy from `selectionGuide.options` where `journeyId` matches — **never invent**. - `data_id`: the top-level `dataId` token (opaque, full copy). **Never use `searchId` as `data_id`** — wrong field causes HTTP 500. - `search_id`: top-level `searchId` (`DC_Search-…`) — **required** so `create_itinerary` nextSteps are pre-filled. - `origin`, `destination`, `departure_date`, `journey_id` (`J1` or `J2`). - For round-trip J2: also `j1_travel_option_id` and `onward_departure_date` (pre-filled in J1 fare nextSteps). * Next step: Show fare table using `fareOptions` with columns from `requiredDisplayColumns`. Wait for user to pick a fare. Follow `flowInstruction` / `nextSteps` — do not auto-pick or call `create_itinerary` until user confirms. Returns (processed response): * `fareOptions`: Fare rows — each has `fareId`, `displayTitle`, `displaySubTitle`, `price`, `isCheapest`, `benefitTags`, `brand`, and comparison columns (`cancellationFee`, `dateChangeFee`, `cabinBagPerAdult`, `checkInBagPerAdult`, `seatSelection`, `mealSelection`). Display as table. Use `fareSelectionGuide` (not this array) for booking IDs. * `fareSelectionGuide`: **Canonical lookup for fareId and price.** Contains `fares[]` — each entry has `name`, `fareId`, `price`. After user picks a fare by name, read `fareId` and `price` from here. **NEVER invent or guess fareId or price — always read from `fareSelectionGuide.fares[]`.** * `flightSummary`: Selected flight summary including `travelOptionId`. * `searchId` / `cardId`: echoed from request for downstream booking. * `requiredDisplayColumns`: Ordered column names for the fare table. * `flowInstruction` / `nextSteps`: Guidance for the next action. **Post-itinerary:** Once `create_itinerary` has succeeded, any user question about **cancellation charges**, **refunds**, **amendment/date-change fees**, or **ClearChoice** requires **`get_itinerary_addon_cards`** (`itinerary_id`) in addition to this tool’s fare rows; **do not** infer card-add-on terms from `fareOptions` alone. Display Rules: Present fare options in a tabular format using all columns from `requiredDisplayColumns`. Each row corresponds to a unique fare option. Present all fare options (do NOT auto-select or highlight the cheapest unless the user asks). Wait for the user to confirm their selection—only then proceed to `create_itinerary`. Constraints: ⚠️ Special Restrictions: * Must be called individually for each journey leg: for round-trip, call separately for 'J1' (onward) and 'J2' (return). * Only supply the user's explicit flight selection (never call for all possible flights). * Do not auto-select a fare. Always show all options to the user and wait for their input.

fetch_fare_options

`fetch_flight_benefits` - Fetch segment-level benefits for a selected **international** flight (baggage, penalties, meal/seat). Accepts flat parameters and builds the backend payload internally. When to use: After `search_flight` has been called for an international flight and the user has picked a card, and you need full cancellation/date-change windows, charges/refunds breakdown, or per-hop baggage details—typically alongside or after `fetch_fare_options`. When NOT to use: Domestic-only benefit comparison; prefer `fetch_fare_options` for fare-family grids. Do not call for every card—only the user's chosen itinerary. Flow position: * Requires: A prior `search_flight` response for an international flight. Extract: `travel_option_id`, `sub_travel_option_id`, `origin`, `destination`, `fare_id` (from fare options), `departure_date`, `departure_time`, `per_pax_total_price`. Optional: `journey_id` (J1/J2), `departure_timezone`, passenger counts. * Next step: Summarise `benefits.segments` for the user and present in a tabular format. When they are ready to book, follow `flowInstruction` / `nextSteps` (usually `create_itinerary` with the ids in the payload). Returns (processed response): * `benefits`: Segment map keyed by route keys (e.g. `DEL_DXB`). Each segment includes `subTravelOptionId`, `subTravelOptionKey`, `benefitKey`, one-line `cancellationFee` / `dateChangeFee`, `cancellationPolicy` and `dateChangePolicy` (time-bounded windows with `fromDateTime` / `toDateTime`, `totalCharges`, `amountRefundable`, `chargesBreakup`), `benefitIds`, `mealDetails` / `seatDetails` (`chargeable`, `amount`, `description`), `cabinBagPerAdult` / `checkInBagPerAdult`, `baggageDetails` by pax type, and `flightBenefits` (per flight hop with `baggageAllowances`). * `flowInstruction`: Guidance for the next action. Constraints: * International supplementary detail only; round-trip: call per leg (`J1`, `J2`) when both need benefits. * Prefer structured `cancellationPolicy` / `dateChangePolicy` and `chargesBreakup` when explaining fees.

fetch_flight_benefits

`get_calendar_fares` - Fetch day-by-day fare calendar for a route (trend/pricing by date), not full flight inventory. When to use: User wants **fare levels across dates**—a whole month, or roughly a week around a specific day. When NOT to use: Listing specific flights, times, or cards (use `search_flight`). Flow position: * Requires: `origin`, `destination` (IATA), and `date` as a date value. Set `around_specific_date`: `True` = ~7 days centered on `date`; `False` = full month containing `date` (e.g. “fares for June”). * Next step: If user picks dates, run `search_flight` for concrete options. Returns: * Per-day amounts (INR), `fareCategory` (CHEAPEST / AVERAGE / COSTLIER), and `dayData` mapping date strings to `{amount, fareCategory, tripSavings, events}`. Optional parameters: `travel_class`, `adults`, `children`, `infants`, `fare_calendar_type`, `number_of_days`. Display Rules: * Present as a readable calendar or table by date—this is aggregate fare insight, not a substitute for live search.

get_calendar_fares

`get_price_insights` - Analyze price trends for a route using search context and the **cheapest** observed fare to guide booking timing. When to use: After `search_flight`, when the user asks whether today’s price looks high/low vs history or typical range. When NOT to use: Without search parameters and a defensible cheapest-fare input; as a substitute for live availability. Flow position: * Requires: `origin`, `destination`, dates, cabin, and cheapest fare derived from search. One-way: minimum `pricingPerAdult` across cards. Round-trip: minimum of (cheapest onward + cheapest return) or cheapest special round-trip bundle, per product rules. * Next step: Share the narrative summary; user may still book via `fetch_fare_options` → `create_itinerary`. Returns: * Trend verdict (e.g. higher/lower/in range), delta from median, sample size, pricing buckets, human-readable summary. * Partial response: HTTP 206 when data is thin; error codes `PI-001`, `PI-002`, `PI-003` explain insufficient or invalid inputs.

get_price_insights

`search_flight` - Live flight search with processed response (flights cards, searchId, dataId, totalFlightsAvailable, displaying, metaData, selectionGuide, isRoundTrip). When to use: When a user requests real-time flight availability, pricing, or schedules between two cities. This is the primary search tool. When NOT to use: If you only need to check the rules or final price of a flight the user has already selected (use `fetch_fare_options` instead). Flow position: * Requires: None (entry-point tool). * Next step: Present the `flights` table to the user. **Wait for the user to explicitly select a flight.** After user selects, use `selectionGuide.options` to look up the `cardId` and `travelOptionId` for that flight. Then call `fetch_fare_options` with `travelOptionId` (as `travel_option_id`) and the `dataId` from the response (as `data_id`). Never auto-select — always wait for user input before calling `fetch_fare_options`. Returns (processed external response): * `searchId` (string): Readable correlation id (e.g. `DC_Search-<uuid>`); pass as `search_id` only where explicitly required. * `dataId` (string): **Required opaque token** — pass exactly as returned as parameter `data_id` to `fetch_fare_options` and `create_itinerary`. **Never substitute `searchId` for `dataId`** — wrong id causes HTTP 500. If `dataId` is absent, re-run `search_flight`. * `flights` (array): Result cards. Each card contains exactly: `journeyId`, `cardId` (integer), `travelOptionId` (integer), `flights` (flight number label e.g. `'AI101 → SG456'`), `departure` (`{airport, time}`), `arrival` (`{airport, time}`), `duration` (string e.g. `'2h 30m'`), `stops` (integer), `price` (total INR), `currency` (`'INR'`), `segments` (list of `{flightNumber, airlineCode}`). **Fields NOT present in this response:** `layovers`, `timeline`, `terminal`, `sortData`, `filterData`, `aircraftType`. Do not reference or invent these fields. * `totalFlightsAvailable` / `displaying`: Count of all matching flights vs how many are shown. * `viewMoreUrl`: Cleartrip URL to see all results; show this to the user so they can browse further. * `metaData`: Lookups — `airlineDetail` and `airportDetail` maps keyed by IATA codes. * `selectionGuide` (object): **Use this to look up IDs after user selects a flight.** Contains: - `dataId`: same as top-level `dataId` — pass as `data_id` to downstream tools. - `searchId`: same as top-level `searchId`. - `options` (array): one entry per displayed flight with `flight` (label), `cardId`, `travelOptionId`, `journeyId`, and `price`. **Always read `travelOptionId` from here — never invent it.** * `isRoundTrip` (boolean, if round-trip): `true` when J2 cards are present; `flights` will contain cards for both J1 (outbound) and J2 (return). Call `fetch_fare_options` once per leg. Display Rules: Present `flights` in a table sorted by increasing price. Show at minimum: flight code (`flights`), departure airport + time, arrival airport + time, duration, stops, price (INR). For round-trip, show J1 and J2 in separate tables. Always show `viewMoreUrl` so the user can see more options on Cleartrip. Constraints: ⚠️ Special Restrictions: * Cleartrip For Work fares are mutually exclusive with `special_fare_type`. * Origin and destination airports cannot be the same. * The search date must not be in the past. * `STUDENT` and `SENIOR_CITIZEN` fares cannot be combined with `children` or `infants`.

search_flight