Engine MCP — Tools for cursor
The tools Engine's MCP server offers to cursor. An assistant invokes a tool through the MCP protocol's tools/call request, passing the arguments listed against it.
Generated from Engine's tool registry.
https://mcp.engine.com/mcp
Tools 18 tools
DESTRUCTIVE lodging_book_cart Places the booking with a saved payment method.
Destructive — can delete data or make irreversible changes.
Places the booking with a saved payment method. Money moves. Books only for the signed-in member; never ask the user for a guest name or who is traveling. Only call after the user has seen the total and the cart's cancellation terms (summary.cancellationPolicy from lodging_create_cart; when summary.refundable is null, after they were given _handoff.finish_in_engine to review them) and explicitly said yes (userConfirmed). Waits for Engine's result: confirmed returns lodgingBookingNumber, an itinerary link, and a summary whose roomTitle is the booked room (ratePlanName is the supplier's rate-plan label, not the room). Every other answer is an error with _handoff links: not booked (failed, under review, needs verification or direct bill), or it may already be booked (booking_outcome_unknown, booking_in_progress, booking_rejected, cart_not_open; the user checks trips first, and never create a new cart; for the first two, lodging_get_booking_status reads from Engine whether that cart booked). After booking_rejected or cart_not_open, never call again. After booking_outcome_unknown or booking_in_progress, call again for the same cart only if the user, after checking trips, asks to retry and confirms the total again: Engine's state is checked before anything is sent. Do not call again after an answer unless the error says nothing was sent and its message allows it (total_changed, booking_cancelled, or a direct-bill refusal offering a card), and then only after the user confirms the total and payment again. The one other exception: payment_failed (or lodging_get_booking_status answering not_booked_retryable) means not booked and nothing charged: tell the user, follow lodging_list_payment_methods for the same cart, and book it again only after the user picks a payment method and confirms the total again. Never create a new cart to retry the same stay unless the error is cart_expired; otherwise give the user the _handoff links. Every error carries _handoff links to the Engine web app (the cart while it can still be booked, trips or the itinerary when it may be booked, the hotel when the cart cannot be used): give them to the user with any retry, and whenever they ask to retry. Whenever you give the user a link from _handoff (handoff, error recovery, or a companion link on a completed step), give each _handoff href exactly as returned, including every query parameter, and do not build, rewrite, or edit Engine links.
Arguments
| Name | Description |
|---|---|
cartId* requiredinteger
|
|
paymentProfileId* requiredstring
|
A method id from
|
paymentTypestring
|
|
confirmedTotal* requirednumber
|
The cart total you showed the user and they said yes to: |
propertyId* requiredinteger
|
for the
|
userConfirmed* requiredboolean
|
The user said yes to this exact cart and total. |
checkInstring
|
Prefilled in the link; only dates the
|
checkOutstring
|
Prefilled in the link; only dates the
|
guestCountinteger
|
Prefilled in the link; only builds the
|
roomCountinteger
|
Prefilled in the link; only builds the
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"cartId": 0,
"paymentProfileId": "string",
"paymentType": "card",
"confirmedTotal": 0,
"propertyId": 0,
"userConfirmed": true,
"checkIn": "string",
"checkOut": "string",
"guestCount": 1,
"roomCount": 1
},
"name": "lodging_book_cart"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"cartId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 999999999999,
"description": "`cart.id` from `lodging_create_cart`"
},
"paymentProfileId": {
"description": "A method id from `lodging_list_payment_methods` as a string (card ids are decimal digits; company direct bill is the literal `direct_bill`)",
"type": "string",
"pattern": "^([1-9][0-9]{0,11}|direct_bill)$"
},
"paymentType": {
"default": "card",
"type": "string",
"enum": [
"card",
"direct_bill"
]
},
"confirmedTotal": {
"type": "number",
"exclusiveMinimum": 0,
"description": "The cart total you showed the user and they said yes to: `summary.totalAmount` from `lodging_create_cart` or `cartTotal.amount` from `lodging_list_payment_methods`"
},
"propertyId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 999999999999,
"description": "for the `_handoff` link on failure"
},
"userConfirmed": {
"type": "boolean",
"const": true,
"description": "The user said yes to this exact cart and total."
},
"checkIn": {
"description": "Prefilled in the link; only dates the `_handoff` link if Engine cannot read the cart",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"checkOut": {
"description": "Prefilled in the link; only dates the `_handoff` link if Engine cannot read the cart",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"guestCount": {
"description": "Prefilled in the link; only builds the `_handoff` link",
"type": "integer",
"minimum": 1,
"maximum": 14
},
"roomCount": {
"description": "Prefilled in the link; only builds the `_handoff` link",
"type": "integer",
"minimum": 1,
"maximum": 8
}
},
"required": [
"cartId",
"paymentProfileId",
"confirmedTotal",
"propertyId",
"userConfirmed"
],
"additionalProperties": false
}Returns
{
"data": {
"state": "confirmed",
"cartId": 0,
"tripNumber": "string",
"lodgingBookingNumber": "string",
"propertyConfirmationNumber": "string",
"summary": {
"cartId": 0,
"status": "string",
"checkIn": "string",
"checkOut": "string",
"roomTitle": "string",
"ratePlanName": "string",
"total": "string",
"totalAmount": 0,
"dueAtProperty": "string",
"refundable": true,
"cancelBy": "string",
"cancellationPolicy": "string"
},
"traveler": {
"firstName": "string",
"lastName": "string"
}
},
"_links": {
"*": {
"tool": "string",
"href": "string",
"method": "GET",
"description": "string",
"body": {
"*": null
},
"required": [
"string"
]
}
},
"_handoff": {
"itinerary": {
"href": "string",
"description": "string"
}
}
}| data* | object{…}{
| ||||||||||||||||||||||||||||||||||||||||||
| _links* | object{…}{
| ||||||||||||||||||||||||||||||||||||||||||
| _handoff* | object{…}{
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"data": {
"type": "object",
"properties": {
"state": {
"type": "string",
"const": "confirmed"
},
"cartId": {
"type": "integer"
},
"tripNumber": {
"type": [
"string",
"null"
]
},
"lodgingBookingNumber": {
"type": "string"
},
"propertyConfirmationNumber": {
"type": [
"string",
"null"
]
},
"summary": {
"type": "object",
"properties": {
"cartId": {
"type": "integer"
},
"status": {
"type": "string"
},
"checkIn": {
"type": [
"string",
"null"
]
},
"checkOut": {
"type": [
"string",
"null"
]
},
"roomTitle": {
"description": "The room the user picked, from the cart; present this as the room.",
"type": [
"string",
"null"
]
},
"ratePlanName": {
"description": "The supplier's rate-plan name. Can differ from roomTitle; never present it as the room.",
"type": [
"string",
"null"
]
},
"total": {
"type": [
"string",
"null"
]
},
"totalAmount": {
"type": [
"number",
"null"
]
},
"dueAtProperty": {
"type": "string"
},
"refundable": {
"description": "Whether this cart can be cancelled for a full refund: true only while the free-cancellation deadline is more than 2 hours away. null when Engine sent no cancellation terms for the cart, which means unknown, not non-refundable.",
"type": [
"boolean",
"null"
]
},
"cancelBy": {
"description": "Free-cancellation deadline, an ISO 8601 date-time at the property's local UTC offset (taken from check-in), e.g. 2026-11-27T03:00:00-07:00; as Engine sent it when that offset is unknown. Present only when refundable is true.",
"type": "string"
},
"cancellationPolicy": {
"description": "Short cancellation terms to show the user, e.g. \"Free cancellation before <cancelBy>\" or \"Non-refundable\". Absent when refundable is null.",
"type": "string"
}
},
"required": [
"cartId",
"status",
"checkIn",
"checkOut",
"roomTitle",
"ratePlanName",
"total",
"totalAmount",
"refundable"
],
"additionalProperties": false
},
"traveler": {
"type": "object",
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
}
},
"required": [
"firstName",
"lastName"
],
"additionalProperties": false
}
},
"required": [
"state",
"cartId",
"tripNumber",
"lodgingBookingNumber",
"propertyConfirmationNumber",
"summary",
"traveler"
],
"additionalProperties": false
},
"_links": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
},
"_handoff": {
"type": "object",
"properties": {
"itinerary": {
"type": "object",
"properties": {
"href": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"href",
"description"
],
"additionalProperties": false
}
},
"required": [
"itinerary"
],
"additionalProperties": false
}
},
"required": [
"data",
"_links",
"_handoff"
],
"additionalProperties": false
}WRITE lodging_create_cart Locks a selected rate into a priced cart: totals, taxes, and cancellation terms (summary.refundable, summary.cancelBy, summary.cancellationPolicy).
Write — creates or changes data.
Locks a selected rate into a priced cart: totals, taxes, and cancellation terms (summary.refundable, summary.cancelBy, summary.cancellationPolicy). Books only for the signed-in member; never ask the user for a guest name or who is traveling. Follow the chosen rate's _links.lodging_create_cart link: pass rateToken exactly as returned (may be a short reference) and send rate, roomTitle, and the searched criteria unchanged (guestCount and roomCount included). A requires_approval, blocked, or not-bookable rate has no such link, only a _handoff: give the user that link instead of calling. When the chosen rate has the link, call this as soon as the user picks it, even if the rates response was saved to a file or the token is long: copy that rate's link body from the file. Never report a blocker before calling; it charges nothing, and a bad body returns an error that says what to do next. Returns either a cart (proceed to lodging_book_cart) or a _handoff when the agent cannot finish. More than one room or guest, or custom booking fields the company requires, still create the cart and hand off to its checkout page in Engine (optional booking fields do not block; the response names them); a rate that needs approval or that policy blocks hands off with no cart. If the price went up, this fails with price_changed and the new total, what is due now, and what is paid at the hotel: tell the user, and only if they accept, call this once more with the same body and the same rateToken; fresh rates show the old price and fail again. If travel policy now blocks the rate (rate_policy_blocked), do not retry; give the user the property link. Every error carries a _handoff link to the Engine web app: give it to the user with any retry, and whenever they ask to retry. Whenever you give the user a link from _handoff (handoff, error recovery, or a companion link on a completed step), give each _handoff href exactly as returned, including every query parameter, and do not build, rewrite, or edit Engine links.
Arguments
| Name | Description | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
propertyId* requiredinteger
|
|
||||||||||||||||||||||||||||||||
rateToken* requiredstring
|
From the rate's |
||||||||||||||||||||||||||||||||
rate* requiredobject
|
From the rate's {…}{
|
||||||||||||||||||||||||||||||||
roomTitle* requiredstring
|
|||||||||||||||||||||||||||||||||
roomDescriptionstring
|
|||||||||||||||||||||||||||||||||
criteria* requiredobject
|
The {…}{
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"propertyId": 0,
"rateToken": "string",
"rate": {
"id": 0,
"searchId": 0,
"sapiRateId": "string",
"outOfPolicy": true,
"violations": {
"travelPolicy": {
"isBookingAllowed": "allowed",
"incidentalsRequired": true,
"refundableRequired": true,
"maxDailyRate": {
"applicableMaxDailyRate": 0,
"exceedsRate": true
}
}
}
},
"roomTitle": "string",
"roomDescription": "string",
"criteria": {
"latitude": 0,
"longitude": 0,
"locationDescription": "string",
"checkIn": "string",
"checkOut": "string",
"roomCount": 1,
"guestCount": 1,
"radiusMiles": 0,
"locationKind": "address",
"requestedProperty": {
"name": "string",
"latitude": 0,
"longitude": 0,
"propertyId": 0
},
"types": [
"string"
],
"locationId": "string"
}
},
"name": "lodging_create_cart"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"propertyId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 999999999999
},
"rateToken": {
"type": "string",
"description": "From the rate's `lodging_create_cart` link; pass exactly as returned (may be a short reference)",
"x-engine/opaqueReference": {
"fromTool": "lodging_get_room_rates",
"fromResponse": "data.rooms[].rates[]._links.lodging_create_cart.body.rateToken"
}
},
"rate": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"searchId": {
"type": "number"
},
"sapiRateId": {
"type": [
"string",
"null"
]
},
"outOfPolicy": {
"type": "boolean"
},
"violations": {
"type": [
"object",
"null"
],
"anyOf": [
{
"type": "object",
"properties": {
"travelPolicy": {
"type": [
"object",
"null"
],
"anyOf": [
{
"type": "object",
"properties": {
"isBookingAllowed": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"enum": [
"allowed",
"requires_approval",
"blocked"
]
},
{
"type": "null"
}
]
},
"incidentalsRequired": {
"type": [
"boolean",
"null"
]
},
"refundableRequired": {
"type": [
"boolean",
"null"
]
},
"maxDailyRate": {
"type": [
"object",
"null"
],
"anyOf": [
{
"type": "object",
"properties": {
"applicableMaxDailyRate": {
"type": [
"number",
"null"
]
},
"exceedsRate": {
"type": "boolean"
}
},
"required": [
"exceedsRate"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"searchId",
"outOfPolicy"
],
"description": "From the rate's `lodging_create_cart` link; send it unchanged",
"additionalProperties": false
},
"roomTitle": {
"type": "string"
},
"roomDescription": {
"type": "string"
},
"criteria": {
"type": "object",
"properties": {
"latitude": {
"type": "number",
"description": "Latitude of the place the member asked to search, from `place.latitude` in `lodging_resolve_destination`. Never the member's device location."
},
"longitude": {
"type": "number",
"description": "Longitude of the place the member asked to search, from `place.longitude` in `lodging_resolve_destination`. Never the member's device location."
},
"locationDescription": {
"type": "string",
"description": "The place the member asked to search, as `place.locationDescription` from `lodging_resolve_destination` returned it (the address, led by the hotel name when the place is a hotel)."
},
"checkIn": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD. Resolve from the current date in the conversation or context. If the current date is not available, ask the user for the full date including the year rather than guessing."
},
"checkOut": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD. Resolve from the current date in the conversation or context. If the current date is not available, ask the user for the full date including the year rather than guessing."
},
"roomCount": {
"type": "integer",
"minimum": 1,
"maximum": 8,
"description": "Use 1 unless the user asks for more rooms. Do not ask. Send the count the user gave: more than 8 rooms is handed off to Engine Groups."
},
"guestCount": {
"type": "integer",
"minimum": 1,
"maximum": 14,
"description": "Use 1 unless the user mentions other people. Do not ask. Send the count the user gave: more than 14 guests is handed off to Engine Groups."
},
"radiusMiles": {
"description": "Search radius in miles around the location, max 50. Omit for the default; raise only when a search returns nothing.",
"type": "number",
"exclusiveMinimum": 0,
"maximum": 50
},
"locationKind": {
"description": "`place.locationKind` from `lodging_resolve_destination`; address searches show distance. Omit when unknown.",
"type": "string",
"enum": [
"address",
"area"
]
},
"requestedProperty": {
"description": "`place.requestedProperty` from `lodging_resolve_destination` when the user named a specific hotel, sent unchanged so that hotel is pinned at results[0]. Omit otherwise.",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"propertyId": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"name",
"latitude",
"longitude"
],
"additionalProperties": false
},
"types": {
"description": "Google place types from `place.types` in `lodging_resolve_destination`, sent to Members for sort determination. Omit when unknown.",
"type": "array",
"items": {
"type": "string"
}
},
"locationId": {
"description": "Google place id (`place.placeId`) from `lodging_resolve_destination`, sent to Members as locationId. Omit when unknown.",
"type": "string"
}
},
"required": [
"latitude",
"longitude",
"locationDescription",
"checkIn",
"checkOut",
"roomCount",
"guestCount"
],
"description": "The `lodging_get_room_rates` criteria, prefilled in the link",
"additionalProperties": false
}
},
"required": [
"propertyId",
"rateToken",
"rate",
"roomTitle",
"criteria"
],
"additionalProperties": false
}Returns
{
"data": {
"cart": {
"id": 0,
"status": "string",
"currency": "string",
"userId": 0,
"hasLodging": true
},
"summary": {
"cartId": 0,
"status": "string",
"checkIn": "string",
"checkOut": "string",
"roomTitle": "string",
"ratePlanName": "string",
"total": "string",
"totalAmount": 0,
"dueAtProperty": "string",
"refundable": true,
"cancelBy": "string",
"cancellationPolicy": "string",
"propertyId": 0,
"roomRateId": 0,
"guestCount": 0,
"roomCount": 0
},
"traveler": {
"firstName": "string",
"lastName": "string"
},
"handoff": true,
"reason": "string",
"detail": "string",
"optionalCustomFields": [
"string"
],
"next": "string"
},
"_links": {
"*": {
"tool": "string",
"href": "string",
"method": "GET",
"description": "string",
"body": {
"*": null
},
"required": [
"string"
]
}
},
"_handoff": {
"*": {
"href": "string",
"description": "string"
}
}
}| data* | object{…}{
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| _links* | object{…}{
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| _handoff | object{…}{
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"data": {
"type": "object",
"properties": {
"cart": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"userId": {
"type": "integer"
},
"hasLodging": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"currency",
"userId",
"hasLodging"
],
"additionalProperties": {}
},
"summary": {
"type": "object",
"properties": {
"cartId": {
"type": "integer"
},
"status": {
"type": "string"
},
"checkIn": {
"type": [
"string",
"null"
]
},
"checkOut": {
"type": [
"string",
"null"
]
},
"roomTitle": {
"description": "The room the user picked, from the cart; present this as the room.",
"type": [
"string",
"null"
]
},
"ratePlanName": {
"description": "The supplier's rate-plan name. Can differ from roomTitle; never present it as the room.",
"type": [
"string",
"null"
]
},
"total": {
"type": [
"string",
"null"
]
},
"totalAmount": {
"type": [
"number",
"null"
]
},
"dueAtProperty": {
"type": "string"
},
"refundable": {
"description": "Whether this cart can be cancelled for a full refund: true only while the free-cancellation deadline is more than 2 hours away. null when Engine sent no cancellation terms for the cart, which means unknown, not non-refundable.",
"type": [
"boolean",
"null"
]
},
"cancelBy": {
"description": "Free-cancellation deadline, an ISO 8601 date-time at the property's local UTC offset (taken from check-in), e.g. 2026-11-27T03:00:00-07:00; as Engine sent it when that offset is unknown. Present only when refundable is true.",
"type": "string"
},
"cancellationPolicy": {
"description": "Short cancellation terms to show the user, e.g. \"Free cancellation before <cancelBy>\" or \"Non-refundable\". Absent when refundable is null.",
"type": "string"
},
"propertyId": {
"type": "integer"
},
"roomRateId": {
"type": "integer"
},
"guestCount": {
"type": "integer"
},
"roomCount": {
"type": "integer"
}
},
"required": [
"cartId",
"status",
"checkIn",
"checkOut",
"roomTitle",
"ratePlanName",
"total",
"totalAmount",
"refundable",
"propertyId",
"roomRateId",
"guestCount",
"roomCount"
],
"additionalProperties": false
},
"traveler": {
"type": "object",
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
}
},
"required": [
"firstName",
"lastName"
],
"additionalProperties": false
},
"handoff": {
"type": "boolean"
},
"reason": {
"type": "string"
},
"detail": {
"type": "string"
},
"optionalCustomFields": {
"description": "Names of the company's optional booking fields. Booking here can go ahead without them; they are filled in only by finishing in the Engine web app via _handoff.finish_in_engine. Absent when there are none.",
"type": "array",
"items": {
"type": "string"
}
},
"next": {
"type": "string",
"description": "Instruction for the next call."
}
},
"required": [
"next"
],
"additionalProperties": false
},
"_links": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
},
"_handoff": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"href": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"href",
"description"
],
"additionalProperties": false
}
}
},
"required": [
"data",
"_links"
],
"additionalProperties": false
}READ lodging_get_booking Returns one booking by its G- booking number: hotel name, property confirmation number, dates, whether Flex was purchased, and its rooms.
Read-only — returns data and changes nothing.
Returns one booking by its G- booking number: hotel name, property confirmation number, dates, whether Flex was purchased, and its rooms. Call it before lodging_preview_cancellation or lodging_preview_shortening. It returns the contract numbers those tools require: child_bookings[].contract_number when present, otherwise the top-level contract_number. It also returns permissions for the booking and each room. The cancellation entry has authorized plus is_eligible and ineligibility_reason. authorized stays true for an authorized modifier even when the booking is already cancelled. is_eligible is then false and ineligibility_reason is "cancelled". ineligibility_reason is "not_cancellable_state" when the booking or room is completed or failed and can no longer be cancelled. A preview-cancellation template appears only when cancellation is authorized and eligible. check_in_shortening and check_out_shortening add is_eligible and deadline. guest_name_change adds is_eligible and ineligibility_reason. A preview-shortening template appears only when shortening is possible. Visibility: the MCP returns not found for an unknown booking and for any booking the member can't view. A member can view: - Admins: any booking on their business - Department managers: bookings they made, bookings for anyone in their department, and bookings made for them - Travel coordinators: bookings they made and bookings made for them. With coordinator dashboard access on, any booking on their business - Users: bookings they made and bookings made for them - View only travelers: bookings made for them The authorized flags cover changes only, not viewing. A view only traveler can't change any booking but can still look it up.
Arguments
| Name | Description |
|---|---|
booking_number* requiredstring
|
Booking number shown to the member, starting with G-, for example G-123456. Not a contract number.
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"booking_number": "string"
},
"name": "lodging_get_booking"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"booking_number": {
"type": "string",
"minLength": 1,
"description": "Booking number shown to the member, starting with G-, for example G-123456. Not a contract number."
}
},
"required": [
"booking_number"
]
}Returns
{
"_links": {
"*": {
"href": "string"
}
},
"_templates": {
"*": {
"title": "string",
"method": "DELETE",
"target": "string",
"contentType": "string",
"properties": [
{
"name": "string",
"type": "date",
"required": true,
"prompt": "string",
"value": "string"
}
]
}
},
"check_in": "string",
"check_out": "string",
"child_bookings": [
{
"check_in": "string",
"check_out": "string",
"contract_number": "string",
"permissions": {
"cancellation": {
"authorized": true,
"authorized_roles": [
"account_admin"
],
"ineligibility_reason": "string",
"is_eligible": true
},
"check_in_shortening": {
"authorized": true,
"authorized_roles": [
"account_admin"
],
"deadline": "string",
"is_eligible": true
},
"check_out_shortening": {
"authorized": true,
"authorized_roles": [
"account_admin"
],
"deadline": "string",
"is_eligible": true
},
"guest_name_change": {
"additional_guest_change_eligible": true,
"authorized": true,
"authorized_roles": [
"account_admin"
],
"ineligibility_reason": "cancelled",
"is_eligible": true,
"primary_guest_change_eligible": true
}
},
"property_confirmation_number": "string",
"property_name": "string"
}
],
"contract_number": "string",
"is_flex_covered": true,
"is_hotel_collect": true,
"permissions": {
"cancellation": {
"authorized": true,
"authorized_roles": [
"account_admin"
],
"ineligibility_reason": "string",
"is_eligible": true
},
"check_in_shortening": {
"authorized": true,
"authorized_roles": [
"account_admin"
],
"deadline": "string",
"is_eligible": true
},
"check_out_shortening": {
"authorized": true,
"authorized_roles": [
"account_admin"
],
"deadline": "string",
"is_eligible": true
},
"guest_name_change": {
"additional_guest_change_eligible": true,
"authorized": true,
"authorized_roles": [
"account_admin"
],
"ineligibility_reason": "cancelled",
"is_eligible": true,
"primary_guest_change_eligible": true
}
},
"property_confirmation_number": "string",
"property_name": "string"
}| _links | object HAL links, keyed by relation ( {…}{
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| _templates | object Next-step affordances: a {…}{
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| check_in* | string ISO-8601 datetime. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| check_out* | string ISO-8601 datetime. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| child_bookings* | object[] Per-room bookings under this booking reference. [{…}][{ ]
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| contract_number* | string The booking reference for the whole booking. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| is_flex_covered* | boolean Whether Flex was purchased for this booking. It does not mean the current cancellation is covered by Flex. lodging_preview_cancellation reports that. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| is_hotel_collect* | boolean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| permissions* | object{…}{
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| property_confirmation_number* | string | null | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| property_name* | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"required": [
"check_in",
"check_out",
"child_bookings",
"contract_number",
"is_flex_covered",
"is_hotel_collect",
"permissions",
"property_confirmation_number",
"property_name"
],
"properties": {
"_links": {
"type": "object",
"description": "HAL links, keyed by relation (`self` at minimum).",
"additionalProperties": {
"type": "object",
"description": "A HAL link.",
"required": [
"href"
],
"properties": {
"href": {
"type": "string",
"description": "Target of the link, relative to this API's base URL."
}
}
}
},
"_templates": {
"type": "object",
"description": "Next-step affordances: a `preview-shortening` template, offered when at least one shortening direction is currently possible on the booking or any of its child bookings. Each room in the form chooses its own direction; the `check_in_shortening` / `check_out_shortening` permissions stay authoritative for which directions and rooms qualify. No template means shortening is not currently possible. A `preview-cancellation` template is offered only when cancellation is authorized and is_eligible on the booking or any child room. No such template means cancellation is not currently possible.",
"additionalProperties": {
"type": "object",
"description": "A HAL-FORMS template describing the next step of a flow: the request to make and the inputs it takes. A response carrying no `_templates` is terminal — the flow is complete.",
"required": [
"method",
"target"
],
"properties": {
"title": {
"type": "string",
"description": "Human-readable name of the step."
},
"method": {
"type": "string",
"description": "HTTP method to use.",
"enum": [
"DELETE",
"GET",
"PATCH",
"POST",
"PUT"
]
},
"target": {
"type": "string",
"description": "URI of the step, relative to this API's base URL. `{name}` placeholders are filled from the property values and removed from the request body."
},
"contentType": {
"type": "string",
"description": "Media type of the request body, when one is sent."
},
"properties": {
"type": "array",
"items": {
"type": "object",
"description": "One input of a HAL-FORMS template. A `value` marks a server-provided (hidden) input the consumer sends back verbatim; a required property without a `value` must be collected from the caller, guided by `prompt`.",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Field name to use in the request."
},
"type": {
"type": "string",
"description": "Input type of the field.",
"enum": [
"date",
"hidden",
"json",
"number",
"text"
]
},
"required": {
"type": "boolean",
"description": "Whether the field must be present when executing the template."
},
"prompt": {
"type": "string",
"description": "Human-readable description of what to collect."
},
"value": {
"type": "string",
"description": "Server-provided value to send back verbatim."
}
}
},
"description": "Inputs of the step."
}
}
}
},
"check_in": {
"type": "string",
"description": "ISO-8601 datetime."
},
"check_out": {
"type": "string",
"description": "ISO-8601 datetime."
},
"child_bookings": {
"type": "array",
"description": "Per-room bookings under this booking reference.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"check_in",
"check_out",
"contract_number",
"permissions",
"property_confirmation_number",
"property_name"
],
"properties": {
"check_in": {
"type": "string",
"description": "ISO-8601 datetime."
},
"check_out": {
"type": "string",
"description": "ISO-8601 datetime."
},
"contract_number": {
"type": "string",
"description": "The per-room contract number."
},
"permissions": {
"type": "object",
"additionalProperties": false,
"required": [
"cancellation",
"check_in_shortening",
"check_out_shortening",
"guest_name_change"
],
"properties": {
"cancellation": {
"type": "object",
"description": "Whether the calling user may cancel, and whether the booking itself can be cancelled now. authorized stays true for an authorized modifier even when the booking is already cancelled. is_eligible is then false and ineligibility_reason is \"cancelled\".",
"additionalProperties": false,
"required": [
"authorized",
"authorized_roles",
"ineligibility_reason",
"is_eligible"
],
"properties": {
"authorized": {
"type": "boolean",
"description": "Whether the calling user may cancel."
},
"authorized_roles": {
"type": "array",
"description": "Roles permitted to cancel.",
"items": {
"type": "string",
"description": "A role permitted to perform a modification.",
"enum": [
"account_admin",
"booker",
"traveler"
]
}
},
"ineligibility_reason": {
"type": [
"string",
"null"
],
"description": "Why cancellation is not eligible, or null when eligible. Already-cancelled rooms use \"cancelled\". Completed or failed bookings and rooms use \"not_cancellable_state\". Additional reason strings may be added without a schema change."
},
"is_eligible": {
"type": "boolean",
"description": "Whether the booking itself can be cancelled now, independent of the caller. Stays false when the room is already cancelled even if authorized is true."
}
}
},
"check_in_shortening": {
"type": "object",
"additionalProperties": false,
"required": [
"authorized",
"authorized_roles",
"deadline",
"is_eligible"
],
"properties": {
"authorized": {
"type": "boolean",
"description": "Whether the calling user may perform this modification."
},
"authorized_roles": {
"type": "array",
"description": "Roles permitted to perform this modification.",
"items": {
"type": "string",
"description": "A role permitted to perform a modification.",
"enum": [
"account_admin",
"booker",
"traveler"
]
}
},
"deadline": {
"type": [
"string",
"null"
],
"description": "Cutoff after which the modification is no longer eligible, or null when none applies."
},
"is_eligible": {
"type": "boolean",
"description": "Whether the booking itself is eligible for this modification, independent of the caller."
}
}
},
"check_out_shortening": {
"type": "object",
"additionalProperties": false,
"required": [
"authorized",
"authorized_roles",
"deadline",
"is_eligible"
],
"properties": {
"authorized": {
"type": "boolean",
"description": "Whether the calling user may perform this modification."
},
"authorized_roles": {
"type": "array",
"description": "Roles permitted to perform this modification.",
"items": {
"type": "string",
"description": "A role permitted to perform a modification.",
"enum": [
"account_admin",
"booker",
"traveler"
]
}
},
"deadline": {
"type": [
"string",
"null"
],
"description": "Cutoff after which the modification is no longer eligible, or null when none applies."
},
"is_eligible": {
"type": "boolean",
"description": "Whether the booking itself is eligible for this modification, independent of the caller."
}
}
},
"guest_name_change": {
"type": "object",
"additionalProperties": false,
"required": [
"additional_guest_change_eligible",
"authorized",
"authorized_roles",
"ineligibility_reason",
"is_eligible",
"primary_guest_change_eligible"
],
"properties": {
"additional_guest_change_eligible": {
"type": "boolean"
},
"authorized": {
"type": "boolean"
},
"authorized_roles": {
"type": "array",
"items": {
"type": "string",
"description": "A role permitted to perform a modification.",
"enum": [
"account_admin",
"booker",
"traveler"
]
}
},
"ineligibility_reason": {
"type": [
"string",
"null"
],
"description": "Why a guest name change is not eligible, or null when eligible.",
"enum": [
"cancelled",
"loyalty_required",
"not_supported",
"past_check_in",
"same_day",
"supplier_unsupported",
null
]
},
"is_eligible": {
"type": "boolean"
},
"primary_guest_change_eligible": {
"type": "boolean"
}
}
}
}
},
"property_confirmation_number": {
"type": [
"string",
"null"
]
},
"property_name": {
"type": "string"
}
}
}
},
"contract_number": {
"type": "string",
"description": "The booking reference for the whole booking."
},
"is_flex_covered": {
"type": "boolean",
"description": "Whether Flex was purchased for this booking. It does not mean the current cancellation is covered by Flex. lodging_preview_cancellation reports that."
},
"is_hotel_collect": {
"type": "boolean"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"required": [
"cancellation",
"check_in_shortening",
"check_out_shortening",
"guest_name_change"
],
"properties": {
"cancellation": {
"type": "object",
"description": "Whether the calling user may cancel, and whether the booking itself can be cancelled now. authorized stays true for an authorized modifier even when the booking is already cancelled. is_eligible is then false and ineligibility_reason is \"cancelled\".",
"additionalProperties": false,
"required": [
"authorized",
"authorized_roles",
"ineligibility_reason",
"is_eligible"
],
"properties": {
"authorized": {
"type": "boolean",
"description": "Whether the calling user may cancel."
},
"authorized_roles": {
"type": "array",
"description": "Roles permitted to cancel.",
"items": {
"type": "string",
"description": "A role permitted to perform a modification.",
"enum": [
"account_admin",
"booker",
"traveler"
]
}
},
"ineligibility_reason": {
"type": [
"string",
"null"
],
"description": "Why cancellation is not eligible, or null when eligible. Already-cancelled rooms use \"cancelled\". Completed or failed bookings and rooms use \"not_cancellable_state\". Additional reason strings may be added without a schema change."
},
"is_eligible": {
"type": "boolean",
"description": "Whether the booking itself can be cancelled now, independent of the caller. Stays false when the room is already cancelled even if authorized is true."
}
}
},
"check_in_shortening": {
"type": "object",
"additionalProperties": false,
"required": [
"authorized",
"authorized_roles",
"deadline",
"is_eligible"
],
"properties": {
"authorized": {
"type": "boolean",
"description": "Whether the calling user may perform this modification."
},
"authorized_roles": {
"type": "array",
"description": "Roles permitted to perform this modification.",
"items": {
"type": "string",
"description": "A role permitted to perform a modification.",
"enum": [
"account_admin",
"booker",
"traveler"
]
}
},
"deadline": {
"type": [
"string",
"null"
],
"description": "Cutoff after which the modification is no longer eligible, or null when none applies."
},
"is_eligible": {
"type": "boolean",
"description": "Whether the booking itself is eligible for this modification, independent of the caller."
}
}
},
"check_out_shortening": {
"type": "object",
"additionalProperties": false,
"required": [
"authorized",
"authorized_roles",
"deadline",
"is_eligible"
],
"properties": {
"authorized": {
"type": "boolean",
"description": "Whether the calling user may perform this modification."
},
"authorized_roles": {
"type": "array",
"description": "Roles permitted to perform this modification.",
"items": {
"type": "string",
"description": "A role permitted to perform a modification.",
"enum": [
"account_admin",
"booker",
"traveler"
]
}
},
"deadline": {
"type": [
"string",
"null"
],
"description": "Cutoff after which the modification is no longer eligible, or null when none applies."
},
"is_eligible": {
"type": "boolean",
"description": "Whether the booking itself is eligible for this modification, independent of the caller."
}
}
},
"guest_name_change": {
"type": "object",
"additionalProperties": false,
"required": [
"additional_guest_change_eligible",
"authorized",
"authorized_roles",
"ineligibility_reason",
"is_eligible",
"primary_guest_change_eligible"
],
"properties": {
"additional_guest_change_eligible": {
"type": "boolean"
},
"authorized": {
"type": "boolean"
},
"authorized_roles": {
"type": "array",
"items": {
"type": "string",
"description": "A role permitted to perform a modification.",
"enum": [
"account_admin",
"booker",
"traveler"
]
}
},
"ineligibility_reason": {
"type": [
"string",
"null"
],
"description": "Why a guest name change is not eligible, or null when eligible.",
"enum": [
"cancelled",
"loyalty_required",
"not_supported",
"past_check_in",
"same_day",
"supplier_unsupported",
null
]
},
"is_eligible": {
"type": "boolean"
},
"primary_guest_change_eligible": {
"type": "boolean"
}
}
}
}
},
"property_confirmation_number": {
"type": [
"string",
"null"
]
},
"property_name": {
"type": "string"
}
}
}READ lodging_get_booking_status Reads whether a cart's booking went through, from Engine, after lodging_book_cart answered booking_outcome_unknown or booking_in_progress.
Read-only — returns data and changes nothing.
Reads whether a cart's booking went through, from Engine, after lodging_book_cart answered booking_outcome_unknown or booking_in_progress. Call it only from those answers' links, with the cartId they name. Books nothing and changes nothing. state is booked (give the user the itinerary link), not_booked_retryable (nothing was booked; the same cart can be booked once the user picks a payment method and confirms the total again), not_booked_final (not booked; this cart cannot be booked here), or in_progress (Engine has not confirmed either way: it may already be booked, so book nothing and have the user check trips). What the user says never changes state; follow next.
Arguments
| Name | Description |
|---|---|
cartId* requiredinteger
|
The cart a
|
propertyIdinteger
|
The cart's hotel, from the link that offered this tool; for the next links and the Engine handoff
|
checkInstring
|
Prefilled in the link; only dates the
|
checkOutstring
|
Prefilled in the link; only dates the
|
guestCountinteger
|
Prefilled in the link; only builds the
|
roomCountinteger
|
Prefilled in the link; only builds the
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"cartId": 0,
"propertyId": 0,
"checkIn": "string",
"checkOut": "string",
"guestCount": 1,
"roomCount": 1
},
"name": "lodging_get_booking_status"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"cartId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 999999999999,
"description": "The cart a `lodging_book_cart` answer named (`cart.id` from `lodging_create_cart`)"
},
"propertyId": {
"description": "The cart's hotel, from the link that offered this tool; for the next links and the Engine handoff",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 999999999999
},
"checkIn": {
"description": "Prefilled in the link; only dates the `_handoff` link",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"checkOut": {
"description": "Prefilled in the link; only dates the `_handoff` link",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"guestCount": {
"description": "Prefilled in the link; only builds the `_handoff` link",
"type": "integer",
"minimum": 1,
"maximum": 14
},
"roomCount": {
"description": "Prefilled in the link; only builds the `_handoff` link",
"type": "integer",
"minimum": 1,
"maximum": 8
}
},
"additionalProperties": false,
"required": [
"cartId"
]
}Returns
{
"data": {
"state": "booked",
"cartId": 0,
"propertyId": 0,
"tripNumber": "string",
"lodgingBookingNumber": "string",
"propertyConfirmationNumber": "string",
"cart": "ready",
"errorType": "string",
"displayMessage": "string",
"next": "string"
},
"_links": {
"*": {
"tool": "string",
"href": "string",
"method": "GET",
"description": "string",
"body": {
"*": null
},
"required": [
"string"
]
}
},
"_handoff": {
"*": {
"href": "string",
"description": "string"
}
}
}| data* | object{…}{
| ||||||||||||||||||||
| _links* | object{…}{
| ||||||||||||||||||||
| _handoff | object{…}{
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"data": {
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"booked",
"not_booked_retryable",
"not_booked_final",
"in_progress"
]
},
"cartId": {
"type": "integer"
},
"propertyId": {
"description": "Echoed from the request, for the payment-methods call.",
"type": "integer"
},
"tripNumber": {
"type": [
"string",
"null"
]
},
"lodgingBookingNumber": {
"type": "string"
},
"propertyConfirmationNumber": {
"type": [
"string",
"null"
]
},
"cart": {
"description": "What Engine shows for the cart when not booked: ready can still be finished in Engine; failed and expired cannot.",
"type": "string",
"enum": [
"ready",
"failed",
"expired"
]
},
"errorType": {
"type": [
"string",
"null"
]
},
"displayMessage": {
"type": [
"string",
"null"
]
},
"next": {
"type": "string",
"description": "Instruction for the next call."
}
},
"required": [
"state",
"cartId",
"next"
],
"additionalProperties": false
},
"_links": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
},
"_handoff": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"href": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"href",
"description"
],
"additionalProperties": false
}
}
},
"required": [
"data",
"_links"
],
"additionalProperties": false
}READ lodging_get_current_user Confirms who is booking: first name, last name, email.
Read-only — returns data and changes nothing.
Confirms who is booking: first name, last name, email. Call first. The current user is the only traveler supported.
Arguments
Takes no arguments.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "lodging_get_current_user"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"additionalProperties": false
}Returns
{
"data": {
"firstName": "string",
"lastName": "string",
"email": "string",
"engineRewardsVisible": true,
"next": "string"
},
"_links": {
"*": {
"tool": "string",
"href": "string",
"method": "GET",
"description": "string",
"body": {
"*": null
},
"required": [
"string"
]
}
},
"_handoff": {
"*": {
"href": "string",
"description": "string"
}
}
}| data* | object{…}{
| ||||||||||||||||
| _links* | object{…}{
| ||||||||||||||||
| _handoff | object{…}{
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"data": {
"type": "object",
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"email": {
"type": "string"
},
"engineRewardsVisible": {
"type": "boolean",
"description": "True when Engine Rewards applies to this member's bookings here: enrolled, and the business lets them see rewards. Search and rate rows then carry doubleRewards; when false the field is absent and 2x rewards is never mentioned. False does not mean the member is not enrolled (the business may have opted out or pool points), so never tell the member they are not a rewards member."
},
"next": {
"type": "string",
"description": "Instruction for the next call."
}
},
"required": [
"firstName",
"lastName",
"email",
"engineRewardsVisible",
"next"
],
"additionalProperties": false
},
"_links": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
},
"_handoff": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"href": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"href",
"description"
],
"additionalProperties": false
}
}
},
"required": [
"data",
"_links"
],
"additionalProperties": false
}READ lodging_get_room_rates Live rooms and rates for one property.
Read-only — returns data and changes nothing.
Live rooms and rates for one property. Follow a search row's lodging_get_room_rates link; it carries roomOffersToken (pass exactly as returned; may be a short reference) and search criteria. Each rate has price, cancellation terms, and policy: allowed, requires_approval, or blocked. blocked rates cannot be selected. requires_approval rates cannot be booked here. Only allowed rates carry a _links.lodging_create_cart; the others carry a _handoff to the Engine web app. Returns at most 5 room types, in-policy first, then cheapest first, always including a room type with a refundable rate when the hotel has one; roomTypesTotal says how many the hotel has, and _handoff.open_property_in_engine shows them all. Show rates as numbered text entries, never a table. Lead with hotel.name and up to 2 of hotel.amenities.primary; when hotel is absent, lead with the hotel name from the earlier search results. Then one flat numbered list with one entry per rate, each written as N. where N is its index, in index order, with no room headings or sub-lists between entries; a room with several rates repeats its title. Each entry: first N., the room title, and features.beds; then together price.nightlyBase per night (before taxes and fees), the nightly saving price.saveAmount (was price.strikeNightly) only when price has it, and price.total for the stay (includes taxes and fees); then refundable or not, and up to 2 of the rate's features and the room's other features. The user may pick by number ("3", "#3", "the 3rd one"); that always means the rate whose index is 3. Keep hotel.amenities.other, room amenities, and the other displayFields secondary values for follow-up questions instead of listing them. Keep this layout and each rate's index when you narrow or re-sort; if the shown numbers no longer run 1, 2, 3 in order, start each entry with Rate N. instead so the client does not renumber them. Whenever you give the user a link from _handoff (handoff, error recovery, or a companion link on a completed step), give each _handoff href exactly as returned, including every query parameter, and do not build, rewrite, or edit Engine links.
Arguments
| Name | Description | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
propertyId* requiredinteger
|
|
||||||||||||||||||||||||||||||||
roomOffersToken* requiredstring
|
From the |
||||||||||||||||||||||||||||||||
criteria* requiredobject
|
The {…}{
|
||||||||||||||||||||||||||||||||
hotelobject
|
From the {…}{
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"propertyId": 0,
"roomOffersToken": "string",
"criteria": {
"latitude": 0,
"longitude": 0,
"locationDescription": "string",
"checkIn": "string",
"checkOut": "string",
"roomCount": 1,
"guestCount": 1,
"radiusMiles": 0,
"locationKind": "address",
"requestedProperty": {
"name": "string",
"latitude": 0,
"longitude": 0,
"propertyId": 0
},
"types": [
"string"
],
"locationId": "string"
},
"hotel": {
"name": "string",
"amenities": {
"primary": [
"breakfast"
],
"other": [
"breakfast"
]
}
}
},
"name": "lodging_get_room_rates"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"propertyId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 999999999999
},
"roomOffersToken": {
"type": "string",
"description": "From the `lodging_search_hotels` row's link; pass exactly as returned (may be a short reference)",
"x-engine/opaqueReference": {
"fromTool": "lodging_search_hotels",
"fromResponse": "data.results[]._links.lodging_get_room_rates.body.roomOffersToken"
}
},
"criteria": {
"type": "object",
"properties": {
"latitude": {
"type": "number",
"description": "Latitude of the place the member asked to search, from `place.latitude` in `lodging_resolve_destination`. Never the member's device location."
},
"longitude": {
"type": "number",
"description": "Longitude of the place the member asked to search, from `place.longitude` in `lodging_resolve_destination`. Never the member's device location."
},
"locationDescription": {
"type": "string",
"description": "The place the member asked to search, as `place.locationDescription` from `lodging_resolve_destination` returned it (the address, led by the hotel name when the place is a hotel)."
},
"checkIn": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD. Resolve from the current date in the conversation or context. If the current date is not available, ask the user for the full date including the year rather than guessing."
},
"checkOut": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD. Resolve from the current date in the conversation or context. If the current date is not available, ask the user for the full date including the year rather than guessing."
},
"roomCount": {
"type": "integer",
"minimum": 1,
"maximum": 8,
"description": "Use 1 unless the user asks for more rooms. Do not ask. Send the count the user gave: more than 8 rooms is handed off to Engine Groups."
},
"guestCount": {
"type": "integer",
"minimum": 1,
"maximum": 14,
"description": "Use 1 unless the user mentions other people. Do not ask. Send the count the user gave: more than 14 guests is handed off to Engine Groups."
},
"radiusMiles": {
"description": "Search radius in miles around the location, max 50. Omit for the default; raise only when a search returns nothing.",
"type": "number",
"exclusiveMinimum": 0,
"maximum": 50
},
"locationKind": {
"description": "`place.locationKind` from `lodging_resolve_destination`; address searches show distance. Omit when unknown.",
"type": "string",
"enum": [
"address",
"area"
]
},
"requestedProperty": {
"description": "`place.requestedProperty` from `lodging_resolve_destination` when the user named a specific hotel, sent unchanged so that hotel is pinned at results[0]. Omit otherwise.",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"propertyId": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"name",
"latitude",
"longitude"
],
"additionalProperties": false
},
"types": {
"description": "Google place types from `place.types` in `lodging_resolve_destination`, sent to Members for sort determination. Omit when unknown.",
"type": "array",
"items": {
"type": "string"
}
},
"locationId": {
"description": "Google place id (`place.placeId`) from `lodging_resolve_destination`, sent to Members as locationId. Omit when unknown.",
"type": "string"
}
},
"required": [
"latitude",
"longitude",
"locationDescription",
"checkIn",
"checkOut",
"roomCount",
"guestCount"
],
"description": "The `lodging_search_hotels` criteria this row came from",
"additionalProperties": false
},
"hotel": {
"description": "From the `lodging_search_hotels` row's link; send it unchanged. Returned as `hotel` so the rates can lead with the hotel's amenities.",
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 200
},
"amenities": {
"type": "object",
"properties": {
"primary": {
"type": "array",
"items": {
"type": "string",
"enum": [
"breakfast",
"parking",
"wifi"
]
}
},
"other": {
"type": "array",
"items": {
"type": "string",
"enum": [
"breakfast",
"parking",
"wifi",
"fitnessCenter",
"swimmingPool",
"petFriendly",
"shuttle",
"kitchen",
"airConditioning",
"truckParking"
]
}
}
},
"required": [
"primary",
"other"
],
"additionalProperties": false
}
},
"required": [
"name",
"amenities"
],
"additionalProperties": false
}
},
"required": [
"propertyId",
"roomOffersToken",
"criteria"
],
"additionalProperties": false
}Returns
{
"data": {
"propertyId": 0,
"hotel": {
"name": "string",
"amenities": {
"primary": [
"breakfast"
],
"other": [
"string"
]
}
},
"criteria": {
"locationDescription": "string",
"latitude": 0,
"longitude": 0,
"radiusMiles": 0,
"checkIn": "string",
"checkOut": "string",
"roomCount": 0,
"guestCount": 0,
"locationKind": "address",
"requestedProperty": {
"name": "string",
"latitude": 0,
"longitude": 0,
"propertyId": 0
}
},
"priceChange": "decrease",
"displayFields": {
"room": {
"primary": [
"string"
],
"secondary": [
"string"
]
},
"rate": {
"primary": [
"string"
],
"secondary": [
"string"
]
}
},
"rooms": [
{
"roomIndex": 0,
"title": "string",
"features": {
"beds": "string",
"wifi": true,
"view": true,
"kitchen": true,
"accessible": true,
"balcony": true,
"bathtub": true
},
"description": "string",
"amenities": [
"string"
],
"beddings": [
{
"type": "string",
"count": 0
}
],
"rates": [
{
"index": 0,
"id": 0,
"price": {
"nightlyBase": 0,
"total": 0,
"currency": "string",
"taxesAndFees": 0,
"strikeNightly": 0,
"saveAmount": 0,
"savePercent": 0
},
"refundable": true,
"cancelBy": "string",
"cancellationPolicy": "string",
"features": {
"breakfast": true,
"parking": true
},
"policy": "allowed",
"numNights": 0,
"numRooms": 0,
"nightlyRates": [
{
"date": "string",
"rate": 0
}
],
"hotelCollect": true,
"isMemberRate": true,
"isPayLater": true,
"loyaltyEligible": true,
"doubleRewards": true,
"outOfPolicy": true,
"includedAmenities": {
"breakfast": 0,
"parking": 0
},
"ratePlan": "string",
"_links": {
"lodging_create_cart": {
"tool": "string",
"href": "string",
"method": "GET",
"description": "string",
"body": {
"propertyId": 0,
"rateToken": "string",
"rate": {
"id": 0,
"searchId": 0,
"sapiRateId": "string",
"outOfPolicy": true,
"violations": null
},
"roomTitle": "string",
"roomDescription": "string",
"criteria": {
"locationDescription": "string",
"latitude": 0,
"longitude": 0,
"radiusMiles": 0,
"checkIn": "string",
"checkOut": "string",
"roomCount": 0,
"guestCount": 0,
"locationKind": "address",
"requestedProperty": {
"name": null,
"latitude": null,
"longitude": null,
"propertyId": null
}
}
},
"required": [
"string"
]
}
},
"_handoff": {
"*": {
"href": "string",
"description": "string"
}
}
}
]
}
],
"roomTypesShown": 0,
"roomTypesTotal": 0,
"refundableRoomTypesHidden": 0,
"next": "string"
},
"_links": {
"*": {
"tool": "string",
"href": "string",
"method": "GET",
"description": "string",
"body": {
"*": null
},
"required": [
"string"
]
}
},
"_handoff": {
"*": {
"href": "string",
"description": "string"
}
}
}| data* | object{…}{
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| _links* | object{…}{
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| _handoff | object{…}{
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"data": {
"type": "object",
"properties": {
"propertyId": {
"type": "integer"
},
"hotel": {
"description": "Echoed from the lodging_search_hotels row link; absent when the call did not come from a search row.",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"amenities": {
"type": "object",
"properties": {
"primary": {
"type": "array",
"items": {
"type": "string",
"enum": [
"breakfast",
"parking",
"wifi"
]
},
"description": "Free breakfast, free parking, free wifi, when offered."
},
"other": {
"type": "array",
"items": {
"type": "string"
},
"description": "Other offered amenities from a fixed set (fitnessCenter, swimmingPool, petFriendly, shuttle, kitchen, airConditioning, truckParking); not exhaustive. For follow-up questions."
}
},
"required": [
"primary",
"other"
],
"additionalProperties": false
}
},
"required": [
"name",
"amenities"
],
"additionalProperties": false
},
"criteria": {
"type": "object",
"properties": {
"locationDescription": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"radiusMiles": {
"type": "number"
},
"checkIn": {
"type": "string"
},
"checkOut": {
"type": "string"
},
"roomCount": {
"type": "integer"
},
"guestCount": {
"type": "integer"
},
"locationKind": {
"type": "string",
"enum": [
"address",
"area"
]
},
"requestedProperty": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"propertyId": {
"type": "integer"
}
},
"required": [
"name",
"latitude",
"longitude"
],
"additionalProperties": false
}
},
"required": [
"locationDescription",
"latitude",
"longitude",
"checkIn",
"checkOut",
"roomCount",
"guestCount"
],
"additionalProperties": false,
"description": "The search these rates came from; send it to lodging_search_hotels to re-run."
},
"priceChange": {
"type": "string",
"enum": [
"decrease",
"increase",
"none"
]
},
"displayFields": {
"type": "object",
"properties": {
"room": {
"type": "object",
"properties": {
"primary": {
"type": "array",
"items": {
"type": "string"
}
},
"secondary": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"primary",
"secondary"
],
"additionalProperties": false,
"description": "Dotted paths into each row. Show primary in every entry, in this order; keep secondary for follow-up questions."
},
"rate": {
"type": "object",
"properties": {
"primary": {
"type": "array",
"items": {
"type": "string"
}
},
"secondary": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"primary",
"secondary"
],
"additionalProperties": false,
"description": "Dotted paths into each row. Show primary in every entry, in this order; keep secondary for follow-up questions."
}
},
"required": [
"room",
"rate"
],
"additionalProperties": false,
"description": "Dotted paths into each room and each rate: primary holds what an entry is built from (next says how to show it); keep secondary for follow-up questions."
},
"rooms": {
"type": "array",
"items": {
"type": "object",
"properties": {
"roomIndex": {
"type": "integer",
"description": "1-based, in response order."
},
"title": {
"type": "string"
},
"features": {
"type": "object",
"properties": {
"beds": {
"description": "From beddings, e.g. \"1 King\".",
"type": "string"
},
"wifi": {
"type": "boolean",
"const": true
},
"view": {
"type": "boolean",
"const": true
},
"kitchen": {
"type": "boolean",
"const": true
},
"accessible": {
"type": "boolean",
"const": true
},
"balcony": {
"type": "boolean",
"const": true
},
"bathtub": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false,
"description": "Fixed feature set mapped from beddings and the supplier amenity text; unmatched text stays in amenities. A feature that is absent is unknown, not unavailable: never tell the user the room lacks it (no wifi, no view); say it is not listed, or check amenities."
},
"description": {
"type": "string"
},
"amenities": {
"description": "Supplier amenity text; for follow-up questions.",
"type": "array",
"items": {
"type": "string"
}
},
"beddings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"count": {
"type": "number"
}
},
"additionalProperties": false
}
},
"rates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"description": "1-based across all rooms in this response; shown as `N.` and the number the user picks by."
},
"id": {
"type": "integer"
},
"price": {
"type": "object",
"properties": {
"nightlyBase": {
"description": "Nightly rate before taxes and fees; null with total.",
"type": [
"number",
"null"
]
},
"total": {
"description": "Stay total, taxes and fees included; null with nightlyBase.",
"type": [
"number",
"null"
]
},
"currency": {
"description": "Omitted when the backend sent none: show the amounts without a currency, never guess one.",
"type": "string"
},
"taxesAndFees": {
"description": "Stay taxes and fees, when the tool knows them.",
"type": "number"
},
"strikeNightly": {
"description": "Nightly price before the saving. Present with saveAmount.",
"type": "number"
},
"saveAmount": {
"description": "Nightly saving. Omitted when there is none worth showing (under 5 and under 10%) or the rate is a negotiated program rate.",
"type": "number"
},
"savePercent": {
"description": "Nightly saving in whole percent. Only with saveAmount, and omitted when it cannot be known or rounds to 0.",
"type": "integer"
}
},
"required": [
"nightlyBase",
"total"
],
"additionalProperties": false
},
"refundable": {
"type": "boolean",
"description": "True only while cancelBy, the free-cancellation deadline, is more than 2 hours ahead."
},
"cancelBy": {
"type": "string"
},
"cancellationPolicy": {
"type": "string"
},
"features": {
"type": "object",
"properties": {
"breakfast": {
"type": "boolean"
},
"parking": {
"type": "boolean"
}
},
"additionalProperties": false,
"description": "Included with this rate (true) or not (false); omitted when unknown, which never means not included."
},
"policy": {
"type": "string",
"enum": [
"allowed",
"requires_approval",
"blocked"
]
},
"numNights": {
"type": "integer"
},
"numRooms": {
"type": "integer"
},
"nightlyRates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"rate": {
"type": "number"
}
},
"required": [
"date",
"rate"
],
"additionalProperties": false
}
},
"hotelCollect": {
"type": "boolean"
},
"isMemberRate": {
"type": "boolean"
},
"isPayLater": {
"type": "boolean"
},
"loyaltyEligible": {
"description": "This rate earns points in the hotel's own loyalty program. Name it from loyaltyProgram on this hotel's search row; when that row is no longer in context, say 'hotel loyalty program points' and never guess the program from the brand. Not Engine Rewards. Absent on every rate when the member's business does not use hotel loyalty programs.",
"type": "boolean"
},
"doubleRewards": {
"description": "True: this rate earns 2x Engine Rewards points. False: standard Engine Rewards. Absent on every rate when Engine Rewards does not apply to this member (engineRewardsVisible on lodging_get_current_user); then never mention 2x rewards.",
"type": "boolean"
},
"outOfPolicy": {
"type": "boolean"
},
"includedAmenities": {
"description": "As LSS sent it; omitted when LSS sent none. features holds the reading.",
"type": "object",
"properties": {
"breakfast": {
"description": "0 unknown, 1 unavailable, 2 available.",
"type": "integer"
},
"parking": {
"description": "0 unknown, 1 unavailable, 2 available.",
"type": "integer"
}
},
"additionalProperties": false
},
"ratePlan": {
"type": "string"
},
"_links": {
"description": "lodging_create_cart, fully prefilled with this rate's own rateToken, on allowed rates only.",
"type": "object",
"properties": {
"lodging_create_cart": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"properties": {
"propertyId": {
"type": "integer"
},
"rateToken": {
"type": "string",
"x-engine/opaqueReference": true
},
"rate": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"searchId": {
"type": "number"
},
"sapiRateId": {
"type": [
"string",
"null"
]
},
"outOfPolicy": {
"type": "boolean"
},
"violations": {
"type": [
"object",
"null"
],
"anyOf": [
{
"type": "object",
"properties": {
"travelPolicy": {
"type": [
"object",
"null"
],
"anyOf": [
{
"type": "object",
"properties": {
"isBookingAllowed": {
"type": [
"string",
"null"
],
"anyOf": [
{
"type": "string",
"enum": [
"allowed",
"requires_approval",
"blocked"
]
},
{
"type": "null"
}
]
},
"incidentalsRequired": {
"type": [
"boolean",
"null"
]
},
"refundableRequired": {
"type": [
"boolean",
"null"
]
},
"maxDailyRate": {
"type": [
"object",
"null"
],
"anyOf": [
{
"type": "object",
"properties": {
"applicableMaxDailyRate": {
"type": [
"number",
"null"
]
},
"exceedsRate": {
"type": "boolean"
}
},
"required": [
"exceedsRate"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"searchId",
"outOfPolicy"
],
"additionalProperties": false
},
"roomTitle": {
"type": "string"
},
"roomDescription": {
"type": "string"
},
"criteria": {
"type": "object",
"properties": {
"locationDescription": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"radiusMiles": {
"type": "number"
},
"checkIn": {
"type": "string"
},
"checkOut": {
"type": "string"
},
"roomCount": {
"type": "integer"
},
"guestCount": {
"type": "integer"
},
"locationKind": {
"type": "string",
"enum": [
"address",
"area"
]
},
"requestedProperty": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"propertyId": {
"type": "integer"
}
},
"required": [
"name",
"latitude",
"longitude"
],
"additionalProperties": false
}
},
"required": [
"locationDescription",
"latitude",
"longitude",
"checkIn",
"checkOut",
"roomCount",
"guestCount"
],
"additionalProperties": false
}
},
"required": [
"propertyId",
"rateToken",
"rate",
"roomTitle",
"criteria"
],
"additionalProperties": false
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
},
"additionalProperties": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
},
"_handoff": {
"description": "Engine web app link on requires_approval and blocked rates, and on any rate LSS sent without a token.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"href": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"href",
"description"
],
"additionalProperties": false
}
}
},
"required": [
"index",
"id",
"price",
"refundable",
"features",
"policy",
"numNights",
"numRooms",
"nightlyRates",
"hotelCollect",
"isMemberRate",
"isPayLater",
"outOfPolicy"
],
"additionalProperties": false
}
}
},
"required": [
"roomIndex",
"title",
"features",
"rates"
],
"additionalProperties": false
},
"description": "At most 5 room types, in-policy first, then cheapest first, as the Engine web app lists them; the last slot goes to the cheapest room type with a bookable refundable rate when the five cheapest have none."
},
"roomTypesShown": {
"type": "integer"
},
"roomTypesTotal": {
"type": "integer",
"description": "Room types the hotel offers; the ones beyond roomTypesShown are in _handoff.open_property_in_engine."
},
"refundableRoomTypesHidden": {
"type": "integer",
"description": "Unlisted room types that have a bookable refundable rate; the shown five always include one when the hotel has any."
},
"next": {
"type": "string",
"description": "Instruction for the next call."
}
},
"required": [
"propertyId",
"criteria",
"priceChange",
"displayFields",
"rooms",
"roomTypesShown",
"roomTypesTotal",
"refundableRoomTypesHidden",
"next"
],
"additionalProperties": false
},
"_links": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
},
"_handoff": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"href": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"href",
"description"
],
"additionalProperties": false
}
}
},
"required": [
"data",
"_links"
],
"additionalProperties": false
}READ lodging_list_payment_methods Lists this member's saved cards (including Engine X) and company direct bill.
Read-only — returns data and changes nothing.
Lists this member's saved cards (including Engine X) and company direct bill. Propose recommendedId when set, then confirm the chosen method with the member before booking. New cards are added in Engine; never accept a card number. At most 10 cards are listed (the default card always is); hiddenCardCount says how many more the member can pick in Engine via _handoff.finish_in_engine. If none are usable, give the member the _handoff.finish_in_engine link when present to continue their booking there; otherwise follow _links. With a cartId, every answer carries that cart's _handoff.finish_in_engine: on an error, give it to the user with any retry, and whenever they ask to retry. Whenever you give the user a link from _handoff (handoff, error recovery, or a companion link on a completed step), give each _handoff href exactly as returned, including every query parameter, and do not build, rewrite, or edit Engine links.
Arguments
| Name | Description |
|---|---|
cartIdinteger
|
When set, each usable method links to
|
propertyIdinteger
|
Required with
|
checkInstring
|
Stay check-in (YYYY-MM-DD) from
|
checkOutstring
|
Stay check-out (YYYY-MM-DD) from
|
guestCountinteger
|
The guestCount this cart was created with (prefilled by
|
roomCountinteger
|
The roomCount this cart was created with (prefilled by
|
roomRateIdinteger
|
rate.id this cart was created for, from
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"cartId": 0,
"propertyId": 0,
"checkIn": "string",
"checkOut": "string",
"guestCount": 1,
"roomCount": 1,
"roomRateId": 0
},
"name": "lodging_list_payment_methods"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"cartId": {
"description": "When set, each usable method links to `lodging_book_cart` for this cart",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 999999999999
},
"propertyId": {
"description": "Required with `cartId`, for the book-page handoff when no method is usable",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 999999999999
},
"checkIn": {
"description": "Stay check-in (YYYY-MM-DD) from `lodging_search_hotels` or `lodging_create_cart`, for the members handoff",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"checkOut": {
"description": "Stay check-out (YYYY-MM-DD) from `lodging_search_hotels` or `lodging_create_cart`, for the members handoff",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"guestCount": {
"description": "The guestCount this cart was created with (prefilled by `lodging_create_cart`). Only builds the members handoff.",
"type": "integer",
"minimum": 1,
"maximum": 14
},
"roomCount": {
"description": "The roomCount this cart was created with (prefilled by `lodging_create_cart`). Only builds the members handoff.",
"type": "integer",
"minimum": 1,
"maximum": 8
},
"roomRateId": {
"description": "rate.id this cart was created for, from `lodging_create_cart`",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 999999999999
}
},
"additionalProperties": false
}Returns
{
"data": {
"methods": [
{
"id": 0,
"label": "string",
"type": "string",
"lastFour": "string",
"isDefault": true,
"isExpired": true,
"isEngineX": true,
"_links": {
"*": {
"tool": "string",
"href": "string",
"method": "GET",
"description": "string",
"body": {
"*": null
},
"required": [
"string"
]
}
}
}
],
"usableCount": 0,
"recommendedId": 0,
"hiddenCardCount": 0,
"cartTotal": {
"amount": 0,
"currency": "string"
},
"next": "string"
},
"_links": {
"*": {
"tool": "string",
"href": "string",
"method": "GET",
"description": "string",
"body": {
"*": null
},
"required": [
"string"
]
}
},
"_handoff": {
"*": {
"href": "string",
"description": "string"
}
}
}| data* | object{…}{
| ||||||||||||||||||||||||||||||||||||||||||||
| _links* | object{…}{
| ||||||||||||||||||||||||||||||||||||||||||||
| _handoff | object{…}{
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"data": {
"type": "object",
"properties": {
"methods": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
],
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
]
},
"label": {
"type": "string"
},
"type": {
"type": "string"
},
"lastFour": {
"type": "string"
},
"isDefault": {
"type": "boolean"
},
"isExpired": {
"type": "boolean"
},
"isEngineX": {
"type": "boolean"
},
"_links": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"label",
"type",
"isDefault",
"isExpired",
"isEngineX"
],
"additionalProperties": false
}
},
"usableCount": {
"type": "integer"
},
"recommendedId": {
"type": [
"integer",
"string",
"null"
],
"anyOf": [
{
"type": [
"integer",
"string"
],
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
]
},
{
"type": "null"
}
]
},
"hiddenCardCount": {
"type": "integer"
},
"cartTotal": {
"type": [
"object",
"null"
],
"anyOf": [
{
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"currency": {
"type": "string"
}
},
"required": [
"amount",
"currency"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"next": {
"type": "string",
"description": "Instruction for the next call."
}
},
"required": [
"methods",
"usableCount",
"recommendedId",
"hiddenCardCount",
"next"
],
"additionalProperties": false
},
"_links": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
},
"_handoff": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"href": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"href",
"description"
],
"additionalProperties": false
}
}
},
"required": [
"data",
"_links"
],
"additionalProperties": false
}READ lodging_preview_cancellation Prices the cancellation of one or more rooms on a booking.
Read-only — returns data and changes nothing.
Prices the cancellation of one or more rooms on a booking. Call lodging_get_booking first for the contract numbers. Returns the refund total and destinations, any penalty, per-room amounts, whether Flex covers the penalty, and the continuation_token that lodging_submit_cancellation requires. refund is null when no refund is issued, such as on a pay-later booking. Call lodging_submit_cancellation only after the member has seen these terms and confirmed. BOOKING_ALREADY_CANCELLED means a selected room is cancelled. NOT_CANCELLABLE_STATE means the stay is completed or failed; do not call lodging_submit_cancellation; tell the member, or hand off to support.
Arguments
| Name | Description | ||
|---|---|---|---|
booking_number* requiredstring
|
G- booking number from lodging_get_booking or the member. Not a contract number.
|
||
rooms* requiredobject[]
|
One entry per room to cancel. List each contract number once.
[{…}][{ ]
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"booking_number": "string",
"rooms": [
{
"contract_number": "string"
}
]
},
"name": "lodging_preview_cancellation"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"booking_number": {
"type": "string",
"minLength": 1,
"description": "G- booking number from lodging_get_booking or the member. Not a contract number."
},
"rooms": {
"type": "array",
"minItems": 1,
"description": "One entry per room to cancel. List each contract number once.",
"items": {
"type": "object",
"properties": {
"contract_number": {
"type": "string",
"minLength": 1,
"description": "Room contract number from lodging_get_booking: child_bookings[].contract_number when present, otherwise the top-level contract_number. Not the G- booking number."
}
},
"required": [
"contract_number"
]
}
}
},
"required": [
"booking_number",
"rooms"
]
}Returns
{
"_links": {
"*": {
"href": "string"
}
},
"booking_number": "string",
"continuation_token": "string",
"is_flex_covered": true,
"penalty": {
"amount": {
"amount": "string",
"currency": "string"
},
"is_flex_covered": true,
"nights_penalty": 0
},
"refund": {
"total": {
"amount": "string",
"currency": "string"
},
"methods": [
{
"type": "credit_card",
"amount": {
"amount": "string",
"currency": "string"
}
}
]
},
"rooms": [
{
"contract_number": "string",
"refund_total": {
"amount": "string",
"currency": "string"
},
"penalty": {
"amount": "string",
"currency": "string"
}
}
]
}| _links | object HAL links. The preview response is affordance-terminal — it carries no {…}{
| ||||||||||||||||
| booking_number* | string The booking the preview is for. | ||||||||||||||||
| continuation_token* | string Opaque token identifying exactly this previewed plan. Always present; pass it back unchanged to | ||||||||||||||||
| is_flex_covered* | boolean True only when the cancellation window in effect right now is a Flex window. False inside the hotel's own free-cancellation window, even on a Flex booking, because the refund there comes from the hotel policy, not Flex. Also false after the Flex cutoff. | ||||||||||||||||
| penalty* | object | null Cancellation penalty for the selected rooms, or null when there is none. {…}{
| ||||||||||||||||
| refund* | object | null Refund for the selected rooms, or null when no refund is issued (for example, a pay-later booking). {…}{
| ||||||||||||||||
| rooms* | object[] Per-room breakdown: one entry per selected room, in request order. [{…}][{ ]
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"required": [
"booking_number",
"continuation_token",
"is_flex_covered",
"penalty",
"refund",
"rooms"
],
"properties": {
"_links": {
"type": "object",
"description": "HAL links. The preview response is affordance-terminal — it carries no `_templates`. Commit the preview by calling `lodging_submit_cancellation` with the `continuation_token` from this response.",
"additionalProperties": {
"type": "object",
"description": "A HAL link.",
"required": [
"href"
],
"properties": {
"href": {
"type": "string",
"description": "Target of the link, relative to this API's base URL."
}
}
}
},
"booking_number": {
"type": "string",
"description": "The booking the preview is for."
},
"continuation_token": {
"type": "string",
"description": "Opaque token identifying exactly this previewed plan. Always present; pass it back unchanged to `lodging_submit_cancellation`."
},
"is_flex_covered": {
"type": "boolean",
"description": "True only when the cancellation window in effect right now is a Flex window. False inside the hotel's own free-cancellation window, even on a Flex booking, because the refund there comes from the hotel policy, not Flex. Also false after the Flex cutoff."
},
"penalty": {
"description": "Cancellation penalty for the selected rooms, or null when there is none.",
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"amount",
"is_flex_covered",
"nights_penalty"
],
"properties": {
"amount": {
"description": "Penalty amount for the selected rooms.",
"type": "object",
"additionalProperties": false,
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"description": "Decimal amount as a string (e.g. \"150.00\")."
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code (e.g. \"USD\")."
}
}
},
"is_flex_covered": {
"type": "boolean",
"description": "Whether Flex coverage absorbs the penalty."
},
"nights_penalty": {
"type": [
"integer",
"null"
],
"description": "Number of nights the penalty is based on, or null when it is not night-based."
}
}
},
"refund": {
"description": "Refund for the selected rooms, or null when no refund is issued (for example, a pay-later booking).",
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"total",
"methods"
],
"properties": {
"total": {
"description": "Total refund across all destinations.",
"type": "object",
"additionalProperties": false,
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"description": "Decimal amount as a string (e.g. \"150.00\")."
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code (e.g. \"USD\")."
}
}
},
"methods": {
"type": "array",
"description": "Refund destinations with a positive amount. A destination receiving nothing is omitted.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"amount"
],
"properties": {
"type": {
"type": "string",
"enum": [
"credit_card",
"direct_bill",
"reward_points",
"travel_credits"
],
"description": "Where this part of the refund goes."
},
"amount": {
"description": "Amount refunded to this destination. Always positive.",
"type": "object",
"additionalProperties": false,
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"description": "Decimal amount as a string (e.g. \"150.00\")."
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code (e.g. \"USD\")."
}
}
}
}
}
}
}
},
"rooms": {
"type": "array",
"description": "Per-room breakdown: one entry per selected room, in request order.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"contract_number",
"refund_total",
"penalty"
],
"properties": {
"contract_number": {
"type": "string",
"description": "The room's contract number, as sent in the request."
},
"refund_total": {
"description": "Refund for this room. Null exactly when the top-level `refund` is null (no refund is issued, e.g. a pay-later booking), so \"no refund\" stays distinct from a zero refund.",
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"description": "Decimal amount as a string (e.g. \"150.00\")."
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code (e.g. \"USD\")."
}
}
},
"penalty": {
"description": "This room's share of the top-level penalty, before any Flex coverage, or null when the room bears none. The shares sum to `penalty.amount`.",
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"description": "Decimal amount as a string (e.g. \"150.00\")."
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code (e.g. \"USD\")."
}
}
}
}
}
}
}
}READ lodging_preview_shortening Prices a later check-in or earlier check-out for one or more rooms on a booking.
Read-only — returns data and changes nothing.
Prices a later check-in or earlier check-out for one or more rooms on a booking. Each room moves one date, not both. Call lodging_get_booking first for the contract numbers, shortening permissions, and deadlines. Returns the refund total, refund type, per-room refund amounts, Flex coverage, is_refundable, and the continuation_token that lodging_submit_shortening requires. Call lodging_submit_shortening only after the member has seen these terms and confirmed. When a room can't be shortened, the MCP returns UNPROCESSABLE_SHORTENING with a reason per room, such as FLEX_CUTOFF_PASSED, NOT_SHORTENABLE, REFUND_WINDOW_PASSED, or SINGLE_NIGHT_BOOKING.
Arguments
| Name | Description | ||||||
|---|---|---|---|---|---|---|---|
booking_number* requiredstring
|
G- booking number from lodging_get_booking or the member. Not a contract number.
|
||||||
rooms* requiredobject[]
|
One entry per room to shorten. Each entry sets check_in_date or check_out_date, not both.
[{…}][{ ]
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"booking_number": "string",
"rooms": [
{
"contract_number": "string",
"check_in_date": "string",
"check_out_date": "string"
}
]
},
"name": "lodging_preview_shortening"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"booking_number": {
"type": "string",
"minLength": 1,
"description": "G- booking number from lodging_get_booking or the member. Not a contract number."
},
"rooms": {
"type": "array",
"minItems": 1,
"description": "One entry per room to shorten. Each entry sets check_in_date or check_out_date, not both.",
"items": {
"type": "object",
"properties": {
"contract_number": {
"type": "string",
"minLength": 1,
"description": "Room contract number from lodging_get_booking: child_bookings[].contract_number when present, otherwise the top-level contract_number. Not the G- booking number."
},
"check_in_date": {
"type": "string",
"minLength": 1,
"description": "New check-in date as YYYY-MM-DD. Must be later than the current check-in. Omit when check_out_date is set."
},
"check_out_date": {
"type": "string",
"minLength": 1,
"description": "New check-out date as YYYY-MM-DD. Must be earlier than the current check-out. Omit when check_in_date is set."
}
},
"required": [
"contract_number"
]
}
}
},
"required": [
"booking_number",
"rooms"
]
}Returns
{
"_links": {
"*": {
"href": "string"
}
},
"calculated_refund": {
"amount_refundable": "string",
"credit_card_refundable": "string",
"direct_bill_refundable": "string",
"refund_type": "original_form_of_payment",
"reward_points_dollar_refundable": "string",
"room_calculations": {
"*": {
"credit_card_refundable": "string",
"direct_bill_refundable": "string",
"refund_type": "original_form_of_payment",
"refundable_amount": "string",
"reward_points_dollar_refundable": "string",
"travel_credit_refundable": "string"
}
},
"travel_credit_refundable": "string"
},
"continuation_token": "string",
"is_flex_covered": true,
"is_hotel_collect": true,
"is_refundable": true
}| _links | object HAL links. The preview response is affordance-terminal — it carries no {…}{
| ||||||||||||||||||||||||||||
| calculated_refund* | object{…}{
| ||||||||||||||||||||||||||||
| continuation_token* | string Opaque token used to commit this preview via | ||||||||||||||||||||||||||||
| is_flex_covered* | boolean | ||||||||||||||||||||||||||||
| is_hotel_collect* | boolean | ||||||||||||||||||||||||||||
| is_refundable* | boolean |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"required": [
"calculated_refund",
"continuation_token",
"is_flex_covered",
"is_hotel_collect",
"is_refundable"
],
"properties": {
"_links": {
"type": "object",
"description": "HAL links. The preview response is affordance-terminal — it carries no `_templates`. Commit the preview by calling `lodging_submit_shortening` with the `continuation_token` from this response (on the gateway wire, that is the discovery root's `submit-shortening` template).",
"additionalProperties": {
"type": "object",
"description": "A HAL link.",
"required": [
"href"
],
"properties": {
"href": {
"type": "string",
"description": "Target of the link, relative to this API's base URL."
}
}
}
},
"calculated_refund": {
"type": "object",
"additionalProperties": false,
"required": [
"amount_refundable",
"credit_card_refundable",
"direct_bill_refundable",
"refund_type",
"reward_points_dollar_refundable",
"room_calculations",
"travel_credit_refundable"
],
"properties": {
"amount_refundable": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
},
"credit_card_refundable": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
},
"direct_bill_refundable": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
},
"refund_type": {
"type": "string",
"enum": [
"original_form_of_payment",
"travel_credit"
]
},
"reward_points_dollar_refundable": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
},
"room_calculations": {
"type": "object",
"description": "Per-room refund breakdown, keyed by the room's contract number.",
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"required": [
"credit_card_refundable",
"direct_bill_refundable",
"refund_type",
"refundable_amount",
"reward_points_dollar_refundable",
"travel_credit_refundable"
],
"properties": {
"credit_card_refundable": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
},
"direct_bill_refundable": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
},
"refund_type": {
"type": "string",
"enum": [
"original_form_of_payment",
"travel_credit"
]
},
"refundable_amount": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
},
"reward_points_dollar_refundable": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
},
"travel_credit_refundable": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
}
}
}
},
"travel_credit_refundable": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
}
}
},
"continuation_token": {
"type": "string",
"description": "Opaque token used to commit this preview via `lodging_submit_shortening`. Pass it through unchanged; it is single-use and time-limited."
},
"is_flex_covered": {
"type": "boolean"
},
"is_hotel_collect": {
"type": "boolean"
},
"is_refundable": {
"type": "boolean"
}
}
}READ lodging_resolve_destination Resolves the place the member wants to stay near: a city, street address, ZIP code, venue, or landmark.
Read-only — returns data and changes nothing.
Resolves the place the member wants to stay near: a city, street address, ZIP code, venue, or landmark. For "near me", use the coarse location the client shares (city or area) as the query. The location is always one the member named or asked about in the conversation: a city, address, ZIP, venue, landmark, or, for "near me", the coarse location the client already shares (city or area). Never request, infer, or guess the member's precise device or GPS location; Engine does not read it. Call with a query to get up to three predictions and a sessionToken. If the intended place is evident, call again with that prediction's placeId and the response's sessionToken (each prediction's _links has this prefilled); if several could match, ask the user which; if none match, ask for a new query and call again. The selected place returns coordinates and locationKind for lodging_search_hotels. When the place is itself a hotel, place.requestedProperty names it; send it to lodging_search_hotels unchanged so that hotel is pinned at results[0]. Saved favorites and phrases like 'the office' are not supported.
Arguments
| Name | Description |
|---|---|
querystring
|
City, street address, ZIP code, venue, or landmark. For "near me", send the coarse location the client shares (city or area). Omit when following a
|
placeIdstring
|
From a
|
sessionTokenstring
|
From a
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "string",
"placeId": "string",
"sessionToken": "string"
},
"name": "lodging_resolve_destination"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"query": {
"description": "City, street address, ZIP code, venue, or landmark. For \"near me\", send the coarse location the client shares (city or area). Omit when following a `lodging_resolve_destination_N` link.",
"type": "string",
"minLength": 2
},
"placeId": {
"description": "From a `lodging_resolve_destination_N` link",
"type": "string",
"minLength": 1
},
"sessionToken": {
"description": "From a `lodging_resolve_destination_N` link",
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}Returns
{
"data": {
"query": "string",
"sessionToken": "string",
"predictions": [
{
"placeId": "string",
"label": "string",
"types": [
"string"
],
"_links": {
"*": {
"tool": "string",
"href": "string",
"method": "GET",
"description": "string",
"body": {
"*": null
},
"required": [
"string"
]
}
}
}
],
"ambiguous": true,
"place": {
"placeId": "string",
"latitude": 0,
"longitude": 0,
"formattedAddress": "string",
"types": [
"string"
],
"locationKind": "address",
"requestedProperty": {
"name": "string",
"latitude": 0,
"longitude": 0,
"propertyId": 0
},
"locationDescription": "string"
},
"next": "string"
},
"_links": {
"*": {
"tool": "string",
"href": "string",
"method": "GET",
"description": "string",
"body": {
"*": null
},
"required": [
"string"
]
}
},
"_handoff": {
"*": {
"href": "string",
"description": "string"
}
}
}| data* | object{…}{
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| _links* | object{…}{
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| _handoff | object{…}{
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"data": {
"type": "object",
"properties": {
"query": {
"type": "string"
},
"sessionToken": {
"description": "Send with the chosen prediction's placeId to resolve it.",
"type": "string"
},
"predictions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"placeId": {
"type": "string"
},
"label": {
"type": "string"
},
"types": {
"type": "array",
"items": {
"type": "string"
}
},
"_links": {
"description": "lodging_resolve_destination prefilled with this row's placeId and the response's sessionToken.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
}
},
"required": [
"placeId",
"label"
],
"additionalProperties": false
}
},
"ambiguous": {
"type": "boolean"
},
"place": {
"type": "object",
"properties": {
"placeId": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"formattedAddress": {
"type": "string"
},
"types": {
"type": "array",
"items": {
"type": "string"
}
},
"locationKind": {
"type": "string",
"enum": [
"address",
"area"
],
"description": "address for a street address, venue, or landmark; area for a city, region, or ZIP. Send it to lodging_search_hotels."
},
"requestedProperty": {
"description": "Present when the place is itself a hotel. Send it to lodging_search_hotels unchanged so that hotel is pinned at results[0].",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"propertyId": {
"type": "integer"
}
},
"required": [
"name",
"latitude",
"longitude"
],
"additionalProperties": false
},
"locationDescription": {
"type": "string",
"description": "What to send lodging_search_hotels as locationDescription: the address, led by the hotel's name when the place is a hotel."
}
},
"required": [
"placeId",
"latitude",
"longitude",
"formattedAddress",
"locationKind",
"locationDescription"
],
"additionalProperties": false
},
"next": {
"type": "string",
"description": "Instruction for the next call."
}
},
"required": [
"next"
],
"additionalProperties": false
},
"_links": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
},
"_handoff": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"href": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"href",
"description"
],
"additionalProperties": false
}
}
},
"required": [
"data",
"_links"
],
"additionalProperties": false
}READ lodging_search_hotels Searches bookable hotels near the location the member asked to search, using the latitude, longitude, and locationDescription that lodging_resolve_destination returned for that place, plus dates, guestCount and roomCount.
Read-only — returns data and changes nothing.
Searches bookable hotels near the location the member asked to search, using the latitude, longitude, and locationDescription that lodging_resolve_destination returned for that place, plus dates, guestCount and roomCount. The location is always one the member named or asked about in the conversation: a city, address, ZIP, venue, landmark, or, for "near me", the coarse location the client already shares (city or area). Never request, infer, or guess the member's precise device or GPS location; Engine does not read it. Resolve relative dates from the current date in the context; if it is absent, ask the user for the year. Pass types and locationId (the placeId) from place in lodging_resolve_destination unchanged when present; omit them when absent. Returns up to 10 available, in-policy rows (trimmed) in Engine's recommendation order (rank 1 first), Engine's prediction of what this traveler wants based on their company's history and preferences. Never show rank numbers or scores. Present the top 3 to start and offer to narrow by price, distance, brand, rating, refundability, or amenities; filter the returned rows yourself, do not re-run the search unless dates, location, guests, or rooms change. Out-of-policy hotels are omitted and outOfPolicyCount says how many; mention it only if the user asks about a missing hotel or wants out-of-policy options, then send them to _handoff.open_search_in_engine to see and book those in Engine. hiddenInPolicyCount says how many in-policy hotels the row limit cut, so a missing hotel is not an unavailable one. requestedProperty (from lodging_resolve_destination) pins the named hotel at results[0] with requested: true and reports requestedProperty.status found or unavailable with a reason; never call a hotel unavailable unless that says so. Search takes 5 to 10 seconds. Each row's _links.lodging_get_room_rates is prefilled; criteria is also returned once at the top for re-runs. Show results as numbered text entries, never a table. Each entry: first the hotel name, starRating stars, and brand; then together price.nightlyBase per night (before taxes and fees), the nightly saving price.saveAmount (was price.strikeNightly) only when price has it, and price.total for the stay (includes taxes and fees); then guestRating with reviewCount, whether refundable rates are available (refundable is about the hotel, not this price), up to 2 of amenities.primary, and city, plus distance only when criteria.locationKind is address. Keep amenities.other and the other displayFields.secondary values for follow-up questions instead of listing them. Keep this layout when you narrow or re-sort. Whenever you give the user a link from _handoff (handoff, error recovery, or a companion link on a completed step), give each _handoff href exactly as returned, including every query parameter, and do not build, rewrite, or edit Engine links.
Arguments
| Name | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
latitude* requirednumber
|
Latitude of the place the member asked to search, from |
||||||||
longitude* requirednumber
|
Longitude of the place the member asked to search, from |
||||||||
locationDescription* requiredstring
|
The place the member asked to search, as |
||||||||
checkIn* requiredstring
|
YYYY-MM-DD. Resolve from the current date in the conversation or context. If the current date is not available, ask the user for the full date including the year rather than guessing.
|
||||||||
checkOut* requiredstring
|
YYYY-MM-DD. Resolve from the current date in the conversation or context. If the current date is not available, ask the user for the full date including the year rather than guessing.
|
||||||||
roomCount* requiredinteger
|
Use 1 unless the user asks for more rooms. Do not ask. Send the count the user gave: more than 8 rooms is handed off to Engine Groups.
|
||||||||
guestCount* requiredinteger
|
Use 1 unless the user mentions other people. Do not ask. Send the count the user gave: more than 14 guests is handed off to Engine Groups.
|
||||||||
radiusMilesnumber
|
Search radius in miles around the location, max 50. Omit for the default; raise only when a search returns nothing.
|
||||||||
locationKindstring
|
|
||||||||
requestedPropertyobject
|
{…}{
|
||||||||
typesstring[]
|
Google place types from |
||||||||
locationIdstring
|
Google place id ( |
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"latitude": 0,
"longitude": 0,
"locationDescription": "string",
"checkIn": "string",
"checkOut": "string",
"roomCount": 1,
"guestCount": 1,
"radiusMiles": 0,
"locationKind": "address",
"requestedProperty": {
"name": "string",
"latitude": 0,
"longitude": 0,
"propertyId": 0
},
"types": [
"string"
],
"locationId": "string"
},
"name": "lodging_search_hotels"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"latitude": {
"type": "number",
"description": "Latitude of the place the member asked to search, from `place.latitude` in `lodging_resolve_destination`. Never the member's device location."
},
"longitude": {
"type": "number",
"description": "Longitude of the place the member asked to search, from `place.longitude` in `lodging_resolve_destination`. Never the member's device location."
},
"locationDescription": {
"type": "string",
"description": "The place the member asked to search, as `place.locationDescription` from `lodging_resolve_destination` returned it (the address, led by the hotel name when the place is a hotel)."
},
"checkIn": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD. Resolve from the current date in the conversation or context. If the current date is not available, ask the user for the full date including the year rather than guessing."
},
"checkOut": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD. Resolve from the current date in the conversation or context. If the current date is not available, ask the user for the full date including the year rather than guessing."
},
"roomCount": {
"type": "integer",
"minimum": 1,
"maximum": 8,
"description": "Use 1 unless the user asks for more rooms. Do not ask. Send the count the user gave: more than 8 rooms is handed off to Engine Groups."
},
"guestCount": {
"type": "integer",
"minimum": 1,
"maximum": 14,
"description": "Use 1 unless the user mentions other people. Do not ask. Send the count the user gave: more than 14 guests is handed off to Engine Groups."
},
"radiusMiles": {
"description": "Search radius in miles around the location, max 50. Omit for the default; raise only when a search returns nothing.",
"type": "number",
"exclusiveMinimum": 0,
"maximum": 50
},
"locationKind": {
"description": "`place.locationKind` from `lodging_resolve_destination`; address searches show distance. Omit when unknown.",
"type": "string",
"enum": [
"address",
"area"
]
},
"requestedProperty": {
"description": "`place.requestedProperty` from `lodging_resolve_destination` when the user named a specific hotel, sent unchanged so that hotel is pinned at results[0]. Omit otherwise.",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"propertyId": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"required": [
"name",
"latitude",
"longitude"
],
"additionalProperties": false
},
"types": {
"description": "Google place types from `place.types` in `lodging_resolve_destination`, sent to Members for sort determination. Omit when unknown.",
"type": "array",
"items": {
"type": "string"
}
},
"locationId": {
"description": "Google place id (`place.placeId`) from `lodging_resolve_destination`, sent to Members as locationId. Omit when unknown.",
"type": "string"
}
},
"required": [
"latitude",
"longitude",
"locationDescription",
"checkIn",
"checkOut",
"roomCount",
"guestCount"
],
"additionalProperties": false
}Returns
{
"data": {
"searchId": "string",
"legacySearchId": 0,
"criteria": {
"locationDescription": "string",
"latitude": 0,
"longitude": 0,
"radiusMiles": 0,
"checkIn": "string",
"checkOut": "string",
"roomCount": 0,
"guestCount": 0,
"locationKind": "address",
"requestedProperty": {
"name": "string",
"latitude": 0,
"longitude": 0,
"propertyId": 0
}
},
"datesNormalized": {
"from": {
"checkIn": "string",
"checkOut": "string"
},
"to": {
"checkIn": "string",
"checkOut": "string"
}
},
"displayFields": {
"primary": [
"string"
],
"secondary": [
"string"
]
},
"results": [
{
"propertyId": 0,
"name": "string",
"starRating": 0,
"brand": "string",
"price": {
"nightlyBase": 0,
"total": 0,
"currency": "string",
"taxesAndFees": 0,
"strikeNightly": 0,
"saveAmount": 0,
"savePercent": 0
},
"guestRating": 0,
"reviewCount": 0,
"refundable": true,
"amenities": {
"primary": [
"breakfast"
],
"other": [
"string"
]
},
"city": "string",
"distance": 0,
"distanceUnit": "string",
"loyaltyEligible": true,
"loyaltyProgram": "string",
"doubleRewards": true,
"bookedBefore": true,
"policy": "in_policy",
"rank": 0,
"requested": true,
"_links": {
"lodging_get_room_rates": {
"tool": "string",
"href": "string",
"method": "GET",
"description": "string",
"body": {
"propertyId": 0,
"roomOffersToken": "string",
"criteria": {
"locationDescription": "string",
"latitude": 0,
"longitude": 0,
"radiusMiles": 0,
"checkIn": "string",
"checkOut": "string",
"roomCount": 0,
"guestCount": 0,
"locationKind": "address",
"requestedProperty": {
"name": "string",
"latitude": 0,
"longitude": 0,
"propertyId": 0
}
},
"hotel": {
"name": "string",
"amenities": {
"primary": [
"breakfast"
],
"other": [
"string"
]
}
}
},
"required": [
"string"
]
}
}
}
],
"total": 0,
"outOfPolicyCount": 0,
"hiddenInPolicyCount": 0,
"requestedProperty": {
"status": "found",
"name": "string",
"propertyId": 0,
"reason": "not_returned"
},
"noResultsReason": "international_restricted",
"notice": "string",
"next": "string"
},
"_links": {
"*": {
"tool": "string",
"href": "string",
"method": "GET",
"description": "string",
"body": {
"*": null
},
"required": [
"string"
]
}
},
"_handoff": {
"*": {
"href": "string",
"description": "string"
}
}
}| data* | object{…}{
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| _links* | object{…}{
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| _handoff | object{…}{
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"data": {
"type": "object",
"properties": {
"searchId": {
"type": "string"
},
"legacySearchId": {
"type": "integer"
},
"criteria": {
"type": "object",
"properties": {
"locationDescription": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"radiusMiles": {
"type": "number"
},
"checkIn": {
"type": "string"
},
"checkOut": {
"type": "string"
},
"roomCount": {
"type": "integer"
},
"guestCount": {
"type": "integer"
},
"locationKind": {
"type": "string",
"enum": [
"address",
"area"
]
},
"requestedProperty": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"propertyId": {
"type": "integer"
}
},
"required": [
"name",
"latitude",
"longitude"
],
"additionalProperties": false
}
},
"required": [
"locationDescription",
"latitude",
"longitude",
"checkIn",
"checkOut",
"roomCount",
"guestCount"
],
"additionalProperties": false
},
"datesNormalized": {
"description": "Present when a prior-year stay was moved into the current year; criteria holds the moved dates.",
"type": "object",
"properties": {
"from": {
"type": "object",
"properties": {
"checkIn": {
"type": "string"
},
"checkOut": {
"type": "string"
}
},
"required": [
"checkIn",
"checkOut"
],
"additionalProperties": false
},
"to": {
"type": "object",
"properties": {
"checkIn": {
"type": "string"
},
"checkOut": {
"type": "string"
}
},
"required": [
"checkIn",
"checkOut"
],
"additionalProperties": false
}
},
"required": [
"from",
"to"
],
"additionalProperties": false
},
"displayFields": {
"type": "object",
"properties": {
"primary": {
"type": "array",
"items": {
"type": "string"
}
},
"secondary": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"primary",
"secondary"
],
"additionalProperties": false,
"description": "Dotted paths into each row. Show primary in every entry, in this order; keep secondary for follow-up questions."
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"propertyId": {
"type": "integer"
},
"name": {
"type": "string"
},
"starRating": {
"type": [
"number",
"null"
]
},
"brand": {
"type": [
"string",
"null"
]
},
"price": {
"type": "object",
"properties": {
"nightlyBase": {
"description": "Nightly rate before taxes and fees; null with total.",
"type": [
"number",
"null"
]
},
"total": {
"description": "Stay total, taxes and fees included; null with nightlyBase.",
"type": [
"number",
"null"
]
},
"currency": {
"description": "Omitted when the backend sent none: show the amounts without a currency, never guess one.",
"type": "string"
},
"taxesAndFees": {
"description": "Stay taxes and fees, when the tool knows them.",
"type": "number"
},
"strikeNightly": {
"description": "Nightly price before the saving. Present with saveAmount.",
"type": "number"
},
"saveAmount": {
"description": "Nightly saving. Omitted when there is none worth showing (under 5 and under 10%) or the rate is a negotiated program rate.",
"type": "number"
},
"savePercent": {
"description": "Nightly saving in whole percent. Only with saveAmount, and omitted when it cannot be known or rounds to 0.",
"type": "integer"
}
},
"required": [
"nightlyBase",
"total"
],
"additionalProperties": false
},
"guestRating": {
"type": [
"number",
"null"
]
},
"reviewCount": {
"type": [
"number",
"null"
]
},
"refundable": {
"type": "boolean"
},
"amenities": {
"type": "object",
"properties": {
"primary": {
"type": "array",
"items": {
"type": "string",
"enum": [
"breakfast",
"parking",
"wifi"
]
},
"description": "Free breakfast, free parking, free wifi, when offered."
},
"other": {
"type": "array",
"items": {
"type": "string"
},
"description": "Other offered amenities from a fixed set (fitnessCenter, swimmingPool, petFriendly, shuttle, kitchen, airConditioning, truckParking); not exhaustive. For follow-up questions."
}
},
"required": [
"primary",
"other"
],
"additionalProperties": false
},
"city": {
"type": "string"
},
"distance": {
"type": "number",
"description": "From the searched location. Primary for an address search, secondary for an area search."
},
"distanceUnit": {
"type": "string"
},
"loyaltyEligible": {
"description": "At least one rate here earns points in the hotel's own loyalty program (loyaltyProgram); each rate's loyaltyEligible decides. Not Engine Rewards. Absent on every row when the member's business does not use hotel loyalty programs.",
"type": "boolean"
},
"loyaltyProgram": {
"description": "Name of the hotel's loyalty program, e.g. Marriott Bonvoy. Absent when the hotel has none; never infer it from the brand.",
"type": "string"
},
"doubleRewards": {
"description": "True: this hotel has rates that earn 2x Engine Rewards points; each rate's doubleRewards from lodging_get_room_rates decides, so do not promise 2x for a hotel before the rate is chosen. False: standard Engine Rewards. Absent on every row when Engine Rewards does not apply to this member (engineRewardsVisible on lodging_get_current_user); then never mention 2x rewards.",
"type": "boolean"
},
"bookedBefore": {
"type": "boolean"
},
"policy": {
"type": "string",
"enum": [
"in_policy",
"out_of_policy",
"unknown"
]
},
"rank": {
"type": "integer",
"description": "1 is Engine's top recommendation for this traveler; rows arrive in rank order. Never show rank numbers to the user."
},
"requested": {
"description": "True only on the hotel the user named; it is ranked first by request, not by Engine's recommendation.",
"type": "boolean"
},
"_links": {
"type": "object",
"properties": {
"lodging_get_room_rates": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"properties": {
"propertyId": {
"type": "integer"
},
"roomOffersToken": {
"type": "string",
"x-engine/opaqueReference": true
},
"criteria": {
"type": "object",
"properties": {
"locationDescription": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"radiusMiles": {
"type": "number"
},
"checkIn": {
"type": "string"
},
"checkOut": {
"type": "string"
},
"roomCount": {
"type": "integer"
},
"guestCount": {
"type": "integer"
},
"locationKind": {
"type": "string",
"enum": [
"address",
"area"
]
},
"requestedProperty": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"propertyId": {
"type": "integer"
}
},
"required": [
"name",
"latitude",
"longitude"
],
"additionalProperties": false
}
},
"required": [
"locationDescription",
"latitude",
"longitude",
"checkIn",
"checkOut",
"roomCount",
"guestCount"
],
"additionalProperties": false
},
"hotel": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"amenities": {
"type": "object",
"properties": {
"primary": {
"type": "array",
"items": {
"type": "string",
"enum": [
"breakfast",
"parking",
"wifi"
]
},
"description": "Free breakfast, free parking, free wifi, when offered."
},
"other": {
"type": "array",
"items": {
"type": "string"
},
"description": "Other offered amenities from a fixed set (fitnessCenter, swimmingPool, petFriendly, shuttle, kitchen, airConditioning, truckParking); not exhaustive. For follow-up questions."
}
},
"required": [
"primary",
"other"
],
"additionalProperties": false
}
},
"required": [
"name",
"amenities"
],
"additionalProperties": false
}
},
"required": [
"propertyId",
"roomOffersToken",
"criteria",
"hotel"
],
"additionalProperties": false
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
},
"required": [
"lodging_get_room_rates"
],
"additionalProperties": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
}
},
"required": [
"propertyId",
"name",
"starRating",
"brand",
"price",
"guestRating",
"reviewCount",
"refundable",
"amenities",
"city",
"distance",
"distanceUnit",
"bookedBefore",
"policy",
"rank"
],
"additionalProperties": false
}
},
"total": {
"type": "integer"
},
"outOfPolicyCount": {
"type": "integer",
"description": "Out-of-policy hotels omitted from results."
},
"hiddenInPolicyCount": {
"type": "integer",
"description": "In-policy hotels cut by the row limit. Nonzero means a hotel can be missing without being unavailable."
},
"requestedProperty": {
"description": "Present when the criteria named a hotel. found: it is results[0] with requested: true. unavailable: reason says why; never call a hotel unavailable otherwise.",
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"found",
"unavailable"
]
},
"name": {
"type": "string"
},
"propertyId": {
"type": "integer"
},
"reason": {
"type": "string",
"enum": [
"not_returned",
"sold_out",
"out_of_policy",
"hidden"
]
}
},
"required": [
"status",
"name"
],
"additionalProperties": false
},
"noResultsReason": {
"description": "Present only with zero results, when the company does not allow international travel.",
"type": "string",
"const": "international_restricted"
},
"notice": {
"description": "What to tell the user when noResultsReason is set; follow it instead of retrying.",
"type": "string"
},
"next": {
"type": "string",
"description": "Instruction for the next call."
}
},
"required": [
"searchId",
"criteria",
"displayFields",
"results",
"total",
"outOfPolicyCount",
"hiddenInPolicyCount",
"next"
],
"additionalProperties": false
},
"_links": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"tool": {
"type": "string"
},
"href": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
]
},
"description": {
"type": "string"
},
"body": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"href",
"method",
"description"
],
"additionalProperties": false
}
},
"_handoff": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"href": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"href",
"description"
],
"additionalProperties": false
}
}
},
"required": [
"data",
"_links"
],
"additionalProperties": false
}DESTRUCTIVE lodging_submit_cancellation Cancels the rooms in a cancellation preview and issues the refund.
Destructive — can delete data or make irreversible changes.
Cancels the rooms in a cancellation preview and issues the refund. Call it only with a continuation_token from lodging_preview_cancellation, after the member confirmed those terms. Returns the cancelled contract numbers, the refund, and any penalty. Errors: - CANCELLATION_OUTCOME_UNKNOWN: the cancellation may have gone through. Do not call lodging_submit_cancellation again. Call lodging_preview_cancellation for the same rooms. BOOKING_ALREADY_CANCELLED from that preview means the cancellation succeeded - CANCELLATION_FAILED: do not retry. Offer the member a handoff to support - CANCELLATION_IN_PROGRESS: another cancellation is running for this booking. Do not call lodging_submit_cancellation again - CANCELLATION_POLICY_CHANGED or INVALID_CONTINUATION_TOKEN: call lodging_preview_cancellation again and get the member's confirmation of the new terms - BOOKING_ALREADY_CANCELLED: a selected room is already cancelled; do not call lodging_submit_cancellation; tell the member, or hand off to support - NOT_CANCELLABLE_STATE: the stay is completed or failed; do not call lodging_submit_cancellation; tell the member, or hand off to support
Arguments
| Name | Description |
|---|---|
booking_number* requiredstring
|
G- booking number. Must match the booking the continuation_token was issued for.
|
continuation_token* requiredstring
|
continuation_token from the lodging_preview_cancellation response. Pass it unchanged. It is single-use and expires.
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"booking_number": "string",
"continuation_token": "string"
},
"name": "lodging_submit_cancellation"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"booking_number": {
"type": "string",
"minLength": 1,
"description": "G- booking number. Must match the booking the continuation_token was issued for."
},
"continuation_token": {
"type": "string",
"minLength": 1,
"description": "continuation_token from the lodging_preview_cancellation response. Pass it unchanged. It is single-use and expires."
}
},
"required": [
"booking_number",
"continuation_token"
]
}Returns
{
"_links": {
"*": {
"href": "string"
}
},
"booking_number": "string",
"is_flex_covered": true,
"penalty": {
"amount": {
"amount": "string",
"currency": "string"
},
"is_flex_covered": true,
"nights_penalty": 0
},
"refund": {
"total": {
"amount": "string",
"currency": "string"
},
"methods": [
{
"type": "credit_card",
"amount": {
"amount": "string",
"currency": "string"
}
}
]
},
"rooms": [
{
"contract_number": "string",
"refund_total": {
"amount": "string",
"currency": "string"
},
"penalty": {
"amount": "string",
"currency": "string"
}
}
],
"cancelled_contract_numbers": [
"string"
]
}| _links | object HAL links. This response is terminal — it carries no {…}{
| ||||||||||||||||
| booking_number* | string The booking the cancellation is for. | ||||||||||||||||
| is_flex_covered* | boolean Whether Flex coverage applied to the cancelled rooms' cancellation policy. | ||||||||||||||||
| penalty* | object | null Cancellation penalty charged, or null when there was none. {…}{
| ||||||||||||||||
| refund* | object | null Refund for the cancelled rooms, or null when no refund is issued (for example, a pay-later booking). {…}{
| ||||||||||||||||
| rooms* | object[] Per-room breakdown of the plan that was carried out. [{…}][{ ]
| ||||||||||||||||
| cancelled_contract_numbers* | string[] Contract numbers of the rooms this request cancelled. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"required": [
"booking_number",
"is_flex_covered",
"penalty",
"refund",
"rooms",
"cancelled_contract_numbers"
],
"properties": {
"_links": {
"type": "object",
"description": "HAL links. This response is terminal — it carries no `_templates` — but `booking-permissions` links back to the booking so a consumer can call `lodging_get_booking` again without returning to the discovery root.",
"additionalProperties": {
"type": "object",
"description": "A HAL link.",
"required": [
"href"
],
"properties": {
"href": {
"type": "string",
"description": "Target of the link, relative to this API's base URL."
}
}
}
},
"booking_number": {
"type": "string",
"description": "The booking the cancellation is for."
},
"is_flex_covered": {
"type": "boolean",
"description": "Whether Flex coverage applied to the cancelled rooms' cancellation policy."
},
"penalty": {
"description": "Cancellation penalty charged, or null when there was none.",
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"amount",
"is_flex_covered",
"nights_penalty"
],
"properties": {
"amount": {
"description": "Penalty amount for the selected rooms.",
"type": "object",
"additionalProperties": false,
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"description": "Decimal amount as a string (e.g. \"150.00\")."
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code (e.g. \"USD\")."
}
}
},
"is_flex_covered": {
"type": "boolean",
"description": "Whether Flex coverage absorbs the penalty."
},
"nights_penalty": {
"type": [
"integer",
"null"
],
"description": "Number of nights the penalty is based on, or null when it is not night-based."
}
}
},
"refund": {
"description": "Refund for the cancelled rooms, or null when no refund is issued (for example, a pay-later booking).",
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"total",
"methods"
],
"properties": {
"total": {
"description": "Total refund across all destinations.",
"type": "object",
"additionalProperties": false,
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"description": "Decimal amount as a string (e.g. \"150.00\")."
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code (e.g. \"USD\")."
}
}
},
"methods": {
"type": "array",
"description": "Refund destinations with a positive amount. A destination receiving nothing is omitted.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"amount"
],
"properties": {
"type": {
"type": "string",
"enum": [
"credit_card",
"direct_bill",
"reward_points",
"travel_credits"
],
"description": "Where this part of the refund goes."
},
"amount": {
"description": "Amount refunded to this destination. Always positive.",
"type": "object",
"additionalProperties": false,
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"description": "Decimal amount as a string (e.g. \"150.00\")."
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code (e.g. \"USD\")."
}
}
}
}
}
}
}
},
"rooms": {
"type": "array",
"description": "Per-room breakdown of the plan that was carried out.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"contract_number",
"refund_total",
"penalty"
],
"properties": {
"contract_number": {
"type": "string",
"description": "The room's contract number, as sent in the request."
},
"refund_total": {
"description": "Refund for this room. Null exactly when the top-level `refund` is null (no refund is issued, e.g. a pay-later booking), so \"no refund\" stays distinct from a zero refund.",
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"description": "Decimal amount as a string (e.g. \"150.00\")."
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code (e.g. \"USD\")."
}
}
},
"penalty": {
"description": "This room's share of the top-level penalty, before any Flex coverage, or null when the room bears none. The shares sum to `penalty.amount`.",
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"description": "Decimal amount as a string (e.g. \"150.00\")."
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code (e.g. \"USD\")."
}
}
}
}
}
},
"cancelled_contract_numbers": {
"type": "array",
"description": "Contract numbers of the rooms this request cancelled.",
"items": {
"type": "string"
}
}
}
}DESTRUCTIVE lodging_submit_guest_name_change Replaces the guests on one or more rooms of a booking.
Destructive — can delete data or make irreversible changes.
Replaces the guests on one or more rooms of a booking. Call lodging_get_booking first for the contract numbers and submit only when guest_name_change is_eligible is true, on the booking and on each room being changed. There is no preview and no continuation_token. lodging_get_booking does not return the current guests. guests is the complete replacement list for each room, and any guest left out is removed. The first guest is the primary guest. Before submitting, collect the full guest list for every room being changed from the member, read it back, and get explicit confirmation. Omit rooms that are not changing. Branch on escalation_type, never on HTTP status. none means the names were applied. member_support_case and member_support_case_same_day mean a support case is already open. That is a successful outcome, so do not retry. Loyalty fields always escalate to support. The call is not idempotent, so a timeout or 502 must not be retried.
Arguments
| Name | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
booking_number* requiredstring
|
G- booking number from lodging_get_booking or the member. Not a contract number.
|
||||||||||||||||||||||||
rooms* requiredobject[]
|
The rooms whose guests to change.
[{…}][{ ]
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"booking_number": "string",
"rooms": [
{
"contract_number": "string",
"guests": [
{
"first_name": "string",
"last_name": "string",
"email": "string",
"phone": "string",
"occupant_id": 0,
"occupant_type": "string",
"employee_id": "string",
"loyalty_reward_id": 0,
"loyalty_reward_name": "string",
"loyalty_reward_program_number": "string"
}
]
}
]
},
"name": "lodging_submit_guest_name_change"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"booking_number": {
"type": "string",
"minLength": 1,
"description": "G- booking number from lodging_get_booking or the member. Not a contract number."
},
"rooms": {
"type": "array",
"minItems": 1,
"description": "The rooms whose guests to change.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"contract_number",
"guests"
],
"properties": {
"contract_number": {
"type": "string",
"minLength": 1,
"description": "Per-room contract number whose guests are being changed. From lodging_get_booking: child_bookings[].contract_number when present, otherwise the top-level contract_number."
},
"guests": {
"type": "array",
"minItems": 1,
"description": "Complete replacement guest list for the room. Guests left out are removed. The first entry is the primary guest.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"first_name",
"last_name"
],
"properties": {
"first_name": {
"type": "string",
"minLength": 1,
"description": "Guest first name."
},
"last_name": {
"type": "string",
"minLength": 1,
"description": "Guest last name."
},
"email": {
"type": "string",
"minLength": 1,
"description": "Guest email."
},
"phone": {
"type": "string",
"minLength": 1,
"description": "Guest phone, E.164."
},
"occupant_id": {
"type": "integer",
"description": "Occupant identifier, when the guest maps to a known occupant."
},
"occupant_type": {
"type": "string",
"minLength": 1,
"description": "Occupant type (e.g. user)."
},
"employee_id": {
"type": "string",
"minLength": 1,
"description": "Customer-side employee identifier."
},
"loyalty_reward_id": {
"type": "integer",
"description": "Loyalty reward program identifier. When present, the change cannot be automated and is routed to a support case. Send loyalty_reward_name and loyalty_reward_program_number alongside it."
},
"loyalty_reward_name": {
"type": "string",
"minLength": 1,
"description": "Loyalty program name. Only takes effect with loyalty_reward_id."
},
"loyalty_reward_program_number": {
"type": "string",
"minLength": 1,
"description": "Guest membership number. Only takes effect with loyalty_reward_id."
}
}
}
}
}
}
}
},
"required": [
"booking_number",
"rooms"
]
}Returns
{
"escalation_type": "member_support_case"
}| escalation_type* | string none means the change was applied automatically. member_support_case and member_support_case_same_day mean a support case was opened. member_support_case_same_day is the urgent same-day case. A support-case value is a successful outcome, not an error.
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"required": [
"escalation_type"
],
"properties": {
"escalation_type": {
"type": "string",
"enum": [
"member_support_case",
"member_support_case_same_day",
"none"
],
"description": "none means the change was applied automatically. member_support_case and member_support_case_same_day mean a support case was opened. member_support_case_same_day is the urgent same-day case. A support-case value is a successful outcome, not an error."
}
}
}DESTRUCTIVE lodging_submit_shortening Moves the check-in or check-out dates in a shortening preview and issues the refund.
Destructive — can delete data or make irreversible changes.
Moves the check-in or check-out dates in a shortening preview and issues the refund. Call it only with a continuation_token from lodging_preview_shortening, after the member confirmed those terms. Returns the refund issued, by payment type. Errors: - UNPROCESSABLE_SHORTENING: the MCP could not apply the change. Show the member the reason and do not retry
Arguments
| Name | Description |
|---|---|
booking_number* requiredstring
|
G- booking number. Must match the booking the continuation_token was issued for.
|
continuation_token* requiredstring
|
continuation_token from the lodging_preview_shortening response. Pass it unchanged. It is single-use and expires.
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"booking_number": "string",
"continuation_token": "string"
},
"name": "lodging_submit_shortening"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"booking_number": {
"type": "string",
"minLength": 1,
"description": "G- booking number. Must match the booking the continuation_token was issued for."
},
"continuation_token": {
"type": "string",
"minLength": 1,
"description": "continuation_token from the lodging_preview_shortening response. Pass it unchanged. It is single-use and expires."
}
},
"required": [
"booking_number",
"continuation_token"
]
}Returns
{
"_links": {
"*": {
"href": "string"
}
},
"issued_refund": {
"amount_refunded": "string",
"credit_card_refunded": "string",
"direct_bill_refunded": "string",
"refund_type": "original_form_of_payment",
"reward_points_dollar_refunded": "string",
"travel_credit_refunded": "string"
}
}| _links | object HAL links. This response is terminal — it carries no {…}{
| ||||||||||||
| issued_refund* | object{…}{
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"required": [
"issued_refund"
],
"properties": {
"_links": {
"type": "object",
"description": "HAL links. This response is terminal — it carries no `_templates` — but `booking-permissions` links back to the booking so a consumer can call `lodging_get_booking` again without returning to the discovery root.",
"additionalProperties": {
"type": "object",
"description": "A HAL link.",
"required": [
"href"
],
"properties": {
"href": {
"type": "string",
"description": "Target of the link, relative to this API's base URL."
}
}
}
},
"issued_refund": {
"type": "object",
"additionalProperties": false,
"required": [
"amount_refunded",
"credit_card_refunded",
"direct_bill_refunded",
"refund_type",
"reward_points_dollar_refunded",
"travel_credit_refunded"
],
"properties": {
"amount_refunded": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
},
"credit_card_refunded": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
},
"direct_bill_refunded": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
},
"refund_type": {
"type": "string",
"enum": [
"original_form_of_payment",
"travel_credit"
]
},
"reward_points_dollar_refunded": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
},
"travel_credit_refunded": {
"type": "string",
"description": "A decimal monetary amount represented as a string (e.g. \"150.00\")."
}
}
}
}
}READ support_get_case Returns the full record for one of the member's customer-visible support cases: type, subject, description, status, customer comments, payment status, and the related booking.
Read-only — returns data and changes nothing.
Returns the full record for one of the member's customer-visible support cases: type, subject, description, status, customer comments, payment status, and the related booking. Use it when the member has a case number and needs more than status. For status only, call support_get_case_status. Cases the member cannot see return not found.
Arguments
| Name | Description |
|---|---|
case_number* requiredstring
|
Salesforce case number, for example 00001234, from support_list_cases or the member.
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"case_number": "string"
},
"name": "support_get_case"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"case_number": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "Salesforce case number, for example 00001234, from support_list_cases or the member."
}
},
"required": [
"case_number"
],
"additionalProperties": false
}Returns
{
"case_number": "string",
"booking_id": "string",
"type": "string",
"subject": "string",
"description": "string",
"origin": "string",
"subtype": "string",
"type_reason": "string",
"status": "string",
"is_closed": true,
"is_escalated": true,
"filed_at": "string",
"closed_at": "string",
"last_updated_at": "string",
"customer_comments": "string",
"payment_status": "string",
"_links": {
"self": {
"href": "string",
"templated": true
},
"status": {
"href": "string",
"templated": true
},
"cases": {
"href": "/support/v1/cases{?booking_reference,type,since,page}",
"templated": true
}
}
}| case_number* | string | ||||||||||||||||||
| booking_id* | string | null Engine booking / contract number, or null when unset. Same value | ||||||||||||||||||
| type* | string | null | ||||||||||||||||||
| subject* | string | null | ||||||||||||||||||
| description* | string | null | ||||||||||||||||||
| origin* | string | null | ||||||||||||||||||
| subtype* | string | null | ||||||||||||||||||
| type_reason* | string | null Case type reason from Salesforce ( | ||||||||||||||||||
| status* | string | ||||||||||||||||||
| is_closed* | boolean | ||||||||||||||||||
| is_escalated* | boolean | ||||||||||||||||||
| filed_at* | string Salesforce CreatedDate, passed through. Often | ||||||||||||||||||
| closed_at* | string | null Salesforce ClosedDate when set, else null. Same | ||||||||||||||||||
| last_updated_at* | string Salesforce LastModifiedDate, passed through. Same | ||||||||||||||||||
| customer_comments* | string | null | ||||||||||||||||||
| payment_status* | string | null | ||||||||||||||||||
| _links* | object{…}{
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"case_number",
"booking_id",
"type",
"subject",
"description",
"origin",
"subtype",
"type_reason",
"status",
"is_closed",
"is_escalated",
"filed_at",
"closed_at",
"last_updated_at",
"customer_comments",
"payment_status",
"_links"
],
"properties": {
"case_number": {
"type": "string"
},
"booking_id": {
"type": [
"string",
"null"
],
"description": "Engine booking / contract number, or null when unset. Same value `support_list_cases` accepts as `booking_reference`."
},
"type": {
"type": [
"string",
"null"
]
},
"subject": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"origin": {
"type": [
"string",
"null"
]
},
"subtype": {
"type": [
"string",
"null"
]
},
"type_reason": {
"type": [
"string",
"null"
],
"description": "Case type reason from Salesforce (`Type_Reason__c`), or null when unset. Distinct from the unused standard Case.Reason field."
},
"status": {
"type": "string"
},
"is_closed": {
"type": "boolean"
},
"is_escalated": {
"type": "boolean"
},
"filed_at": {
"type": "string",
"description": "Salesforce CreatedDate, passed through. Often `…+0000` (no colon in the offset) — not strict RFC 3339, so no `format: date-time`."
},
"closed_at": {
"type": [
"string",
"null"
],
"description": "Salesforce ClosedDate when set, else null. Same `…+0000` wire form as `filed_at` when present."
},
"last_updated_at": {
"type": "string",
"description": "Salesforce LastModifiedDate, passed through. Same `…+0000` wire form as `filed_at`."
},
"customer_comments": {
"type": [
"string",
"null"
]
},
"payment_status": {
"type": [
"string",
"null"
]
},
"_links": {
"type": "object",
"required": [
"self",
"status",
"cases"
],
"properties": {
"self": {
"type": "object",
"required": [
"href"
],
"properties": {
"href": {
"type": "string"
},
"templated": {
"type": "boolean",
"description": "True when `href` is an RFC 6570 URI template."
}
}
},
"status": {
"type": "object",
"required": [
"href"
],
"properties": {
"href": {
"type": "string"
},
"templated": {
"type": "boolean",
"description": "True when `href` is an RFC 6570 URI template."
}
}
},
"cases": {
"type": "object",
"required": [
"href",
"templated"
],
"properties": {
"href": {
"type": "string",
"example": "/support/v1/cases{?booking_reference,type,since,page}"
},
"templated": {
"type": "boolean",
"const": true
}
}
}
}
}
}
}READ support_get_case_status Returns the type, status, is_closed, and last_updated_at for one of the member's customer-visible support cases, with no free-text fields.
Read-only — returns data and changes nothing.
Returns the type, status, is_closed, and last_updated_at for one of the member's customer-visible support cases, with no free-text fields. Use it when the member has a case number and only needs status. For the full record, call support_get_case. Cases the member cannot see return not found.
Arguments
| Name | Description |
|---|---|
case_number* requiredstring
|
Salesforce case number, for example 00001234, from support_list_cases or the member.
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"case_number": "string"
},
"name": "support_get_case_status"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"case_number": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "Salesforce case number, for example 00001234, from support_list_cases or the member."
}
},
"required": [
"case_number"
],
"additionalProperties": false
}Returns
{
"case_number": "string",
"type": "string",
"status": "string",
"is_closed": true,
"last_updated_at": "string",
"_links": {
"self": {
"href": "string",
"templated": true
},
"case": {
"href": "string",
"templated": true
},
"cases": {
"href": "string",
"templated": true
}
}
}| case_number* | string | ||||||||||||||||||
| type* | string | null | ||||||||||||||||||
| status* | string | ||||||||||||||||||
| is_closed* | boolean | ||||||||||||||||||
| last_updated_at* | string Salesforce LastModifiedDate, passed through. Often | ||||||||||||||||||
| _links* | object{…}{
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"case_number",
"type",
"status",
"is_closed",
"last_updated_at",
"_links"
],
"properties": {
"case_number": {
"type": "string"
},
"type": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"is_closed": {
"type": "boolean"
},
"last_updated_at": {
"type": "string",
"description": "Salesforce LastModifiedDate, passed through. Often `…+0000` (no colon in the offset) — not strict RFC 3339, so no `format: date-time`."
},
"_links": {
"type": "object",
"required": [
"self",
"case",
"cases"
],
"properties": {
"self": {
"type": "object",
"required": [
"href"
],
"properties": {
"href": {
"type": "string"
},
"templated": {
"type": "boolean",
"description": "True when `href` is an RFC 6570 URI template."
}
}
},
"case": {
"type": "object",
"required": [
"href"
],
"properties": {
"href": {
"type": "string"
},
"templated": {
"type": "boolean",
"description": "True when `href` is an RFC 6570 URI template."
}
}
},
"cases": {
"type": "object",
"required": [
"href",
"templated"
],
"properties": {
"href": {
"type": "string"
},
"templated": {
"type": "boolean",
"const": true
}
}
}
}
}
}
}READ support_list_cases Lists the member's customer-visible support cases, newest first, five per page, up to 25 cases.
Read-only — returns data and changes nothing.
Lists the member's customer-visible support cases, newest first, five per page, up to 25 cases. Booking, case type, and filed-since filters combine. Use it when the member has no case number. For a known case number, call support_get_case or support_get_case_status. Each case has a case number, type, subject, status, is_closed, and filed and updated times. total_count and has_more cover only the 25-case window.
Arguments
| Name | Description |
|---|---|
booking_referencestring
|
Booking number or contract number, with or without the G- prefix, for example G-123456. Also matches flight and car booking numbers. Returns only cases for that booking.
|
typestring
|
Case type. Must match one listed value exactly. BPG is Best Price Guaranteed: a member's request for a refund or price match under the BPG program. Engine X covers cases about Engine's charge card.
|
sincestring
|
Returns cases filed on or after this time. Accepts YYYY-MM-DD, read as UTC midnight, or an ISO 8601 datetime with Z or a numeric offset. The MCP rejects datetimes with no offset.
|
pageinteger
|
Page of five cases, 1 to 5. Defaults to 1. A page past the last case returns an empty list.
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"booking_reference": "string",
"type": "Account Inquiry",
"since": "2026-01-01",
"page": 1
},
"name": "support_list_cases"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"booking_reference": {
"type": "string",
"minLength": 1,
"description": "Booking number or contract number, with or without the G- prefix, for example G-123456. Also matches flight and car booking numbers. Returns only cases for that booking."
},
"type": {
"type": "string",
"description": "Case type. Must match one listed value exactly. BPG is Best Price Guaranteed: a member's request for a refund or price match under the BPG program. Engine X covers cases about Engine's charge card.",
"enum": [
"Account Inquiry",
"BPG",
"Billing Inquiry",
"Car Rental Billing Inquiry",
"Car Rental Changes",
"Car Rental Other",
"Car Rental Technology",
"Car Rentals Client Reported Issues",
"Client Inquiry",
"Client Reported Issue",
"Client Requests",
"Engine X",
"Flight Billing Inquiry",
"Flight Changes",
"Flight Inquiry",
"Flight Loyalty/Benefits",
"Flight Other",
"Flight Technology",
"Loyalty/Benefits",
"Other",
"Reservation Changes",
"Reservation Inquiry",
"System",
"Technology"
]
},
"since": {
"type": "string",
"description": "Returns cases filed on or after this time. Accepts YYYY-MM-DD, read as UTC midnight, or an ISO 8601 datetime with Z or a numeric offset. The MCP rejects datetimes with no offset.",
"examples": [
"2026-01-01",
"2026-01-01T00:00:00Z"
]
},
"page": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 1,
"description": "Page of five cases, 1 to 5. Defaults to 1. A page past the last case returns an empty list."
}
},
"additionalProperties": false
}Returns
{
"cases": [
{
"case_number": "00001234",
"type": "Billing Inquiry",
"subject": "string",
"status": "string",
"is_closed": true,
"filed_at": "string",
"last_updated_at": "string"
}
],
"page": 1,
"page_size": 5,
"total_count": 0,
"has_more": true,
"_links": {
"self": {
"href": "string",
"templated": true
}
}
}| cases* | object[][{…}][{ ]
| ||||||||||||||
| page* | integer
| ||||||||||||||
| page_size* | integer | ||||||||||||||
| total_count* | integer Count of cases in the capped result window after the allowlist pair-check (at most 25), not a guaranteed full allowlist total. The service over-fetches then truncates; when the over-fetch under-fills after filtering, this count can be lower than the true matching set. | ||||||||||||||
| has_more* | boolean True when | ||||||||||||||
| _links* | object{…}{
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cases",
"page",
"page_size",
"total_count",
"has_more",
"_links"
],
"properties": {
"cases": {
"type": "array",
"items": {
"type": "object",
"required": [
"case_number",
"type",
"subject",
"status",
"is_closed",
"filed_at",
"last_updated_at"
],
"properties": {
"case_number": {
"type": "string",
"example": "00001234"
},
"type": {
"type": [
"string",
"null"
],
"example": "Billing Inquiry"
},
"subject": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"description": "Verbatim from Salesforce Case.Status."
},
"is_closed": {
"type": "boolean"
},
"filed_at": {
"type": "string",
"description": "Salesforce CreatedDate, passed through. Often `…+0000` (no colon in the offset) — not strict RFC 3339, so no `format: date-time`."
},
"last_updated_at": {
"type": "string",
"description": "Salesforce LastModifiedDate, passed through. Same `…+0000` wire form as `filed_at`."
}
}
}
},
"page": {
"type": "integer",
"example": 1
},
"page_size": {
"type": "integer",
"const": 5
},
"total_count": {
"type": "integer",
"description": "Count of cases in the capped result window after the allowlist pair-check (at most 25), not a guaranteed full allowlist total. The service over-fetches then truncates; when the over-fetch under-fills after filtering, this count can be lower than the true matching set."
},
"has_more": {
"type": "boolean",
"description": "True when `page * page_size < total_count` for this same capped window — not evidence that more matching cases exist beyond the over-fetch."
},
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"type": "object",
"required": [
"href"
],
"properties": {
"href": {
"type": "string"
},
"templated": {
"type": "boolean",
"description": "True when `href` is an RFC 6570 URI template."
}
}
}
}
}
}
}READ support_search_help_center Searches Engine's public Help Center for how-to and policy answers, such as cancellation, Flex, billing, loyalty, booking rules, and product use.
Read-only — returns data and changes nothing.
Searches Engine's public Help Center for how-to and policy answers, such as cancellation, Flex, billing, loyalty, booking rules, and product use. Returns article excerpts with title, source URL, and relevance score, highest first. It returns public articles only. It cannot look up a member's bookings, cases, or account; the booking and case tools cover those. Call it even when unsure. An empty result means no article matched.
Arguments
| Name | Description |
|---|---|
question* requiredstring
|
A how-to or policy question in plain language, up to 2,000 characters. Leave out personal details such as email, phone, card numbers, full names, and booking details. They don't match articles. The MCP trims whitespace and rejects a blank question.
|
max_resultsinteger
|
Most passages to return, 1 to 50. Defaults to 10.
|
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"question": "how do I cancel a hotel reservation",
"max_results": 10
},
"name": "support_search_help_center"
}
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"question": {
"type": "string",
"minLength": 1,
"maxLength": 2000,
"description": "A how-to or policy question in plain language, up to 2,000 characters. Leave out personal details such as email, phone, card numbers, full names, and booking details. They don't match articles. The MCP trims whitespace and rejects a blank question.",
"examples": [
"how do I cancel a hotel reservation"
]
},
"max_results": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 10,
"description": "Most passages to return, 1 to 50. Defaults to 10."
}
},
"required": [
"question"
],
"additionalProperties": false
}Returns
{
"_links": {
"self": {
"href": "string",
"templated": true
}
},
"passages": [
{
"article_id": "000001919",
"article_title": "Canceling a Reservation",
"chunk_text": "string",
"relevance_score": 0,
"source_url": "https://example.com"
}
]
}| _links* | object{…}{
| ||||||||||
| passages* | object[] Ranked highest-relevance first, at most [{…}][{ ]
|
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"_links",
"passages"
],
"properties": {
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"type": "object",
"required": [
"href"
],
"properties": {
"href": {
"type": "string"
},
"templated": {
"type": "boolean",
"description": "True when `href` is an RFC 6570 URI template."
}
}
}
}
},
"passages": {
"type": "array",
"description": "Ranked highest-relevance first, at most `max_results` long. Empty means nothing matched, not that retrieval failed.",
"items": {
"type": "object",
"required": [
"article_id",
"article_title",
"chunk_text",
"relevance_score",
"source_url"
],
"properties": {
"article_id": {
"type": "string",
"description": "Salesforce article number.",
"examples": [
"000001919"
]
},
"article_title": {
"type": "string",
"examples": [
"Canceling a Reservation"
]
},
"chunk_text": {
"type": "string",
"description": "The retrieved chunk — the text an answer may cite."
},
"relevance_score": {
"type": "number",
"description": "Similarity to the question; higher is closer. Finite and unclamped — Data Cloud may report values outside `[0, 1]` when the index uses a different metric than the one we measured, and rewriting them would hide that drift.",
"format": "double"
},
"source_url": {
"type": "string",
"description": "Public Help Center URL for the article.",
"format": "uri"
}
}
}
}
}
}