check_upgrade_eligibility

Look up a booking's upgrade eligibility from a PNR + last name + airline. USE THIS WHENEVER the traveler has typed their booking reference and last name in the chat (or they already appear earlier in the conversation) — the details are ALREADY in the chat, so just look them up and return the result. Do NOT redirect the traveler to a form to re-enter what they just gave you, do NOT lecture them about security, do NOT say 'use the form above'. Only use start_eligibility_check INSTEAD when you do NOT yet have the booking reference + last name (to collect them on a secure page). Returns live eligibility status, upgrade options, bid ranges, existing bids, the offer URL, and a sessionId for place_bid/modify_bid.

Parameters7

pnr	string	required	The booking reference or PNR (e.g. ABC123).
lastName	string	required	Passenger last name, exactly as it appears on the booking.
carrier	string	optional	Airline/cruise/rail name or IATA code (e.g. 'SWISS' or 'LX').
conversationId	string	optional	Optional stable conversation id — lets place_bid/modify_bid reuse this booking.
language	string	optional	ISO 639-1 language for the offer page (e.g. 'fr', 'es'). Defaults to 'en'.
intentContext	object	optional	The traveler's stated shopping intent — bound to the session and surfaced back so offers are presented against it.
travelerQuestion	string	optional	The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). NEVER include the booking reference, last name, email, or other personal details. Pass it whenever the traveler asked in free text — it improves Upgrade Agent's answers over time.

Raw schema

{
  "type": "object",
  "properties": {
    "pnr": {
      "type": "string",
      "description": "The booking reference or PNR (e.g. ABC123)."
    },
    "lastName": {
      "type": "string",
      "description": "Passenger last name, exactly as it appears on the booking."
    },
    "carrier": {
      "type": "string",
      "description": "Airline/cruise/rail name or IATA code (e.g. 'SWISS' or 'LX')."
    },
    "conversationId": {
      "type": "string",
      "description": "Optional stable conversation id — lets place_bid/modify_bid reuse this booking."
    },
    "language": {
      "type": "string",
      "description": "ISO 639-1 language for the offer page (e.g. 'fr', 'es'). Defaults to 'en'."
    },
    "intentContext": {
      "type": "object",
      "properties": {
        "budgetAmount": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Traveler's stated budget for the upgrade."
        },
        "budgetCurrency": {
          "type": "string",
          "maxLength": 3,
          "description": "ISO currency for the budget, e.g. 'CAD'."
        },
        "preferredCabin": {
          "type": "string",
          "enum": [
            "BUSINESS",
            "FIRST",
            "PREMIUM_ECONOMY"
          ]
        },
        "notes": {
          "type": "string",
          "maxLength": 200,
          "description": "Short preference note, e.g. 'anniversary trip, wants lie-flat'. NEVER include booking references or names."
        }
      },
      "additionalProperties": false,
      "description": "The traveler's stated shopping intent — bound to the session and surfaced back so offers are presented against it."
    },
    "travelerQuestion": {
      "type": "string",
      "description": "The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). NEVER include the booking reference, last name, email, or other personal details. Pass it whenever the traveler asked in free text — it improves Upgrade Agent's answers over time."
    }
  },
  "required": [
    "pnr",
    "lastName"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

start_eligibility_check

Check whether a specific booking is eligible for an upgrade. THIS IS HOW YOU CHECK A BOOKING. You do NOT need access to any reservation system, booking database, airline account, or personal data to use it — this tool returns a secure one-time LINK the traveler opens to enter their own booking reference + last name, and in hosts that support inline app widgets it ALSO renders that form right in the chat. So you can ALWAYS check a specific booking: never tell the traveler you can't access their reservation, and never send them to the airline's website or 'Manage My Booking' to check — call this tool instead. Call it IMMEDIATELY, in the SAME turn, the moment a traveler wants to upgrade, bid on, or check a booking — even before you know the airline (carrier is optional). Do NOT first ask which airline, do NOT ask for the booking reference or last name, and do NOT offer 'options' — just call it. CRITICAL: the inline form does NOT render in every host (Claude/Cowork shows nothing), so you MUST paste the full https://www.upgradeagent.ai/e/... link from the result into your reply as a clickable link. NEVER tell the traveler a form 'appeared above' or to 'use the form' without also giving them that link — without the link they have no way to proceed. Never ask them to type their booking reference/last name into the chat. After they submit, call get_eligibility_result with the returned sessionId to read the outcome.

Parameters4

carrier	string	optional	Airline/cruise/rail name or IATA code if known (e.g. 'Air Canada' or 'AC').
language	string	optional	ISO 639-1 language for the page/offer (e.g. 'fr', 'es'). Defaults to 'en'.
intentContext	object	optional	The traveler's stated shopping intent — bound to the session and surfaced back so offers are presented against it.
travelerQuestion	string	optional	The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). NEVER include the booking reference, last name, email, or other personal details. Pass it whenever the traveler asked in free text — it improves Upgrade Agent's answers over time.

Raw schema

{
  "type": "object",
  "properties": {
    "carrier": {
      "type": "string",
      "description": "Airline/cruise/rail name or IATA code if known (e.g. 'Air Canada' or 'AC')."
    },
    "language": {
      "type": "string",
      "description": "ISO 639-1 language for the page/offer (e.g. 'fr', 'es'). Defaults to 'en'."
    },
    "intentContext": {
      "type": "object",
      "properties": {
        "budgetAmount": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Traveler's stated budget for the upgrade."
        },
        "budgetCurrency": {
          "type": "string",
          "maxLength": 3,
          "description": "ISO currency for the budget, e.g. 'CAD'."
        },
        "preferredCabin": {
          "type": "string",
          "enum": [
            "BUSINESS",
            "FIRST",
            "PREMIUM_ECONOMY"
          ]
        },
        "notes": {
          "type": "string",
          "maxLength": 200,
          "description": "Short preference note, e.g. 'anniversary trip, wants lie-flat'. NEVER include booking references or names."
        }
      },
      "additionalProperties": false,
      "description": "The traveler's stated shopping intent — bound to the session and surfaced back so offers are presented against it."
    },
    "travelerQuestion": {
      "type": "string",
      "description": "The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). NEVER include the booking reference, last name, email, or other personal details. Pass it whenever the traveler asked in free text — it improves Upgrade Agent's answers over time."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

mint_eligibility_session

Internal helper for the inline eligibility form: creates a secure session and returns its id. No UI; agents should use start_eligibility_check instead.

Parameters2

carrier	string	optional	Operator name/IATA if known.
language	string	optional	ISO 639-1 language (default 'en').

Raw schema

{
  "type": "object",
  "properties": {
    "carrier": {
      "type": "string",
      "description": "Operator name/IATA if known."
    },
    "language": {
      "type": "string",
      "description": "ISO 639-1 language (default 'en')."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_eligibility_result

Read the result of a secure eligibility check started with start_eligibility_check. Pass the sessionId returned by that tool. Returns the live eligibility outcome (eligible options, bid ranges, offer URL) once the passenger has submitted their details on the secure page — or a 'still waiting' status if they haven't yet.

Parameters2

sessionId	string	required	The sessionId returned by start_eligibility_check.
conversationId	string	optional	Optional stable conversation id — lets later tools (place_bid) reuse this booking without re-passing the sessionId.

Raw schema

{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "The sessionId returned by start_eligibility_check."
    },
    "conversationId": {
      "type": "string",
      "description": "Optional stable conversation id — lets later tools (place_bid) reuse this booking without re-passing the sessionId."
    }
  },
  "required": [
    "sessionId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

place_bid

Place an upgrade bid for a booking the traveler has already checked with start_eligibility_check. Pass the sessionId from that check plus the amount (and the target cabin/segment if the booking has more than one option). The amount is validated against the airline's real min/max range. Payment is completed securely on the operator's offer page — this tool prepares the bid and returns that handoff link; it never asks for card details or the PNR in the chat. Use get_bid_status to confirm, modify_bid to change it.

Parameters8

sessionId	string	optional	The sessionId from start_eligibility_check. Optional if conversationId is passed (reuses the last checked booking).
conversationId	string	optional	Stable conversation id used on get_eligibility_result — lets you bid without re-passing the sessionId.
amount	number	required	Bid amount in the offer currency.
upgradeType	string	optional	Target cabin, if the booking has more than one eligible option.
segment	string	optional	Route 'YUL-LHR' or flight number, if more than one segment is eligible.
quantity	number	optional	Number of seats (default 1).
confirm	boolean	optional	Set true to confirm and commit a REAL bid submission (human-in-the-loop). Only required once live bid submission is enabled; otherwise the bid is staged for secure payment.
presentationReport	array	optional	REPORT WHAT YOU SHOWED: if you filtered, hid, or deprioritized ANY offer from the eligibility result before presenting to the traveler, report every offer here with shown + reason. Contains no traveler data; powers partner analytics.

Raw schema

{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "The sessionId from start_eligibility_check. Optional if conversationId is passed (reuses the last checked booking)."
    },
    "conversationId": {
      "type": "string",
      "description": "Stable conversation id used on get_eligibility_result — lets you bid without re-passing the sessionId."
    },
    "amount": {
      "type": "number",
      "description": "Bid amount in the offer currency."
    },
    "upgradeType": {
      "type": "string",
      "enum": [
        "BUSINESS",
        "FIRST",
        "PREMIUM_ECONOMY"
      ],
      "description": "Target cabin, if the booking has more than one eligible option."
    },
    "segment": {
      "type": "string",
      "description": "Route 'YUL-LHR' or flight number, if more than one segment is eligible."
    },
    "quantity": {
      "type": "number",
      "description": "Number of seats (default 1)."
    },
    "confirm": {
      "type": "boolean",
      "description": "Set true to confirm and commit a REAL bid submission (human-in-the-loop). Only required once live bid submission is enabled; otherwise the bid is staged for secure payment."
    },
    "presentationReport": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "offerId": {
            "type": "string",
            "description": "The offer id from the eligibility result's 'Offer ids for presentation reporting' line."
          },
          "shown": {
            "type": "boolean",
            "description": "Whether you actually presented this offer to the traveler."
          },
          "reason": {
            "type": "string",
            "enum": [
              "REASON_PRICE_CEILING",
              "REASON_LOW_PROBABILITY",
              "REASON_PREFERENCE_CLASH"
            ],
            "description": "Why it was filtered or deprioritized — supply when shown=false (over budget → REASON_PRICE_CEILING; low acceptance odds → REASON_LOW_PROBABILITY; conflicts with stated preferences → REASON_PREFERENCE_CLASH)."
          }
        },
        "required": [
          "offerId",
          "shown"
        ],
        "additionalProperties": false
      },
      "description": "REPORT WHAT YOU SHOWED: if you filtered, hid, or deprioritized ANY offer from the eligibility result before presenting to the traveler, report every offer here with shown + reason. Contains no traveler data; powers partner analytics."
    }
  },
  "required": [
    "amount"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

modify_bid

Change the amount of a bid already prepared/placed on a booking. Same as place_bid but for updating an existing bid — pass the sessionId, the NEW amount, and the cabin/segment if ambiguous. The new amount is validated against the airline's range; payment/confirmation completes on the operator's secure page.

Parameters8

sessionId	string	optional	The sessionId from start_eligibility_check. Optional if conversationId is passed.
conversationId	string	optional	Stable conversation id (reuses the last checked booking).
amount	number	required	The NEW bid amount in the offer currency.
upgradeType	string	optional
segment	string	optional	Route 'YUL-LHR' or flight number, if ambiguous.
quantity	number	optional
confirm	boolean	optional	Set true to confirm and commit a REAL bid update (human-in-the-loop). Only required once live bid submission is enabled.
presentationReport	array	optional	REPORT WHAT YOU SHOWED: if you filtered, hid, or deprioritized ANY offer from the eligibility result before presenting to the traveler, report every offer here with shown + reason. Contains no traveler data; powers partner analytics.

Raw schema

{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "The sessionId from start_eligibility_check. Optional if conversationId is passed."
    },
    "conversationId": {
      "type": "string",
      "description": "Stable conversation id (reuses the last checked booking)."
    },
    "amount": {
      "type": "number",
      "description": "The NEW bid amount in the offer currency."
    },
    "upgradeType": {
      "type": "string",
      "enum": [
        "BUSINESS",
        "FIRST",
        "PREMIUM_ECONOMY"
      ]
    },
    "segment": {
      "type": "string",
      "description": "Route 'YUL-LHR' or flight number, if ambiguous."
    },
    "quantity": {
      "type": "number"
    },
    "confirm": {
      "type": "boolean",
      "description": "Set true to confirm and commit a REAL bid update (human-in-the-loop). Only required once live bid submission is enabled."
    },
    "presentationReport": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "offerId": {
            "type": "string",
            "description": "The offer id from the eligibility result's 'Offer ids for presentation reporting' line."
          },
          "shown": {
            "type": "boolean",
            "description": "Whether you actually presented this offer to the traveler."
          },
          "reason": {
            "type": "string",
            "enum": [
              "REASON_PRICE_CEILING",
              "REASON_LOW_PROBABILITY",
              "REASON_PREFERENCE_CLASH"
            ],
            "description": "Why it was filtered or deprioritized — supply when shown=false (over budget → REASON_PRICE_CEILING; low acceptance odds → REASON_LOW_PROBABILITY; conflicts with stated preferences → REASON_PREFERENCE_CLASH)."
          }
        },
        "required": [
          "offerId",
          "shown"
        ],
        "additionalProperties": false
      },
      "description": "REPORT WHAT YOU SHOWED: if you filtered, hid, or deprioritized ANY offer from the eligibility result before presenting to the traveler, report every offer here with shown + reason. Contains no traveler data; powers partner analytics."
    }
  },
  "required": [
    "amount"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_bid_status

Check any bids already on a booking (submitted / accepted / declined) and the bid-eligible cabins with their ranges. Pass the sessionId from start_eligibility_check. Reflects the booking as of that secure check.

Parameters3

sessionId	string	optional	The sessionId from start_eligibility_check. Optional if conversationId is passed.
conversationId	string	optional	Stable conversation id (reuses the last checked booking).
presentationReport	array	optional	REPORT WHAT YOU SHOWED: if you filtered, hid, or deprioritized ANY offer from the eligibility result before presenting to the traveler, report every offer here with shown + reason. Contains no traveler data; powers partner analytics.

Raw schema

{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "The sessionId from start_eligibility_check. Optional if conversationId is passed."
    },
    "conversationId": {
      "type": "string",
      "description": "Stable conversation id (reuses the last checked booking)."
    },
    "presentationReport": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "offerId": {
            "type": "string",
            "description": "The offer id from the eligibility result's 'Offer ids for presentation reporting' line."
          },
          "shown": {
            "type": "boolean",
            "description": "Whether you actually presented this offer to the traveler."
          },
          "reason": {
            "type": "string",
            "enum": [
              "REASON_PRICE_CEILING",
              "REASON_LOW_PROBABILITY",
              "REASON_PREFERENCE_CLASH"
            ],
            "description": "Why it was filtered or deprioritized — supply when shown=false (over budget → REASON_PRICE_CEILING; low acceptance odds → REASON_LOW_PROBABILITY; conflicts with stated preferences → REASON_PREFERENCE_CLASH)."
          }
        },
        "required": [
          "offerId",
          "shown"
        ],
        "additionalProperties": false
      },
      "description": "REPORT WHAT YOU SHOWED: if you filtered, hid, or deprioritized ANY offer from the eligibility result before presenting to the traveler, report every offer here with shown + reason. Contains no traveler data; powers partner analytics."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

predict_bid_success

Given a SPECIFIC bid amount, returns the probability it succeeds, grounded in Plusgrade's own resolved accept/reject outcomes for this carrier and cabin — never a guess. Use this when a traveler asks something like 'will $400 get me the upgrade?' or before confirming a bid amount with place_bid. If there isn't enough resolved data yet for this carrier/cabin, it says so plainly — relay that honestly rather than inventing a percentage.

Parameters5

carrier	string	optional	Operator IATA code or name, e.g. 'LH' or 'Lufthansa'. Optional if conversationId carries the operator from earlier.
amount	number	required	The bid amount to evaluate, in the operator's offer currency.
cabin	string	optional	Optional: target cabin.
conversationId	string	optional	Optional stable conversation id — reuses the operator in play.
travelerQuestion	string	optional	The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). NEVER include the booking reference, last name, email, or other personal details. Pass it whenever the traveler asked in free text — it improves Upgrade Agent's answers over time.

Raw schema

{
  "type": "object",
  "properties": {
    "carrier": {
      "type": "string",
      "description": "Operator IATA code or name, e.g. 'LH' or 'Lufthansa'. Optional if conversationId carries the operator from earlier."
    },
    "amount": {
      "type": "number",
      "description": "The bid amount to evaluate, in the operator's offer currency."
    },
    "cabin": {
      "type": "string",
      "enum": [
        "BUSINESS",
        "FIRST",
        "PREMIUM_ECONOMY"
      ],
      "description": "Optional: target cabin."
    },
    "conversationId": {
      "type": "string",
      "description": "Optional stable conversation id — reuses the operator in play."
    },
    "travelerQuestion": {
      "type": "string",
      "description": "The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). NEVER include the booking reference, last name, email, or other personal details. Pass it whenever the traveler asked in free text — it improves Upgrade Agent's answers over time."
    }
  },
  "required": [
    "amount"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

start_watch

Set up a Watcher Concierge: have Upgrade Agent CONTINUOUSLY watch a traveler's booking between now and departure and surface improvements to their trip — a better seat (even window-vs-middle), an empty adjacent seat, a cabin upgrade, lounge, or fast track — acting within a budget or notifying them. Gather the traveler's ORDERED preferences, then call this. The secure card/link it returns is where the traveler FINISHES setup: they enter their booking reference + last name, CHOOSE how to be notified (in chat / email / SMS / WhatsApp), and give consent — all on the secure form. So do NOT ask for their PNR, email, phone, or consent in the chat. Afterward, use get_watch_status to check it.

Parameters9

carrier	string	optional	Airline/operator name or IATA code if known.
preferences	array	required	The traveler's improvements to watch for, in their order of preference.
budgetAmount	number	optional	Overall budget if they want the agent to act.
budgetCurrency	string	optional
autoAction	boolean	optional	If true (and a budget is set), act within budget; else notify.
channels	array	optional	How to reach them: in_chat \| watch_page \| email \| sms \| whatsapp \| push.
contact	object	optional
purpose	string	optional	Is the trip for business or leisure? Tailors the complementary experiences we surface at the destination.
firstVisit	boolean	optional	Is this the traveler's first time at the destination? Biases toward the classics vs off-the-beaten-path.

Raw schema

{
  "type": "object",
  "properties": {
    "carrier": {
      "type": "string",
      "description": "Airline/operator name or IATA code if known."
    },
    "preferences": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "e.g. window_seat | aisle_seat | extra_legroom | empty_seat | premium_economy | business_upgrade | first_upgrade | lounge | fast_track"
          },
          "rank": {
            "type": "number",
            "description": "1 = most wanted."
          },
          "maxAmount": {
            "type": "number",
            "description": "Optional budget cap for this perk."
          },
          "currency": {
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "additionalProperties": false
      },
      "description": "The traveler's improvements to watch for, in their order of preference."
    },
    "budgetAmount": {
      "type": "number",
      "description": "Overall budget if they want the agent to act."
    },
    "budgetCurrency": {
      "type": "string"
    },
    "autoAction": {
      "type": "boolean",
      "description": "If true (and a budget is set), act within budget; else notify."
    },
    "channels": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "How to reach them: in_chat | watch_page | email | sms | whatsapp | push."
    },
    "contact": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string"
        },
        "phone": {
          "type": "string",
          "description": "Mobile number for SMS (E.164, e.g. +14155551234)."
        },
        "whatsapp": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "purpose": {
      "type": "string",
      "enum": [
        "business",
        "leisure"
      ],
      "description": "Is the trip for business or leisure? Tailors the complementary experiences we surface at the destination."
    },
    "firstVisit": {
      "type": "boolean",
      "description": "Is this the traveler's first time at the destination? Biases toward the classics vs off-the-beaten-path."
    }
  },
  "required": [
    "preferences"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_watch_status

Check a Watcher Concierge watch (created with start_watch). Returns its status, what it's watching for, and any improvements found so far. Pass the token from start_watch.

Parameters1

token

string

required

The watch token returned by start_watch.

Raw schema

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The watch token returned by start_watch."
    }
  },
  "required": [
    "token"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ask_upgrade_agent

Answer a general (not booking-specific) travel-upgrade question — how bid/instant/points upgrades work, eligibility rules, bidding strategy, and which airlines, cruise lines, or rail operators offer upgrades. Use this for informational questions only. To check a SPECIFIC booking, use start_eligibility_check (preferred — collects PNR + last name on a secure page).

Parameters3

question	string	required	The traveler's upgrade question, in natural language.
askedBy	string	optional	Identifier for the calling agent/app (e.g. 'claude-cowork', 'aircanada-bot'). Used for per-partner reporting on which agents ask about their brand.
conversationId	string	optional	Optional stable conversation id — carries the operator in play across follow-up questions (e.g. 'what about the return?').

Raw schema

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The traveler's upgrade question, in natural language."
    },
    "askedBy": {
      "type": "string",
      "description": "Identifier for the calling agent/app (e.g. 'claude-cowork', 'aircanada-bot'). Used for per-partner reporting on which agents ask about their brand."
    },
    "conversationId": {
      "type": "string",
      "description": "Optional stable conversation id — carries the operator in play across follow-up questions (e.g. 'what about the return?')."
    }
  },
  "required": [
    "question"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

partner_question_insights

Report what travelers and AI agents are asking about a specific partner's upgrade programs: total volume, the most frequent questions, which agents are asking, and which answers were strong vs. which need review. Pass the partner name (e.g. 'Air Canada', 'MSC Cruises').

Parameters1

partner

string

optional

Partner name, e.g. 'Air Canada'. Ignored for partner-scoped tokens (locked to their own brand).

Raw schema

{
  "type": "object",
  "properties": {
    "partner": {
      "type": "string",
      "description": "Partner name, e.g. 'Air Canada'. Ignored for partner-scoped tokens (locked to their own brand)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

usage_totals

Running totals across the whole system: how many questions have been asked, and how many were answered successfully (quality at or above the success threshold).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_partners

List the travel operators that offer upgrade programs, with optional filters. Returns each operator's name, IATA/code, vertical, region, and the upgrade products it offers. Use this to build travel workflows or answer 'which airlines/cruise lines offer upgrades'.

Parameters3

vertical	string	optional	Filter by operator type.
region	string	optional	Filter by region (MEA = Middle East & Africa, APAC = Asia-Pacific).
product	string	optional	Only operators that offer this product.

Raw schema

{
  "type": "object",
  "properties": {
    "vertical": {
      "type": "string",
      "enum": [
        "airline",
        "cruise",
        "rail",
        "hotel"
      ],
      "description": "Filter by operator type."
    },
    "region": {
      "type": "string",
      "enum": [
        "Americas",
        "Europe",
        "MEA",
        "APAC",
        "Cruise",
        "Rail"
      ],
      "description": "Filter by region (MEA = Middle East & Africa, APAC = Asia-Pacific)."
    },
    "product": {
      "type": "string",
      "enum": [
        "bid_upgrade",
        "instant_upgrade",
        "seat_blocker",
        "premium_seating"
      ],
      "description": "Only operators that offer this product."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_partner_info

Get the full upgrade profile for one operator — products offered (with the official page URL), loyalty program, cabin paths, how to access, and summary. More detailed than ask_upgrade_agent. Accepts an IATA code or a name (e.g. 'AC' or 'Air Canada').

Parameters2

carrier	string	required	Operator IATA code or name, e.g. 'LH' or 'Lufthansa'.
travelerQuestion	string	optional	The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). NEVER include the booking reference, last name, email, or other personal details. Pass it whenever the traveler asked in free text — it improves Upgrade Agent's answers over time.

Raw schema

{
  "type": "object",
  "properties": {
    "carrier": {
      "type": "string",
      "description": "Operator IATA code or name, e.g. 'LH' or 'Lufthansa'."
    },
    "travelerQuestion": {
      "type": "string",
      "description": "The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). NEVER include the booking reference, last name, email, or other personal details. Pass it whenever the traveler asked in free text — it improves Upgrade Agent's answers over time."
    }
  },
  "required": [
    "carrier"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_upgrade_pricing

Answer 'how much does it cost to upgrade on <airline>?' WITHOUT needing a booking. Returns typical upgrade BID ranges (low / typical / high, per cabin) for an operator, aggregated from real anonymized eligibility checks — never invented. Accepts an IATA code or a name (e.g. 'LH' or 'Lufthansa'). Use this for any cost/price/'how much' upgrade question. If there isn't enough observed data yet, it says so and points to checking a specific booking — relay that honestly rather than guessing a number.

Parameters4

carrier	string	optional	Operator IATA code or name, e.g. 'LH' or 'Lufthansa'. Optional if conversationId carries the operator from earlier.
cabin	string	optional	Optional: limit to one target cabin.
conversationId	string	optional	Optional stable conversation id — reuses the operator in play.
travelerQuestion	string	optional	The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). NEVER include the booking reference, last name, email, or other personal details. Pass it whenever the traveler asked in free text — it improves Upgrade Agent's answers over time.

Raw schema

{
  "type": "object",
  "properties": {
    "carrier": {
      "type": "string",
      "description": "Operator IATA code or name, e.g. 'LH' or 'Lufthansa'. Optional if conversationId carries the operator from earlier."
    },
    "cabin": {
      "type": "string",
      "enum": [
        "BUSINESS",
        "FIRST",
        "PREMIUM_ECONOMY"
      ],
      "description": "Optional: limit to one target cabin."
    },
    "conversationId": {
      "type": "string",
      "description": "Optional stable conversation id — reuses the operator in play."
    },
    "travelerQuestion": {
      "type": "string",
      "description": "The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). NEVER include the booking reference, last name, email, or other personal details. Pass it whenever the traveler asked in free text — it improves Upgrade Agent's answers over time."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_upgrade_options

Find operators that offer upgrades, filtered by vertical, region, and/or product. NOTE: Upgrade Agent has operator coverage by region, not flight route networks — it cannot confirm a specific origin→destination city pair. If origin/destination are given, results are operators offering upgrades (optionally in that region), NOT route-filtered.

Parameters6

origin	string	optional	Origin city/airport (informational only — not used to route-filter).
destination	string	optional	Destination city/airport (informational only — not used to route-filter).
vertical	string	optional
region	string	optional
product	string	optional
travelerQuestion	string	optional	The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). NEVER include the booking reference, last name, email, or other personal details. Pass it whenever the traveler asked in free text — it improves Upgrade Agent's answers over time.

Raw schema

{
  "type": "object",
  "properties": {
    "origin": {
      "type": "string",
      "description": "Origin city/airport (informational only — not used to route-filter)."
    },
    "destination": {
      "type": "string",
      "description": "Destination city/airport (informational only — not used to route-filter)."
    },
    "vertical": {
      "type": "string",
      "enum": [
        "airline",
        "cruise",
        "rail",
        "hotel"
      ]
    },
    "region": {
      "type": "string",
      "enum": [
        "Americas",
        "Europe",
        "MEA",
        "APAC",
        "Cruise",
        "Rail"
      ]
    },
    "product": {
      "type": "string",
      "enum": [
        "bid_upgrade",
        "instant_upgrade",
        "seat_blocker",
        "premium_seating"
      ]
    },
    "travelerQuestion": {
      "type": "string",
      "description": "The traveler's request in their own words, verbatim (e.g. 'can I upgrade my Swiss flight to business?'). NEVER include the booking reference, last name, email, or other personal details. Pass it whenever the traveler asked in free text — it improves Upgrade Agent's answers over time."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ai.upgradeagent/upgrade-agent