Jinko MCP

Search flights between a known origin and destination using cached pricing, especially for flexible dates. WHEN TO USE THIS TOOL (CRITICAL): - The user provides both an origin AND a destination (city or airport) - Examples: "Paris to Barcelona", "JFK to CDG", "London to NYC for a weekend" - Supports loose / flexible dates: single dates, date arrays, date ranges, stay_days - ALSO the right tool for "cheapest flight", "best flight", "find me a flight", "cheapest date" phrasings — this tool returns the cheapest cached itineraries for the given route and window. WHEN TO USE find_destination INSTEAD: - The user does NOT specify a destination: "Where should I go from Paris?", "Best deals from NYC" - The user wants inspiration: "Beach destinations from London", "Cheap flights from SF" WHEN TO USE flight_search INSTEAD: - The user wants live pricing on one specific route with an exact departure date. For a round trip, also require an exact return date; one-way trips need no return date. - Examples: "Paris → NYC one-way on June 17", "Paris → NYC, June 17 → June 26" - flight_search hits live pricing (each call has a cost) and is the step immediately before booking. Use it once the route and required travel dates are locked. - **TRIP-CONTEXT DATES COUNT AS EXACT.** If a trip is already in context with a HOTEL, the hotel's check-in and check-out ARE the exact departure/return dates the user wants — even if they don't restate the dates in the message. In that case use flight_search (not flight_calendar) with the hotel's check-in as departure_date and check-out as return_date. Examples: cart has hotel May 8 → May 10 in Madrid; user says "add a flight from Paris" → flight_search with PAR→MAD, dep=2026-05-08, ret=2026-05-10. The trip cross-sell hint confirms this — when it points you at flight_search, follow it. IMPORTANT: All dates in query parameters (departure_dates, departure_date_ranges, return_dates, return_date_ranges) MUST be in the future. Never use past dates. Use

Discover travel destinations when the user does NOT know where to go. This is a destination EXPLORATION tool. WHEN TO USE THIS TOOL (CRITICAL): - The user does NOT specify a destination: "Where should I go?", "Best deals from NYC" - The user wants inspiration based on criteria: "Beach destinations", "Somewhere warm", "Cheap flights from SF" - The user wants to compare multiple destination options from their origin - The user previously asked for destination recommendations and wants pricing for those options WHEN NOT TO USE THIS TOOL — USE flight_calendar INSTEAD: - The user specifies BOTH an origin AND a destination → use flight_calendar - Examples that should use flight_calendar, NOT this tool: • "Flights from Paris to Barcelona" → flight_calendar • "Find me a flight from JFK to CDG" → flight_calendar • "Cheapest flight from LA to Miami in June" → flight_calendar • "Paris to BCN for a weekend in April" → flight_calendar • "What are the cheapest dates to go to NYC from Paris?" → flight_calendar - If the user names a specific city/airport as destination, that means they KNOW where to go → flight_calendar IMPORTANT - DATES: All dates in query parameters (departure_dates, departure_date_ranges, return_dates, return_date_ranges) MUST be in the future. Never use past dates. Please fill as much as possible search parameters based on user intent to get best results. IMPORTANT - RE-CALL THIS TOOL when the user: - Asks for a different type of destination (beach, city trip, ski, etc.) - Asks for different dates while still exploring - The user is already in fullscreen mode in the widget CORE FUNCTIONALITY: - REQUIRED: User's origin location (LLM identifies ALL nearby airports) - OPTIONAL: Destination filtering by specific airports/cities OR omit for global discovery mode - Destination Discovery Mode: When destinations is omitted/empty, searches ALL destinations globally - Flexible dates and stay durations for exploring options - Filter by budget, direct fl

Live flight tool with two modes. Provide exactly one of "search" or "price_check". Set the unused one to null or leave it out; for a route search, send "price_check": null. EACH CALL HITS LIVE PRICING — it prices ONE exact date pair, so any loose, open or flexible date query belongs to flight_calendar instead. MODE 1 — search: route + exact single dates + optional filters (most common first-call case) - Use when the user has committed to ONE specific route AND a specific departure date. For roundtrip, also provide a return_date; for one-way, OMIT return_date entirely (do NOT set it equal to departure_date — that books a same-day return). - ROUTE CODES: the city code when the user named a city, the airport code when they named an airport. Untyped, a code that names a multi-airport city is searched as the city and any other code as the airport; LAX, MIA and LAS are both a city code and that city's main airport, so they are read as the city unless you send origin_type / destination_type "airport". - Supports the full shop filter set on the same call: trip_type, max_stops, cabin_class, max_price (whole-trip budget for all passengers), limit, include_carriers / exclude_carriers, single_carrier_only, departure/arrival (and return_*) time ranges, connection_time_min/max_minutes, max_total_duration_minutes, refundable_only, changeable_only, checked_bag_included, via_airports / exclude_via_airports, aircraft_types, origin_alternate_airports / destination_alternate_airports, nearby_airports, same_connection/origin/turnaround_airport_only, origin_type, destination_type. - **Trip-context dates count as exact.** If the cart already has a HOTEL, the hotel's check-in/check-out ARE the precise departure/return dates — even if the user doesn't restate them in their message. Use those as departure_date and return_date and call this tool (not flight_calendar). Forward the trip_id on the call. - Examples: ✓ "Paris to NYC, June 1 to June 10" → { search: { origin: "PAR", destination:

Search live hotel inventory and rates worldwide. CONTINUATION: - To load more from a prior result, send { next_handle } by itself: it continues the same search. Do not repeat destination, dates, occupancy, currency, filters, user_intent or trip_id. FIRST SEARCH REQUIRED: - destination: object — two distinct modes. Mode A (rate lookup): { hotel_name (+ optional country_code, city_name) } or { hotel_ids }. Mode B (hotel search): { query }, { city_name + country_code }, or { latitude + longitude (+ radius_km) }. - checkin, checkout: the user's stay dates in YYYY-MM-DD. Check-in must be today or later; check-out must be after check-in. - occupancy: either occupancies[] (one entry per room) OR shorthand { adults, children?, rooms? } TWO MODES — pick deliberately: MODE A (rate lookup — the user named a specific hotel): - { hotel_name }: free-text hotel name ("Hotel Calimala", "The St. Regis Rome", "Hôtel Costes"). Server fuzzy-matches against a 1.74M-hotel catalog. ALWAYS pair with country_code AND city_name when known — lookup precision drops sharply on common names without scope. Returns 422 HOTEL_NAME_LOW_CONFIDENCE if no candidate scores ≥ 0.7; see "ERROR HANDLING" below. - { hotel_ids }: re-shop a known set (from a prior search result). In Mode A: property filters (min_rating, min_star_rating, max_star_rating, min_reviews, hotel_type_ids, chain_ids, facility_ids) cannot be combined with hotel_name / hotel_ids: the request is rejected (the user named the property). filters.max_budget_per_night applies. The response includes nearby_alternatives — up to 40 hotels within ~3km of the matched property in the same response shape so the user can compare. MODE B (hotel search — the user is exploring a destination): - { query }: a natural-language destination (city, POI, island or region). The platform parses it once into city + country or coordinates and applies shared location normalization; raw query text is never sent to a supplier. - { city_name + country_code }: whe

Rich metadata for one hotel. Pass the hotel_ref from hotel_search when available, exactly as returned; hotel_id remains a legacy fallback. **Cost: 1 credit per call.**

Unified tool for managing a trip (shopping cart). Supports flights and hotels in the same cart. Actions are determined by which objects you provide. SCHEMA: { trip_id?: string, // Existing trip ID (omit to create new) offer_id?: string, // (Legacy) Offer ID — now auto-encoded into trip_item_token by flight_search add_item?: { ... }, // Add a flight or hotel to the trip remove_item?: { ... }, // Remove an item from the trip upsert_travelers?: { ... }, // Set travelers (replaces all) idempotency_key?: string // Prevent duplicate processing } ACTIONS: 1. ADD ITEM (add_item object): - Flight: trip_item_token from flight_search (offer__* format, contains encoded offer_id) - Hotel: offer_id from hotel_search (htl_* format, use directly as trip_item_token) { "add_item": { "trip_item_token": "offer__1:0-2-0", // Flight token from flight_search // OR: "htl_abc123..." // Hotel token from hotel_search "traveler_ids": ["traveler_1", "traveler_2"] // Optional: associate travelers } } MULTI-ROOM HOTEL (rooms array — one booking, one reference): When the user wants MULTIPLE ROOMS for ONE hotel stay (same hotel, same check-in/check-out), make ONE add_item call with the rooms array — do NOT add the same hotel twice as separate items when the user wants one reservation. Each entry carries that room's htl_* rate token from hotel_search (e.g. one rate per requested occupancy). 2–8 rooms; for a single room use trip_item_token instead. rooms and trip_item_token are mutually exclusive. Hotel tokens only; not every hotel rate can be booked this way, and one that cannot is refused when it is added. { "add_item": { "rooms": [ { "trip_item_token": "htl_rate_room1", "traveler_ids": ["traveler_1", "traveler_2"] }, { "trip_item_token": "htl_rate_room2", "traveler_ids": ["traveler_3"] } ] } } 2. REMOVE ITEM (remove_item object): { "trip_id": "trip_xxx", "remove_item": { "ite

Unified tool for booking a trip. Actions are determined by which object you provide. SCHEMA: { create?: { // Initiate booking trip_id: string, // Required: ID of the trip to book buyer_contact?: { // Optional: buyer contact info email: string, phone?: string } }, status?: { // Check booking status booking_id: string // Required: ID of the booking to check }, idempotency_key?: string // Prevent duplicate processing } ACTIONS: 1. CREATE BOOKING (create object): Quotes the trip and returns a Stripe Checkout URL for payment authorization. { "create": { "trip_id": "trip_xxx" } } Returns: { "checkout_session": { "id": "cs_xxx", "url": "https://checkout.stripe.com/...", // Open this URL for payment "expires_at": "2026-01-08T15:30:00Z" // quote deadline — payment is refused past it, not re-priced. Not a price hold. Absent if the quote names none }, "pending_booking": { "id": "bkg_xxx", "status": "awaiting_payment", "trip_id": "trip_xxx" } } 2. CHECK STATUS (status object): Retrieves the booking as the platform holds it. { "status": { "booking_id": "bkg_xxx" } } Returns: Full booking object with status, items, passengers, totals, payment info. booking.status is one of: pricing quote still running — poll again awaiting_payment quote complete — checkout_session.url is where the customer pays processing paid — the platform is booking with the suppliers; poll again confirmed / partially_confirmed / failed / cancelled the outcome, with booking_reference, booked_items and documents No checkout URL is returned once the trip is paid: never ask the customer to pay again from processing or a terminal status. PREREQUISITES: • Trip must have at least one item (use trip tool with add_item) • Trip must have travelers assigned (use trip tool with upsert_travelers)