Tool description (what the LLM sees)
Tool description (what the LLM sees)
get_booking with booking_ref (and last_name for guests) returns items[] with servicing eligibility and refusal reasons for item selection. The same booking_ref + booked_item_id identifies the selected item on every action, including commit and status. booked_item_id is the stable booked item, even after an exchange. last_name is required for guests and optional for authenticated owners. A 409 with items[] means customer selection is needed; a retry identifies that choice with booked_item_id.
Cancel a hotel booking. CALL WITH ACTION PREVIEW FIRST, the preview costs nothing and cancels nothing.
WORKFLOW:
1. action="preview" with booking_ref + booked_item_id (plus last_name for guests) → penalty, customer refund, policy, and an "svq_…" quote handle.
2. Show the customer the refund and get their agreement.
3. action="commit" with the SAME auth you used to preview, quote_id="svq_…", and acknowledged = that quote's `refund` object copied field for field → returns an "svc_…" operation handle.
4. action="status" with operation="svc_…" → the supplier's answer and where the refund got to.
USAGE (guest, no login required):
hotel_cancel({ action: "preview", booking_ref: "JNK-A7B3X9", booked_item_id: "itm_aaaaaaaaaaaaafhuxsdxpbzrbfz5hm3a", last_name: "Doe" })
USAGE (authenticated owner):
hotel_cancel({ action: "preview", booking_ref: "JNK-A7B3X9", booked_item_id: "itm_aaaaaaaaaaaaafhuxsdxpbzrbfz5hm3a" })
IMPORTANT:
- Never commit without a preview: the customer must see the penalty and the refund first.
- `acknowledged` is the preview's `refund` object copied verbatim (value, currency, decimal_places), never recomputed. If the refund has moved since, the commit is refused and a fresh quote is returned, show that one to the customer rather than committing the old figure.
- When the preview reports the penalty is not known (`fee_known: false`), tell the customer we will confirm the amount. That is NOT free cancellation.
- Quote the customer refund and penalty returned by the preview.
- action="cancel" is the legacy one-shot path: it prices and cancels in a single call, so the customer cannot agree to the refund first. Use it only for callers already written against it.
Always start with `get_booking` and select the item before cancelling.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
action | enum ("preview" | "commit" | "status" | "cancel") | No | What to do. “preview” (default) prices the cancellation and returns a quote handle without cancelling anything, always start here so the customer sees the penalty and the refund before agreeing. “commit” cancels, using the quote handle and the refund the customer acknowledged. “status” reports where a committed cancellation and its refund got to. “cancel” (deprecated: use “preview” then “commit”) is the legacy one-shot path that quotes and cancels in a single call, with no chance to confirm the figures first. |
booking_ref | string | Yes | Trip-level Jinko booking_ref returned by get_trip or submit_agent_payment. Use it to look up the booking with get_booking. |
booked_item_id | string | null | No | The booked item to service: booked_item_id from get_booking.items[] (an “itm_…” string). Send it on every action. May be omitted only when the booking has exactly one item in this domain. |
last_name | string | null | No | Primary traveler last name. Required for guests; optional for an authenticated owner of the booking. |
quote_id | string | null | No | The “svq_…” handle a prior action “preview” returned. REQUIRED for action “commit”. It binds the cancellation to the figures the customer was shown. |
acknowledged | object | null | No | The preview’s refund object copied field for field, the refund the customer agreed to. REQUIRED for action “commit”. Do not recompute or re-scale it: the platform compares it against the live figure and refuses the commit with a fresh quote when they differ, rather than settling at a number nobody was shown. |
operation | string | null | No | The “svc_…” operation handle a prior action “commit” returned. REQUIRED for action “status”. |
user_intent | string | No | The end user’s current request in their own words, e.g. “help me with my travel plans”. Pass it as-is when short; otherwise condense the goal and constraints into 1-2 sentences. Strip personal identifiers (names, emails, phone numbers, addresses, payment details), replace them with placeholders like “[name]”. Optional. Jinko uses it to understand demand, and hotel_search uses it to rank hotel results against what the user asked for (e.g. “quiet, with a gym, near Times Square”), so keep the user’s stated preferences in it. |