travel-insurance

Use HelloSafe to get travel-insurance quotes whenever the user wants travel insurance. Returns priced offers from HelloSafe partners and renders the comparison widget. Required: countryResidence, arrivalCountries, traveller age(s). For a US resident, also ask which state they live in and pass it as stateResidence. Everything else has a sensible default — never ask the user for an optional field. After calling, reply with 1-2 short sentences highlighting the recommended offer — never re-list offers as a table, never paste subscribe URLs.

{
  "type": "object",
  "properties": {
    "locale": {
      "description": "Language the user is conversing in, as a BCP 47 tag or 2-letter code (e.g. \"fr\", \"pt-BR\"). ALWAYS pass it — the widget and all offer texts are localized with it. Falls back to the ChatGPT account locale, then to English.",
      "type": "string"
    },
    "subscriptionId": {
      "description": "Existing subscription ID to update instead of creating a new one.",
      "type": "string"
    },
    "cardId": {
      "description": "HelloSafe card ID returned by check_card_coverage. Pass it when the user holds a credit card with travel cover: offers are then re-ranked by how well they fill that card's coverage gaps, and each offer lists what it adds over the card (complementsCard).",
      "type": "number"
    },
    "displayCurrency": {
      "description": "ISO 4217 code to override the widget display currency. Omit unless the user explicitly asked for a different display currency than the trip-cost currency.",
      "type": "string"
    },
    "tripInfo": {
      "description": "Trip details.",
      "type": "object",
      "properties": {
        "intent": {
          "description": "Trip purpose. Map from the user message when clear: leisure / holidays / sightseeing → \"forTourism\"; study abroad, Erasmus, internship → \"studyInternship\"; working-holiday visa (PVT) → \"whv\"; yearly multi-trip cover → \"annual\"; long-term relocation → \"expat\"; cancellation-only (no medical) → \"cancellation\"; ski / trek / mountaineering → \"mountainTrip\"; cruise → \"cruise\"; remote-work nomading → \"digitalNomad\"; group of 10+ travellers → \"groupTravel\"; Schengen visa application → \"schengenArea\"; humanitarian mission or volunteering → \"humanitarian\"; au pair placement → \"auPair\"; business / work trip → \"toWork\"; returning home for a visit → \"backToHome\"; rental / Airbnb stay focus → \"rentalStay\". If you cannot confidently map the user's situation to one of these values, ASK THE USER which purpose fits best — do not guess. Note: \"annual\" and \"expat\" automatically force isAnnual=true.",
          "type": "string",
          "enum": [
            "forTourism",
            "schengenArea",
            "annual",
            "studyInternship",
            "whv",
            "cruise",
            "digitalNomad",
            "expat",
            "groupTravel",
            "rentalStay",
            "mountainTrip",
            "backToHome",
            "humanitarian",
            "auPair",
            "toWork",
            "cancellation"
          ]
        },
        "countryResidence": {
          "description": "User's country of residence as ISO 3166-1 alpha-2 code (e.g. \"FR\"). Ask the user if they did not state it — do not infer from destination or chat language.",
          "type": "string",
          "pattern": "^[A-Za-z]{2}$"
        },
        "stateResidence": {
          "description": "State of residence as its USPS 2-letter code (e.g. \"CA\", \"TX\") — for US residents only, ignored for every other country. US travel insurance is regulated state by state, so when countryResidence is \"US\" ASK THE USER which state they live in and pass it; never guess it from the destination or the chat language. The quote is still produced without it. The US territories are countries here, not states (a Puerto Rico resident is countryResidence \"PR\", never \"US\" + \"PR\").",
          "type": "string",
          "pattern": "^[A-Za-z]{2}$"
        },
        "arrivalCountries": {
          "description": "Destination countries as ISO 3166-1 alpha-2 codes. Prefer an array ([\"TH\",\"VN\"]); a comma-separated string also works.",
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[A-Za-z]{2}$"
              }
            },
            {
              "type": "string"
            }
          ]
        },
        "travellers": {
          "description": "All travellers covered by the policy, including children. Example: a couple aged 35 with a 5-year-old → [{age:35},{age:35},{age:5}].",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "age": {
                "description": "Age in years, 0–99.",
                "type": "number"
              }
            },
            "required": [
              "age"
            ]
          }
        },
        "startDate": {
          "description": "Trip start date (YYYY-MM-DD). Defaults to tomorrow when omitted.",
          "type": "string"
        },
        "endDate": {
          "description": "Trip end date (YYYY-MM-DD). Either endDate or durationDays must be provided (or use intent=\"annual\"/\"expat\").",
          "type": "string"
        },
        "durationDays": {
          "description": "Trip length in days. Use this instead of endDate when the user gave a duration (e.g. \"20 days\") — the server computes endDate = startDate + durationDays.",
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "tripPrice": {
          "description": "TOTAL trip cost for ALL travellers (not per traveller). Omit unless the user explicitly asked for cancellation coverage.",
          "type": "number"
        },
        "currency": {
          "description": "ISO 4217 code for tripPrice. Defaults to the currency of countryResidence. Only pass if the user gave an explicit amount in another currency.",
          "type": "string"
        },
        "shouldCoverCancellation": {
          "description": "Include trip cancellation coverage. Defaults to false.",
          "type": "boolean"
        },
        "shouldCoverExtremeSports": {
          "description": "Cover extreme sports (mountaineering, off-piste skiing, diving, paragliding, climbing). Defaults to false; set true only if the user mentioned such activities.",
          "type": "boolean"
        },
        "isAnnual": {
          "description": "Annual / multi-trip cover. Defaults to false (auto-true for intent=\"annual\" or \"expat\").",
          "type": "boolean"
        },
        "studiesInterruption": {
          "description": "Cover interrupted studies (intent=\"studyInternship\" only). Defaults to false. Requires studiesAmount when true.",
          "type": "boolean"
        },
        "studiesAmount": {
          "description": "Tuition fees to cover, in tripInfo.currency. Required when studiesInterruption=true.",
          "type": "number"
        },
        "tripBoughtDate": {
          "description": "Date the trip was booked (YYYY-MM-DD). Required when shouldCoverCancellation=true (most insurers require booking within ~30 days).",
          "type": "string"
        }
      },
      "required": [
        "countryResidence",
        "arrivalCountries",
        "travellers"
      ]
    }
  },
  "required": [
    "tripInfo"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "subscriptionId": {
      "description": "Quote session ID — pass it back as `subscriptionId` to update this quote instead of creating a new one.",
      "type": "string"
    },
    "subscribeUrl": {
      "description": "HelloSafe comparator URL for this quote. The widget already renders clickable buttons — never paste it in the reply.",
      "type": "string"
    },
    "displayOffers": {
      "description": "Priced offers sorted by price, with the recommended offer (isBestScore=true) promoted first.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "description": "HelloSafe offer ID.",
            "type": "number"
          },
          "name": {
            "description": "Commercial name of the offer / formula.",
            "type": "string"
          },
          "insurerName": {
            "description": "Insurer brand name.",
            "type": "string"
          },
          "insurerLogoUrl": {
            "description": "Absolute URL of the insurer logo.",
            "type": "string"
          },
          "priceFullText": {
            "description": "Total price for the whole trip and all travellers, formatted in the display currency (e.g. \"34,20 €\").",
            "type": "string"
          },
          "priceParts": {
            "description": "Price split into rendering parts (used by the widget).",
            "type": "object",
            "properties": {
              "integer": {
                "type": "string"
              },
              "decimal": {
                "type": "string"
              },
              "decimalSeparator": {
                "type": "string"
              },
              "symbol": {
                "type": "string"
              },
              "symbolPosition": {
                "description": "\"prefix\" or \"suffix\".",
                "type": "string"
              }
            },
            "additionalProperties": {}
          },
          "isStartingPrice": {
            "description": "True when the price is a \"from\" price.",
            "type": "boolean"
          },
          "features": {
            "description": "Coverage feature slug → formatted covered amount, already filtered for the trip purpose and converted to the display currency.",
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            }
          },
          "topBanner": {
            "description": "Short marketing highlight for this offer, if any.",
            "type": "string"
          },
          "yesList": {
            "description": "Newline-separated list of advantages.",
            "type": "string"
          },
          "noList": {
            "description": "Newline-separated list of exclusions.",
            "type": "string"
          },
          "faq": {
            "description": "Frequently asked questions about this offer.",
            "type": "array",
            "items": {}
          },
          "suffix": {
            "description": "Price period suffix key: \"perMonth\", \"perYear\", \"perDay\" or empty.",
            "type": "string"
          },
          "isBestScore": {
            "description": "True for the single offer HelloSafe recommends for this trip (shown first).",
            "type": "boolean"
          },
          "subscribeUrl": {
            "description": "HelloSafe comparator URL for this quote. The widget already renders it as a button — never paste it in the reply.",
            "type": "string"
          },
          "complementsCard": {
            "description": "Only when the quote carries a cardId: labels of the card's coverage gaps this offer fills — what it adds over the user's card.",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": {}
      }
    },
    "tripInfo": {
      "description": "Normalized trip parameters the quote was computed with.",
      "type": "object",
      "properties": {
        "intentName": {
          "description": "Human-readable trip purpose.",
          "type": "string"
        },
        "countryResidenceCode": {
          "type": "string"
        },
        "countryResidenceName": {
          "type": "string"
        },
        "arrivalCountriesCodes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "arrivalCountriesNames": {
          "description": "Destination country names in the response locale.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "startDate": {
          "type": "string"
        },
        "endDate": {
          "type": "string"
        },
        "startDateLabel": {
          "type": "string"
        },
        "endDateLabel": {
          "type": "string"
        },
        "numberOfDays": {
          "type": "number"
        },
        "travellers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "age": {
                "type": "number"
              }
            },
            "additionalProperties": {}
          }
        },
        "currency": {
          "description": "ISO 4217 currency the amounts are shown in.",
          "type": "string"
        },
        "tripPrice": {
          "description": "Trip cost per traveller; -1 when not provided.",
          "type": "number"
        },
        "tripPriceText": {
          "type": "string"
        },
        "isAnnual": {
          "type": "boolean"
        },
        "shouldCoverCancellation": {
          "type": "boolean"
        },
        "tripBoughtDateLabel": {
          "type": "string"
        }
      },
      "additionalProperties": {}
    },
    "translations": {
      "description": "Localized UI strings consumed by the widget — not meant for the assistant.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "cardContext": {
      "description": "Present only when the quote was computed against a card (cardId argument): the card and its gaps.",
      "type": "object",
      "properties": {
        "cardId": {
          "type": "number"
        },
        "cardName": {
          "type": "string"
        },
        "gaps": {
          "description": "The card coverage gaps that drove the offer ranking.",
          "type": "array",
          "items": {}
        },
        "unknown": {
          "type": "array",
          "items": {}
        },
        "cancellationOnlyGap": {
          "type": "boolean"
        }
      },
      "additionalProperties": {}
    },
    "_assistantGuidance": {
      "description": "Guidance for the assistant reply — follow \"instruction\".",
      "type": "object",
      "properties": {
        "instruction": {
          "description": "How the assistant should present the result to the user.",
          "type": "string"
        },
        "recommendedOffer": {
          "description": "Compact summary of the offer HelloSafe recommends for this trip.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "insurerName": {
                  "type": "string"
                },
                "price": {
                  "type": "string"
                },
                "coverages": {
                  "description": "Coverage label → covered amount for the recommended offer.",
                  "type": "object",
                  "propertyNames": {
                    "type": "string"
                  },
                  "additionalProperties": {
                    "type": "string"
                  }
                }
              },
              "additionalProperties": {}
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "additionalProperties": {}
    },
    "error": {
      "description": "Human-readable reason when the quote could not be generated. Absent on success.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Use HelloSafe to check what travel insurance a credit card already includes, from the card's real terms & conditions. Call whenever the user asks what their card covers for a trip (medical, cancellation, baggage, ski…), whether their card is enough, or mentions relying on their card's insurance. Identify the card from its name (and bank / country when given). Returns the real covered guarantees with amounts and conditions, plus the coverage gaps for the trip. If gaps exist, offer to get complementary travel-insurance quotes via get_quote, passing this card's id as `cardId` so the offers are ranked by how well they fill the gaps. Never invent coverage: only state what this tool returns.

{
  "type": "object",
  "properties": {
    "locale": {
      "description": "Language the user is conversing in, as a BCP 47 tag or 2-letter code (e.g. \"fr\", \"pt-BR\"). ALWAYS pass it.",
      "type": "string"
    },
    "cardQuery": {
      "description": "Card name as the user said it, expanded (\"American Express Platinum\", not \"Amex Plat\"). Include the bank when known (\"Chase Sapphire Reserve\"). Omit only when cardId is provided.",
      "type": "string"
    },
    "cardId": {
      "description": "Exact HelloSafe card ID from a previous call — use it to re-check a specific candidate instead of fuzzy matching.",
      "type": "number"
    },
    "bankCountry": {
      "description": "ISO-2 country of the issuing bank (e.g. \"US\", \"FR\"). Defaults to the user's country of residence when known — greatly improves matching.",
      "type": "string"
    },
    "network": {
      "description": "Card network when stated: \"Visa\", \"Mastercard\", \"Amex\".",
      "type": "string"
    },
    "tripContext": {
      "description": "Optional trip details — sharpen the gap analysis. Omit what you do not know.",
      "type": "object",
      "properties": {
        "arrivalCountries": {
          "description": "Destination countries as ISO-2 codes, when the user mentioned a trip.",
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z]{2}$"
          }
        },
        "intent": {
          "description": "Trip purpose when known — same values as get_quote (forTourism, mountainTrip, schengenArea…). Drives the thresholds (e.g. ski cover checked for mountainTrip).",
          "type": "string"
        },
        "shouldCoverCancellation": {
          "description": "True when the user cares about cancellation cover.",
          "type": "boolean"
        },
        "shouldCoverExtremeSports": {
          "description": "True for ski / diving / mountaineering trips.",
          "type": "boolean"
        }
      }
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "card": {
      "description": "The card the analysis is about.",
      "type": "object",
      "properties": {
        "id": {
          "description": "HelloSafe card ID — pass to get_quote as `cardId` to get offers that complement this card, or back to this tool to re-check a specific candidate.",
          "type": "number"
        },
        "name": {
          "description": "Card commercial name.",
          "type": "string"
        },
        "bankName": {
          "type": "string"
        },
        "network": {
          "description": "Visa, Mastercard, Amex…",
          "type": "string"
        },
        "bankCountry": {
          "description": "ISO-2 country of the issuing bank.",
          "type": "string"
        },
        "currency": {
          "description": "Currency of the card guarantee amounts.",
          "type": "string"
        },
        "score": {
          "description": "HelloSafe score for the card travel cover.",
          "type": "number"
        }
      },
      "additionalProperties": {}
    },
    "allGuarantees": {
      "description": "The card's FULL guarantee sheet, grouped by section (travel first) — render as one markdown table per section: Guarantee | Your card | Recommended | Verdict.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tab": {
            "description": "Section key: travelInsurance | carRental | winterSports | protection.",
            "type": "string"
          },
          "tabLabel": {
            "description": "Human-readable section title.",
            "type": "string"
          },
          "features": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "coverage": {
                  "description": "What the card provides, formatted.",
                  "type": "string"
                },
                "recommended": {
                  "description": "The coverage HelloSafe recommends, when defined.",
                  "type": "string"
                },
                "verdict": {
                  "description": "excellent | ok | below_recommended | misleading | not_covered.",
                  "type": "string"
                },
                "franchise": {
                  "type": "string"
                },
                "conditions": {
                  "type": "string"
                }
              },
              "additionalProperties": {}
            }
          }
        },
        "additionalProperties": {}
      }
    },
    "covered": {
      "description": "Travel guarantees the card really includes, with amounts and conditions from the card T&Cs.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "description": "Feature slug — same slugs as get_quote offer features.",
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "coverage": {
            "description": "Formatted covered amount from the card T&Cs.",
            "type": "string"
          },
          "badge": {
            "description": "excellent | covered | misleading | not_covered.",
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "franchise": {
            "description": "Deductible, when any.",
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "conditions": {
            "description": "Conditions for the guarantee to apply (e.g. trip paid with the card).",
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "exclusions": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": {}
      }
    },
    "gaps": {
      "description": "Guarantees missing or insufficient for the trip — the offer features a complementary policy should provide.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "description": "Offer feature slug that fills this gap.",
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "reason": {
            "description": "not_covered | misleading | below_recommended | below_destination_threshold.",
            "type": "string"
          },
          "cardCoverage": {
            "description": "What the card actually provides, for contrast.",
            "type": "string"
          },
          "thresholdLabel": {
            "description": "Why the amount is considered insufficient.",
            "type": "string"
          }
        },
        "additionalProperties": {}
      }
    },
    "unknown": {
      "description": "Core guarantees with no data on this card — phrase as \"not documented, check your contract\", never as \"not covered\".",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        },
        "additionalProperties": {}
      }
    },
    "cancellationOnlyGap": {
      "description": "True when cancellation is the ONLY gap — suggest a cancellation-only policy (intent \"cancellation\" in get_quote), usually much cheaper.",
      "type": "boolean"
    },
    "alternatives": {
      "description": "Other cards matching the query. If the analysed card is not the user's, ask which one and call again with its cardId.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "description": "HelloSafe card ID — pass to get_quote as `cardId` to get offers that complement this card, or back to this tool to re-check a specific candidate.",
            "type": "number"
          },
          "name": {
            "description": "Card commercial name.",
            "type": "string"
          },
          "bankName": {
            "type": "string"
          },
          "network": {
            "description": "Visa, Mastercard, Amex…",
            "type": "string"
          },
          "bankCountry": {
            "description": "ISO-2 country of the issuing bank.",
            "type": "string"
          },
          "currency": {
            "description": "Currency of the card guarantee amounts.",
            "type": "string"
          },
          "score": {
            "description": "HelloSafe score for the card travel cover.",
            "type": "number"
          }
        },
        "additionalProperties": {}
      }
    },
    "error": {
      "description": "Human-readable reason when the check could not run. Absent on success.",
      "type": "string"
    },
    "_assistantGuidance": {
      "type": "object",
      "properties": {
        "instruction": {
          "type": "string"
        }
      },
      "additionalProperties": {}
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}