com.gojinko.mcp/jinko

Search flights between a known origin and destination using cached pricing. Use this tool whenever the user specifies BOTH where they are flying FROM and where they are flying TO. 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 has committed to EXACT dates — both a single departure date AND a single return date for one specific route. - Example: "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 only once route + both dates are locked in. - **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. Please fill as much as possible search parameters based on user intent to get best results. Origin and destination must be IATA city code by default except if the user specifies IATA Airport code in the search. ROUTE SEARCH: - Use exact 3-letter IATA airport codes or IATA city code for both origin and destination - Date ranges OR stay duration for flexible trip planning - Natural trip duration (stay_days) instead of exact return dates - By default, please search roundtrip flights unless user specifies one-way. Use trip_type="oneway" ONLY when the user explicitly asks for a one-way trip USE CASES: ✓ "Find flights from JFK to CDG next month" - route + flexible date range ✓ "Fly from LA to Tokyo for a week in December" - uses departure_date + stay_days ✓ "Paris to Barcelona for a weekend in April" - route + loose window ✓ "Cheapest flight from ORD to LHR in June" - route + loose month window ✓ "Direct business-class flight NYC → LON next month" - route with preferences Flow: flight_calendar → (user picks) → flight_search (price_check with offer_token) → trip → book. Or, for precise dates: skip flight_calendar and go straight to flight_search search mode. The widget displays flights in a scrollable carousel with options to view detailed itineraries. **Cost: 1 credit per call.**

Per questo strumento non è stato pubblicato alcuno schema di input.

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 flights preference, and locale - By default, please search roundtrip flights unless user specifies one-way AIRPORT IDENTIFICATION - CRITICAL: LLM MUST identify and recommend ALL relevant airports for user's origin location: - "New York": ["JFK", "LGA", "EWR"] - "London": ["LHR", "LGW", "STN", "LTN", "LCY"] - "Paris": ["CDG", "ORY"] - "Tokyo": ["NRT", "HND"] - "Chicago": ["ORD", "MDW"] - "Los Angeles": ["LAX"] - "San Francisco": ["SFO"] DESTINATION FILTERING - INTELLIGENT INTERPRETATION: Destinations can be specified using IATA airport codes OR city codes (3 letters). You can mix both types: - Airport codes: ["JFK", "LAX", "LHR"] - searches specific airports - City codes: ["NYC", "LON", "PAR"] - searches all airports in those cities DESTINATION LIST - CRITICAL: When users mention criteria that imply a type of destination, the LLM MUST generate the appropriate list: - "Sunny places in winter": ["MIA","MCO","SAN","PHX","HNL","CUN","PUJ","PTY","LIM","GIG"] - "Somewhere in Asia": ["NRT","HND","ICN","PVG","PEK","HKG","SIN","BKK","KUL","MNL"] - "Beach destinations": ["MIA","SAN","HNL","CUN","PUJ","SJU","NAS","MBJ"] - "European capitals": ["LHR","CDG","FRA","MAD","FCO","AMS","BRU","VIE","PRG","CPH"] If no filtering is specified ("anywhere", "surprise me"), leave destinations empty for global discovery. TYPICAL USE CASES: 1. "Where should I travel from NYC next month?" → origins: ["JFK","LGA","EWR"], destinations: [] 2. "I want to go somewhere warm from Chicago for a week in December" → origins: ["ORD","MDW"], destinations: [warm destinations] 3. "Best weekend getaways from Boston?" → origins: ["BOS"], destinations: [] 4. "Beach vacation from Seattle in summer under $600" → origins: ["SEA"], destinations: [beach destinations] IMPORTANT: Always provide ALL airports for origins to maximize search results. **Cost: 1 credit per call.**

Per questo strumento non è stato pubblicato alcuno schema di input.

Live flight tool with two modes. EACH CALL HITS LIVE PRICING — not for loose or flexible date queries (use flight_calendar for those). 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). - Supports filters on the same call: direct_only, cabin_class, max_price, include_carriers, exclude_carriers, 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 17 to June 26" → { search: { origin: "PAR", destination: "NYC", departure_date: "2026-06-17", return_date: "2026-06-26" } } ✓ "Paris to Rome June 19 to 27, direct only, business class" → { search: { origin: "PAR", destination: "ROM", departure_date: "2026-06-19", return_date: "2026-06-27", direct_only: true, cabin_class: "business" } } ✓ "JFK → CDG August 5 to 12, Air France only, under $800" → { search: { origin: "JFK", origin_type: "airport", destination: "CDG", destination_type: "airport", departure_date: "2026-08-05", return_date: "2026-08-12", include_carriers: ["AF"], max_price: 800 } } ✓ "Paris to LA June 3, one way" → { search: { origin: "PAR", destination: "LAX", departure_date: "2026-06-03" } } ✓ Cart has hotel in Madrid May 8 → May 10; user says "add a flight from Paris, directs only" → { search: { origin: "PAR", destination: "MAD", departure_date: "2026-05-08", return_date: "2026-05-10", direct_only: true }, trip_id: "trip_xxx" } - Only ONE departure_date and at most ONE return_date. No arrays, no ranges, no multi-city. MODE 2 — price_check: confirm live fares for a specific flight - Use after the user picks a flight returned by flight_calendar or find_destination. Pass the offer_token. - Schema: { "price_check": { "offer_token": "..." } } WHEN NOT TO USE (route to flight_calendar instead): - "Cheapest flight in June" (loose month window) - "Paris to NYC next week" (loose window — 7 days) - "Best weekend to fly to Rome in spring" (flexible dates) - Any query with a date RANGE that implies multiple candidate departure/return pairs - Multi-city itineraries NOTE: "June 19 to 27" / "between the 19 and 27" with a specific round-trip intent counts as exact single dates (dep=19, ret=27) — use flight_search, not flight_calendar. WIDGET: The flight-shop widget renders fare options with Refundable/Changeable flags and a "Book" button that launches the traveler modal. Both search and price_check modes populate this widget. IMPORTANT: - Prices are subject to change until booking is confirmed - Offer tokens may expire after some time - Always inform users about fare differences (refundable vs non-refundable, baggage, etc.) - Per-person totals apply unless stated otherwise PRICE CHECK FILTER PASS-THROUGH (CRITICAL): - When the user picks a flight from a previous flight_calendar or find_destination result, you call price_check with that offer_token. - ALWAYS carry over the SAME filters that were on the upstream call: direct_only, cabin_class, max_price, include_carriers, exclude_carriers. - The BFF performs a "closest-match" reshop using offer_token. Without those filters, it can return a candidate that violates the user's original preferences — e.g. stopover when they asked for direct, or wrong cabin. - Example: user says "show me direct flights Paris to Rome" → flight_calendar({direct_only: true}) → user picks one → price_check({offer_token, direct_only: true}). Forgetting direct_only here is a bug; do not skip it. TRIP CONTINUITY (trip_id): - If a recent trip(...

Per questo strumento non è stato pubblicato alcuno schema di input.

Search live hotel inventory and rates worldwide. 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 }, { latitude + longitude (+ radius_km) }, or { place_id }. - checkin, checkout: YYYY-MM-DD - 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: filters are ignored (user named the property), and the response includes nearby_alternatives — up to 5 hotels within ~2km 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 }: unambiguous cities or well-known POIs only ("Paris", "Times Square"). Provider AI search returns 0 for islands ("Menorca", "Santorini", "Mykonos"), regions ("Tuscany", "Provence", "Bavaria"), countries, archipelagos. Do NOT use { query } for those. - { city_name + country_code }: when the user named a city, even if ambiguous. Best when the destination has a primary city ("Mahón, ES" for Menorca; "Florence, IT" for Tuscany). - { latitude + longitude + radius_km }: when the destination is an area, island, or region with no obvious primary city. radius_km up to 50. - { place_id }: when you already have an upstream Place ID. If the user names something non-city (an island, region, archipelago, neighborhood), DO NOT pass it as { query } — pick { city_name+country_code } or { latitude+longitude+radius_km }. OPTIONAL: - currency, guest_nationality - filters: { min_rating, min_star_rating, max_star_rating, min_reviews, hotel_type_ids, chain_ids, facility_ids, max_results } — Mode B only - filters.max_budget_per_night: per-night per-room price cap (request currency) for "under $150/night" asks — works in BOTH modes. Hotels whose CHEAPEST rate fits are kept with ALL their rates; the search scans deeper automatically when few fit. Prefer it over post-filtering results yourself. WORKFLOW: 1. Call hotel_search with the destination, dates, and occupancy. 2. Each rate in the response includes an htl_* offer_id (the trip_item_token). 3. Pass the chosen htl_* token to trip(add_item) to build a cart. 4. Hotels work alongside flights in the same cart (single Stripe checkout). ERROR HANDLING — 422 HOTEL_NAME_LOW_CONFIDENCE (Mode A only): When { hotel_name } fuzzy lookup finds no candidate ≥ 0.7, the response body is: { "error": { "code": "HOTEL_NAME_LOW_CONFIDENCE", "message": "...", "top_candidates": [{hotel_id, name, city, score}], "suggested_retry": { "destination": {...} } } } This is ACTIONABLE, not fatal: 1. Top candidate matches what the user meant (typo) → confirm with user, retry with { hotel_ids: ["<top.hotel_id>"] }. 2. None fit → ask "I couldn't pin down 'X' — search all hotels in <city>?" then retry with suggested_retry.destination. 3. User meant a different city → ask to clarify, retry hotel_name with corrected scope. Never silently auto-pick a low-confidence candidate. EXAMPLES: - { "destination": { "query": "Paris" }, "checkin": "2026-07-15", "checkout": "2026-07-18", "adults": 2 } - { "destination": { "city_name": "Barcelona", "country_code": "es" }, "checkin": "2026-08-01", "checkout": "2026-08-05", "occupancies": [{ "adults": 2 }, { "adults": 1, "children_ages": [5] }] } - Mode A: { "destination": { "hotel_name": "Hotel Calimala", "country_code": "it", "city_name": "Florence" }, "check

Per questo strumento non è stato pubblicato alcuno schema di input.

Rich metadata (gallery, facilities, policies, per-room details) for a single hotel — called by the hotel widget on fullscreen open. **Cost: 1 credit per call.**

Per questo strumento non è stato pubblicato alcuno schema di input.

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; currently supported for HotelBeds-inventory tenants only. { "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": { "item_id": "item_123" // From trip.trip_items[].id } } 3. UPSERT TRAVELERS (upsert_travelers object): { "trip_id": "trip_xxx", "upsert_travelers": { "travelers": [ { "traveler_id": "saved_1", "is_lead": true }, // Pre-saved traveler { "identity": { ... } } // Or inline details ], "contact": { // Optional trip contact "email": "john@example.com", "phone": "+1-555-123-4567" } } } TRAVELER ENTRY OPTIONS: • { traveler_id: "id" } - Use pre-saved traveler • { traveler_id: "id", is_lead: true } - Pre-saved as lead • { identity: {...}, passport?: {...} } - Inline details WORKFLOW: 1. flight_calendar → Returns flights with offer_token 2. flight_search → Returns fare options with trip_item_token (offer_id encoded inside) 3. trip(add_item={...}) → Adds flight, returns trip + saved travelers 4. trip(upsert_travelers={...}) → Sets travelers on trip 5. checkout_trip → Completes booking RETURNS: • trip: Complete trip object with items, travelers, totals • saved_travelers: Available pre-saved travelers for selection • recommended_products: Upsell opportunities (hotels, cars, insurance) • actions_performed: Which actions were executed • trip_item_id: ID of newly added item (if add_item performed) • hint: Action guidance for the LLM. May start with "Cross-sell: ask the user..." — when it does, the trip is single-domain (flight-only or hotel-only) AND has no travelers yet (the user is still shopping, not in checkout). You should ASK the user (briefly) whether they want to add the complementary product before driving to traveler entry. Forward the trip_id from the response on the follow-up flight_search/hotel_search call so the new selection appends to this trip. Once travelers are present the hint switches to checkout guidance and the cross-sell prompt drops by design — at that point push to book. TRIP CONTINUITY: • Every successful trip(...) call returns the trip's id. Carry that trip_id in your conversatio

Per questo strumento non è stato pubblicato alcuno schema di input.

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" }, "pending_booking": { "id": "bkg_xxx", "status": "awaiting_payment", "trip_id": "trip_xxx" } } 2. CHECK STATUS (status object): Retrieves booking status. If payment is authorized but fulfillment hasn't started, automatically triggers fulfillment. { "status": { "booking_id": "bkg_xxx" } } Returns: Full booking object with status, items, passengers, totals, payment info. 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) • Trip must pass validation WORKFLOW (flights): 1. flight_calendar → offer_token 2. flight_search → trip_item_token 3. trip(add_item) → trip created 4. trip(upsert_travelers) → travelers set 5. book(create={trip_id}) → checkout URL WORKFLOW (hotels): 1. hotel_search → htl_* offer_id 2. trip(add_item, trip_item_token=htl_*) → trip created 3. trip(upsert_travelers) → travelers set 4. book(create={trip_id}) → checkout URL Flights and hotels can be in the same trip (single checkout). After book(create), poll with book(status={booking_id}) for confirmation. EXAMPLES: 1. Create booking: { "create": { "trip_id": "trip_xyz789" } } 2. Create booking with buyer contact: { "create": { "trip_id": "trip_xyz789", "buyer_contact": { "email": "john@example.com", "phone": "+1-555-123-4567" } } } 3. Check booking status: { "status": { "booking_id": "bkg_xxx" } } **Cost: 1 credit per call.**

Per questo strumento non è stato pubblicato alcuno schema di input.