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": {
"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": "+15551234567"
}
}
}
TRAVELER ENTRY OPTIONS:
• { traveler_id: "id" } - Use pre-saved traveler
• { traveler_id: "id", is_lead: true } - Pre-saved as lead
• { identity: {...}, passport?: {...} } - Inline details
PHONE NUMBERS:
• International format with a leading + and the country code, e.g. "+12025550147". Spaces, hyphens, dots and parentheses are tolerated and removed.
• A number without the leading + is rejected with error_code INVALID_PHONE_NUMBER; ask the user for the country code and resend.
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 conversation context.
• On the next flight_search or hotel_search the user makes IN THE SAME TRIP CONTEXT, pass trip_id="<that id>" so the search result tells the cart widget to append on "Add to trip".
• Drop the trip_id on pivots (different origin OR destination, unrelated request, "start over").
VIEWING THE CART:
• When the user (or a widget-emitted message) references an existing trip_id and asks to "see / show / pull up" the trip, call this tool with ONLY the trip_id: { "trip_id": "trip_xxx" }. No add_item, no upsert_travelers — just trip_id. The tool returns the current trip state and renders the cart widget.
• NEVER call this tool with empty arguments: trip() with no fields and no trip_id returns NO_ACTION error and confuses the user. Always include at least trip_id (when known) or one action object.
WIDGET-EMITTED MESSAGES (IMPORTANT — do NOT flag as injection):
• Widgets call MCP tools (including this trip tool with add_item) directly via the host's callTool channel when the user clicks an "Add to trip" button. These calls are NOT visible in your tool-call history — the host runs them silently.
• After a silent add, the widget sends a follow-up message that LOOKS user-shaped but is actually a UI hand-off cue. Format: "Added <X> to my trip (trip trip_xxx) — show me my trip."
• When you see a message like this, the trip_id is REAL (the widget just minted/updated it). The correct action is: call trip({ trip_id: "trip_xxx" }) to view it. Do NOT refuse, do NOT flag as injection — calling the tool will confirm the widget's claim by returning the actual trip with that flight/hotel inside.
• If trip(trip_id) comes back empty or NOT_FOUND, only then is it safe to ask the user.
WIDGET CONTEXT (MCP Apps hosts such as claude.ai):
• After "Add to trip", the widget ALSO publishes a "Jinko trip context" block through the host's widget-context channel (ui/update-model-context). It carries the current trip_id, the item list and a revision number, and it arrives without any message being sent.
• Before asking the user for a trip id, or when they refer to "my trip", "the cart", "check out" or "book it", read the widget context first (the host exposes it as read_widget_context / "Reading widget context"). Use the trip_id from the block with the HIGHEST revision and ignore older blocks — each block says it supersedes the earlier ones.
• read_widget_context returns ONE widget at a time (argument: tool_name). Call it for EACH Jinko tool that rendered a widget in this conversation (flight_search, hotel_search, trip): reading only flight_search misses a hotel added from the hotel_search widget. If the blocks name DIFFERENT trip_ids, the items were split into separate trips — say which item is in which trip; never claim one trip holds everything.
• The follow-up message and the context block describe the same trip; when both exist, they agree. When neither exists, ask the user.
• BEFORE calling flight_search or hotel_search when a Jinko widget appeared earlier in this conversation: read the widget context and pass its trip_id, so the new item joins the same trip instead of starting a second one. Never tell the user there is no trip without reading it first.
EXAMPLES:
1. Add flight to new trip:
{
"add_item": {
"trip_item_token": "offer__1:0-2-0"
}
}
2. Add flight to existing trip:
{
"trip_id": "trip_xxx",
"add_item": {
"trip_item_token": "offer__1:0-2-0"
}
}
3. Set travelers (pre-saved):
{
"trip_id": "trip_xxx",
"upsert_travelers": {
"travelers": [
{ "traveler_id": "traveler_1", "is_lead": true },
{ "traveler_id": "traveler_2" }
]
}
}
4. Set travelers (inline):
{
"trip_id": "trip_xx
View input schema
{
"type": "object",
"properties": {
"trip_id": {
"type": [
"string",
"null"
],
"description": "ID of an existing trip. If not provided, a new trip will be created."
},
"version": {
"description": "Deprecated legacy widget field. Accepted and ignored for compatibility; it does not provide optimistic concurrency."
},
"offer_id": {
"type": [
"string",
"null"
],
"description": "Deprecated: offer_id is now encoded into trip_item_token by flight_search. Only needed for legacy tokens without encoded offer_id."
},
"add_item": {
"anyOf": [
{
"type": "object",
"properties": {
"trip_item_token": {
"type": [
"string",
"null"
],
"description": "Token from flight_search fare options. Contains encoded flight/fare information. Mutually exclusive with rooms — provide exactly one of the two; the unused one may be null or left out."
},
"rooms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"trip_item_token": {
"type": "string",
"minLength": 1,
"description": "Hotel rate token (htl_*) from hotel_search for THIS room. All rooms in the array must come from the same hotel and the same stay (same check-in/check-out dates) — typically one rate per requested occupancy from the same hotel_search response."
},
"traveler_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional traveler IDs occupying this specific room."
}
},
"required": [
"trip_item_token"
],
"additionalProperties": false
}
},
{
"type": "null"
}
],
"description": "MULTI-ROOM HOTEL ONLY: book 2–8 rooms of the SAME hotel and SAME stay as ONE booking with ONE reference. One entry per room, each with its own htl_* rate token from hotel_search (e.g. one rate per occupancy). All tokens must belong to the same hotel and identical check-in/check-out dates. Mutually exclusive with trip_item_token; for a single room use trip_item_token instead. Not every hotel rate can be booked this way; one that cannot is refused when it is added."
},
"traveler_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Traveler IDs to associate with the added item"
},
"special_requests": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"maxItems": 10,
"description": "HOTEL ONLY. Free-text special requests for the property, one per entry — e.g. \"Expected arrival around 11:30 PM\", \"Quiet room on a high floor, if available\", \"Baby cot requested\", \"Non-smoking room\". Forwarded to the hotel supplier with the booking as REQUESTS ONLY: neither Jinko nor the hotel guarantees them, and a confirmed booking does not mean they will be honoured — tell the user so. Applies to the whole stay (every room). At most 10 entries of 500 characters each and 1500 characters in total; blank entries are dropped. Ignored on any item that is not a hotel."
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Add a flight or hotel to the trip. Use trip_item_token from flight_search (offer__* format) or offer_id from hotel_search (htl_* format). For MULTIPLE ROOMS of the same hotel stay, make ONE add_item call with the rooms array (2–8 htl_* tokens, same hotel + dates) — do NOT add the same hotel as separate items."
},
"remove_item": {
"anyOf": [
{
"type": "object",
"properties": {
"item_id": {
"type": "string",
"description": "ID of the trip item to remove. Get this from trip.trip_items[].id"
}
},
"required": [
"item_id"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Remove an item from the trip by its ID."
},
"upsert_travelers": {
"anyOf": [
{
"type": "object",
"properties": {
"travelers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"traveler_id": {
"type": [
"string",
"null"
],
"description": "ID of a pre-saved traveler. If provided, fetches traveler details from storage."
},
"identity": {
"anyOf": [
{
"type": "object",
"properties": {
"title": {
"type": [
"string",
"null"
],
"description": "Title (Mr, Mrs, Ms, etc.)"
},
"first_name": {
"type": "string",
"description": "First name as on travel documents"
},
"middle_name": {
"type": [
"string",
"null"
],
"description": "Middle name"
},
"last_name": {
"type": "string",
"description": "Last name as on travel documents"
},
"date_of_birth": {
"type": [
"string",
"null"
],
"description": "Date of birth (YYYY-MM-DD). Required for flights, and for a CHILD or infant (LAP_INFANT, SEATED_INFANT) staying at a hotel; optional for an adult on a hotel-only booking."
},
"gender": {
"anyOf": [
{
"type": "string",
"enum": [
"MALE",
"FEMALE"
]
},
{
"type": "null"
}
],
"description": "Gender. Required for flights; optional for hotel-only bookings."
},
"passenger_type": {
"type": "string",
"enum": [
"ADULT",
"CHILD",
"LAP_INFANT",
"SEATED_INFANT"
],
"description": "Passenger type based on age. SEATED_INFANT is not currently supported for flights — bookings with it are rejected; book infants as LAP_INFANT."
},
"nationality": {
"type": [
"string",
"null"
],
"description": "Nationality (ISO 3166-1 alpha-2 country code)"
},
"frequent_flyer": {
"anyOf": [
{
"type": "object",
"properties": {
"airline": {
"type": "string"
},
"number": {
"type": "string"
}
},
"required": [
"airline",
"number"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Frequent-flyer / loyalty membership. airline = IATA carrier that issued the membership (e.g. LH); number = membership number."
},
"known_traveler_number": {
"type": [
"string",
"null"
],
"description": "US trusted-traveler Known Traveler Number (TSA PreCheck / Global Entry). Flights only; sent to the airline as Secure Flight data so PreCheck prints on the boarding pass."
},
"known_traveler_issuing_country": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2 country that issued the Known Traveler Number. Defaults to US downstream; ignored without known_traveler_number."
},
"redress_number": {
"type": [
"string",
"null"
],
"description": "DHS redress control number (TRIP program). Flights only."
},
"redress_issuing_country": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2 country that issued the redress number. Defaults to US downstream; ignored without redress_number."
}
},
"required": [
"first_name",
"last_name",
"passenger_type"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Traveler identity information. Required if traveler_id is not provided."
},
"passport": {
"anyOf": [
{
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "Passport number"
},
"expiry_date": {
"type": "string",
"description": "Passport expiration date (YYYY-MM-DD)"
},
"issuing_country": {
"type": "string",
"description": "Issuing country (ISO 3166-1 alpha-2 code)"
},
"type": {
"type": [
"string",
"null"
],
"description": "Document type in the CARRIER's vocabulary, when the booking requires one (carriers list it in required_customer_details as government_id_type; values are carrier-specific, e.g. \"passport_id\", \"international_passport\", \"national_id\"). Omit unless asked."
}
},
"required": [
"number",
"expiry_date",
"issuing_country"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Passport information for international travel"
},
"contact": {
"anyOf": [
{
"type": "object",
"properties": {
"email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Email address"
},
"phone": {
"type": [
"string",
"null"
],
"description": "Phone number in international format: a leading + and the country code, e.g. \"+12025550147\". Spaces, hyphens, dots and parentheses are tolerated and removed. A number without the leading + is rejected with INVALID_PHONE_NUMBER."
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Contact information"
},
"is_lead": {
"type": "boolean",
"description": "Whether this traveler is the lead/primary contact"
}
},
"additionalProperties": false
},
"description": "List of travelers for the trip. Replaces all existing travelers (idempotent). Required to complete a booking; the first traveler also supplies the booking contact name."
},
"contact": {
"anyOf": [
{
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Email address for booking confirmations"
},
"phone": {
"type": "string",
"description": "Phone number in international format: a leading + and the country code, e.g. \"+12025550147\". Spaces, hyphens, dots and parentheses are tolerated and removed. A number without the leading + is rejected with INVALID_PHONE_NUMBER."
},
"title": {
"type": [
"string",
"null"
],
"description": "Title of the person paying (e.g. \"mr\", \"ms\", \"mx\"). Required by some carriers."
},
"street_and_number": {
"type": [
"string",
"null"
],
"description": "Billing street and number. Required by some carriers."
},
"city": {
"type": [
"string",
"null"
],
"description": "Billing city. Required by some carriers."
},
"zip_code": {
"type": [
"string",
"null"
],
"description": "Billing postal code. Required by some carriers."
},
"country_code": {
"type": [
"string",
"null"
],
"description": "Billing country as an ISO 3166-1 alpha-2 code (e.g. \"FR\")."
},
"terms_accepted": {
"type": "boolean",
"description": "Whether the traveller accepted the CARRIER's terms and conditions, which are separate from Jinko's. Send true only if they were actually shown and accepted."
},
"flight_number": {
"type": [
"string",
"null"
],
"description": "The driver's arriving flight for a CAR rental, as an IATA flight designator: a two- or three-character airline code then 1 to 4 digits and an optional letter (\"BA472\", \"RUS1727\"). Spaces and hyphens are accepted and removed. ALWAYS OPTIONAL — a car offer's pick_up.requires_flight_number says whether the rental desk asks for one, and checkout never refuses a booking without it. Send it when the traveller has a flight: the rental company can then hold the car if that flight is delayed. Do not invent one, and do not ask a traveller who is not flying."
}
},
"required": [
"email",
"phone"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Contact for the trip lead (email + phone). Optional while building the cart, but required before booking — the connectors reject bookings without a contact phone."
}
},
"required": [
"travelers"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Set travelers on the trip. Replaces all existing travelers (idempotent operation)."
},
"schedule_quote": {
"type": "boolean",
"description": "Schedule a fresh quote on the current cart state. Triggers async re-pricing on the BFF; poll trip(get) until trip.quote_status is \"completed\", \"partial\", or \"failed\". Only \"completed\" covers the whole cart. trip.quoted_total is the quoted sell total; trip.totals includes unquoted search prices, and trip.status is a legacy lifecycle field. Call this AFTER any traveler or cart-composition change so subsequent steps see fresh prices. book(create) will silently re-quote if the cart drifted from the last quote."
},
"payment_type": {
"type": "string",
"enum": [
"checkout",
"intent"
],
"description": "Payment flow type: \"checkout\" for Stripe Checkout (default), \"intent\" for Payment Intent."
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "Idempotency key to prevent duplicate processing"
},
"user_intent": {
"type": "string",
"description": "A concise summary of what the user is trying to accomplish, derived from their message or the\nconversation context that triggered this tool call.\nThis is used to understand the user's intent and context to improve the overall user experience.\n\n- For short, self-contained prompts (e.g. \"I want new shoes\"), copy the user message as-is.\n- For longer conversations or detailed requests, summarize the core goal and any relevant\n context in 1-2 sentences. Focus on intent, constraints, and preferences - not the full\n dialogue.\n\nBefore sending, strip all personally identifiable information (PII), including but not\nlimited to:\n - Names (first, last, usernames, handles)\n - Email addresses\n - Phone numbers\n - Physical addresses (street, city, zip/postal code, country when tied to an individual)\n - Dates of birth or exact ages\n - Government-issued ID numbers (SSN, passport, driver's license, etc.)\n - Payment or financial information (card numbers, bank accounts, etc.)\n - IP addresses or device identifiers\n - Account credentials (passwords, tokens, API keys)\n - Health or biometric data\n - Any other information that could identify a specific individual\n\nReplace stripped values with a generic placeholder (e.g. \"[name]\", \"[email]\", \"[address]\").\n\nExamples:\n User: \"I want red running shoes under $100\"\n -> \"I want red running shoes under $100\"\n\n User: \"Hi, I'm John Smith, john@example.com, and I'm looking for flights from Paris to\n Tokyo for 2 adults departing around mid-June, budget around EUR2000 total\"\n -> \"Looking for flights from Paris to Tokyo for 2 adults, mid-June, budget ~EUR2000\"\n\n User: \"I need help resetting my password for account ID acct_12345\"\n -> \"I need help resetting my password for account ID [account_id]\""
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}