Jinko MCP

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "origins",
    "trip_type"
  ],
  "properties": {
    "locale": {
      "type": "string",
      "description": "User's BCP 47 locale inferred from the conversation (e.g. \"fr-FR\", \"en-US\", \"ja-JP\"). Used for formatting dates, numbers, and selecting currency. Infer from the user's language and location context."
    },
    "origins": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "description": "REQUIRED. Array of origin IATA codes (3-letter uppercase), representing either airports or cities where the trip starts. The LLM MUST detect and include all relevant nearby airports or city codes based on the user’s location. Examples: [\"JFK\", \"LGA\", \"EWR\"] for New York City; [\"SFO\", \"OAK\", \"SJC\"] for the San Francisco Bay Area; [\"ORD\", \"MDW\"] for Chicago; or a single city code like [\"NYC\"]. A code that names a multi-airport city (NYC, LON, PAR — and LAX, MIA, LAS, which a city shares with its main airport) covers every airport of that city; any other code is that one airport."
    },
    "sort_by": {
      "enum": [
        "lowest",
        "recommendation"
      ],
      "type": "string",
      "description": "Sorting preference for search results. Options: \"lowest\" (cheapest first, default) or \"recommendation\" (best overall balance of price, duration, and stops)."
    },
    "currency": {
      "type": "string",
      "description": "ISO 4217 currency code for displaying prices (e.g. \"EUR\", \"USD\", \"GBP\"). Infer from the user's country or locale. If the user mentions a specific currency, use that."
    },
    "max_price": {
      "anyOf": [
        {
          "type": "number",
          "exclusiveMinimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Maximum price PER PERSON: the cap applies to a one-adult fare, in the requested currency. For a whole-party budget, divide it by the number of ADULTS only and treat the result as a loose pre-filter: children and lap infants usually cost less than an adult, so dividing by every traveller would exclude affordable trips. Send a per-person budget as-is. The exact whole-trip budget check is flight_search with max_price."
    },
    "stay_days": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 365,
          "minimum": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "Exact number of days to stay at the destination. Used with a departure date to automatically compute the return date. Example: 7 = one-week trip; 3 = weekend getaway."
    },
    "trip_type": {
      "enum": [
        "oneway",
        "roundtrip"
      ],
      "type": "string",
      "description": "REQUIRED. Type of trip: \"oneway\" for single-leg flights, or \"roundtrip\" for return flights."
    },
    "cabin_class": {
      "anyOf": [
        {
          "enum": [
            "economy",
            "premium_economy",
            "business",
            "first"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Preferred cabin class. Options: \"economy\", \"premium_economy\", \"business\", or \"first\". Filters results accordingly."
    },
    "direct_only": {
      "type": "boolean",
      "description": "When true, only returns nonstop (direct) flights. Useful for avoiding layovers or minimizing total travel time."
    },
    "user_intent": {
      "type": "string",
      "description": "A concise summary of what the user is trying to accomplish, derived from their message or the\nconversation context that triggered this tool call.\nThis is used to understand the user's intent and context to improve the overall user experience.\n\n- For short, self-contained prompts (e.g. \"I want new shoes\"), copy the user message as-is.\n- For longer conversations or detailed requests, summarize the core goal and any relevant\n  context in 1-2 sentences. Focus on intent, constraints, and preferences - not the full\n  dialogue.\n\nBefore sending, strip all personally identifiable information (PII), including but not\nlimited to:\n  - Names (first, last, usernames, handles)\n  - Email addresses\n  - Phone numbers\n  - Physical addresses (street, city, zip/postal code, country when tied to an individual)\n  - Dates of birth or exact ages\n  - Government-issued ID numbers (SSN, passport, driver's license, etc.)\n  - Payment or financial information (card numbers, bank accounts, etc.)\n  - IP addresses or device identifiers\n  - Account credentials (passwords, tokens, API keys)\n  - Health or biometric data\n  - Any other information that could identify a specific individual\n\nReplace stripped values with a generic placeholder (e.g. \"[name]\", \"[email]\", \"[address]\").\n\nExamples:\n  User: \"I want red running shoes under $100\"\n  -> \"I want red running shoes under $100\"\n\n  User: \"Hi, I'm John Smith, [email protected], and I'm looking for flights from Paris to\n         Tokyo for 2 adults departing around mid-June, budget around EUR2000 total\"\n  -> \"Looking for flights from Paris to Tokyo for 2 adults, mid-June, budget ~EUR2000\"\n\n  User: \"I need help resetting my password for account ID acct_12345\"\n  -> \"I need help resetting my password for account ID [account_id]\""
    },
    "destinations": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "OPTIONAL. Array of destination IATA codes (3-letter uppercase), representing either airports or cities. When a city code is provided, the LLM MUST expand it to include all associated airports. Examples: [\"LHR\", \"LGW\", \"STN\", \"LTN\", \"LCY\"] for London airports; [\"CDG\", \"ORY\"] for Paris; [\"TYO\"] for all Tokyo airports. You may mix airport and city codes: [\"JFK\", \"CDG\", \"LON\", \"PAR\"]. A code that names a multi-airport city (NYC, LON, PAR — and LAX, MIA, LAS, which a city shares with its main airport) covers every airport of that city; any other code is that one airport. When omitted or empty, the system searches globally to discover the best flight deals (destination discovery mode)."
    },
    "return_dates": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "List of specific return dates for round-trip searches (YYYY-MM-DD). Must be after the corresponding departure dates. Supports multiple options (OR logic). Example: [\"2025-12-22\", \"2025-12-23\", \"2025-12-24\"]."
    },
    "departure_dates": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of specific departure dates in ISO 8601 format (YYYY-MM-DD). Use for searching multiple specific dates with OR logic. Example: [\"2025-12-15\", \"2025-12-16\", \"2025-12-17\"] for flexible date searches. Useful when user wants to check specific dates like weekends."
    },
    "stay_days_range": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "min",
            "max"
          ],
          "properties": {
            "max": {
              "type": "integer",
              "maximum": 365,
              "description": "Maximum stay duration in days"
            },
            "min": {
              "type": "integer",
              "minimum": 1,
              "description": "Minimum stay duration in days"
            }
          },
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Range of acceptable trip durations for flexible planning (e.g., “5 to 10 days”). Cannot be combined with stay_days or explicit return_date. Example: {min: 5, max: 10}."
    },
    "return_date_ranges": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "start",
              "end"
            ],
            "properties": {
              "end": {
                "type": "string",
                "description": "Range end date (YYYY-MM-DD)"
              },
              "start": {
                "type": "string",
                "description": "Range start date (YYYY-MM-DD)"
              }
            },
            "additionalProperties": false
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "List of return date ranges for flexible round-trip searches. Supports multiple return windows. Example: [{start: \"2025-12-22\", end: \"2025-12-25\"}, {start: \"2025-12-29\", end: \"2026-01-02\"}]."
    },
    "departure_date_ranges": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "start",
          "end"
        ],
        "properties": {
          "end": {
            "type": "string",
            "description": "Range end date (YYYY-MM-DD)"
          },
          "start": {
            "type": "string",
            "description": "Range start date (YYYY-MM-DD)"
          }
        },
        "additionalProperties": false
      },
      "description": "List of departure date ranges for flexible travel discovery. Use when the user mentions periods like “next month” or “spring.” Supports multiple non-contiguous ranges (OR logic). Example: [{start: \"2025-12-10\", end: \"2025-12-15\"}, {start: \"2025-12-20\", end: \"2025-12-25\"}]."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "origin",
    "destination",
    "trip_type"
  ],
  "properties": {
    "locale": {
      "type": "string",
      "description": "User's BCP 47 locale inferred from the conversation (e.g. \"fr-FR\", \"en-US\", \"ja-JP\"). Used for formatting dates, numbers, and selecting currency. Infer from the user's language and location context."
    },
    "origin": {
      "type": "string",
      "maxLength": 3,
      "minLength": 3,
      "description": "REQUIRED: Single origin IATA airport code or IATA city code. Airport codes: \"JFK\" for John F. Kennedy in New York, \"LGW\" for Gatwick in London. City codes: \"NYC\" for New York, \"LON\" for London, \"PAR\" for Paris. A code that names a multi-airport city (NYC, LON, PAR — and LAX, MIA, LAS, which a city shares with its main airport) covers every airport of that city; any other code is that one airport."
    },
    "sort_by": {
      "enum": [
        "lowest",
        "recommendation"
      ],
      "type": "string",
      "description": "Sort results by this criteria. Default: lowest (best deals first). Options: lowest (cheapest flights), recommendation (best overall value considering price, duration, and stops)."
    },
    "currency": {
      "type": "string",
      "description": "ISO 4217 currency code for displaying prices (e.g. \"EUR\", \"USD\", \"GBP\"). Infer from the user's country or locale. If the user mentions a specific currency, use that."
    },
    "max_price": {
      "anyOf": [
        {
          "type": "number",
          "exclusiveMinimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Maximum price PER PERSON: the cap applies to a one-adult fare, in the requested currency. For a whole-party budget, divide it by the number of ADULTS only and treat the result as a loose pre-filter: children and lap infants usually cost less than an adult, so dividing by every traveller would exclude affordable trips. Send a per-person budget as-is. The exact whole-trip budget check is flight_search with max_price."
    },
    "stay_days": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 365,
          "minimum": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "Exact number of days to stay at destination. Used with departure_date to calculate return date automatically. Example: 7 for a week-long trip, 3 for a weekend getaway."
    },
    "trip_type": {
      "enum": [
        "oneway",
        "roundtrip"
      ],
      "type": "string",
      "description": "REQUIRED: Trip type: \"oneway\" for one-way flights or \"roundtrip\" for round-trip flights."
    },
    "cabin_class": {
      "anyOf": [
        {
          "enum": [
            "economy",
            "premium_economy",
            "business",
            "first"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Cabin class preference. Options: \"economy\" (standard economy), \"premium_economy\" (enhanced economy with more space/amenities), \"business\" (business class), \"first\" (first class). When specified, only shows flights in the requested cabin class."
    },
    "destination": {
      "type": "string",
      "maxLength": 3,
      "minLength": 3,
      "description": "REQUIRED: Single destination IATA airport code or IATA city code. Airport codes: \"CDG\" for Paris Charles de Gaulle, \"SFO\" for San Francisco. City codes: \"PAR\" for Paris, \"BJS\" for Beijing, \"LAX\" for Los Angeles (LAX is the city code too). A code that names a multi-airport city (NYC, LON, PAR — and LAX, MIA, LAS, which a city shares with its main airport) covers every airport of that city; any other code is that one airport."
    },
    "direct_only": {
      "type": "boolean",
      "description": "Only show direct/nonstop flights. When true, only flights with no stops are returned. Use for fastest travel or when layovers are not desired."
    },
    "user_intent": {
      "type": "string",
      "description": "A concise summary of what the user is trying to accomplish, derived from their message or the\nconversation context that triggered this tool call.\nThis is used to understand the user's intent and context to improve the overall user experience.\n\n- For short, self-contained prompts (e.g. \"I want new shoes\"), copy the user message as-is.\n- For longer conversations or detailed requests, summarize the core goal and any relevant\n  context in 1-2 sentences. Focus on intent, constraints, and preferences - not the full\n  dialogue.\n\nBefore sending, strip all personally identifiable information (PII), including but not\nlimited to:\n  - Names (first, last, usernames, handles)\n  - Email addresses\n  - Phone numbers\n  - Physical addresses (street, city, zip/postal code, country when tied to an individual)\n  - Dates of birth or exact ages\n  - Government-issued ID numbers (SSN, passport, driver's license, etc.)\n  - Payment or financial information (card numbers, bank accounts, etc.)\n  - IP addresses or device identifiers\n  - Account credentials (passwords, tokens, API keys)\n  - Health or biometric data\n  - Any other information that could identify a specific individual\n\nReplace stripped values with a generic placeholder (e.g. \"[name]\", \"[email]\", \"[address]\").\n\nExamples:\n  User: \"I want red running shoes under $100\"\n  -> \"I want red running shoes under $100\"\n\n  User: \"Hi, I'm John Smith, [email protected], and I'm looking for flights from Paris to\n         Tokyo for 2 adults departing around mid-June, budget around EUR2000 total\"\n  -> \"Looking for flights from Paris to Tokyo for 2 adults, mid-June, budget ~EUR2000\"\n\n  User: \"I need help resetting my password for account ID acct_12345\"\n  -> \"I need help resetting my password for account ID [account_id]\""
    },
    "return_dates": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "List of specific return dates for round-trip flights (YYYY-MM-DD). Use for searching multiple return date options with OR logic. Must be after departure dates. Example: [\"2025-12-22\", \"2025-12-23\", \"2025-12-24\"]"
    },
    "departure_dates": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of specific departure dates in ISO 8601 format (YYYY-MM-DD). Use for searching multiple specific dates with OR logic. Example: [\"2025-12-15\", \"2025-12-16\", \"2025-12-17\"] for flexible date searches. Useful when user wants to check specific dates like weekends."
    },
    "stay_days_range": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "min",
            "max"
          ],
          "properties": {
            "max": {
              "type": "integer",
              "maximum": 365,
              "description": "Maximum stay duration in days"
            },
            "min": {
              "type": "integer",
              "minimum": 1,
              "description": "Minimum stay duration in days"
            }
          },
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Flexible stay duration range. Use when user wants flexibility in trip length (e.g., \"5 to 10 days\"). Cannot be combined with exact stay_days or return_date. Example: {min: 5, max: 10}"
    },
    "arrival_time_range": {
      "type": "object",
      "properties": {
        "latest": {
          "type": "string",
          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
          "description": "Inclusive latest local time-of-day (HH:MM, 24-hour)."
        },
        "earliest": {
          "type": "string",
          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
          "description": "Inclusive earliest local time-of-day (HH:MM, 24-hour)."
        }
      },
      "description": "Filter the OUTBOUND leg by local arrival time-of-day. Example: { \"latest\": \"20:00\" } to arrive by 8pm. Use when the user says \"arrive before dinner\", \"land by noon\", etc.",
      "additionalProperties": false
    },
    "return_date_ranges": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "start",
              "end"
            ],
            "properties": {
              "end": {
                "type": "string",
                "description": "Range end date (YYYY-MM-DD)"
              },
              "start": {
                "type": "string",
                "description": "Range start date (YYYY-MM-DD)"
              }
            },
            "additionalProperties": false
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "List of return date ranges for flexible round-trip exploration. Use when user wants flexibility on return timing across multiple periods with OR logic. Example: [{start: \"2025-12-22\", end: \"2025-12-25\"}, {start: \"2025-12-29\", end: \"2026-01-02\"}]"
    },
    "departure_time_range": {
      "type": "object",
      "properties": {
        "latest": {
          "type": "string",
          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
          "description": "Inclusive latest local time-of-day (HH:MM, 24-hour)."
        },
        "earliest": {
          "type": "string",
          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
          "description": "Inclusive earliest local time-of-day (HH:MM, 24-hour)."
        }
      },
      "description": "Filter the OUTBOUND leg by local departure time-of-day. Example: { \"earliest\": \"08:00\", \"latest\": \"12:00\" } for a late-morning departure. Use when the user says \"morning flight\", \"leave after 6pm\", etc.",
      "additionalProperties": false
    },
    "departure_date_ranges": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "start",
          "end"
        ],
        "properties": {
          "end": {
            "type": "string",
            "description": "Range end date (YYYY-MM-DD)"
          },
          "start": {
            "type": "string",
            "description": "Range start date (YYYY-MM-DD)"
          }
        },
        "additionalProperties": false
      },
      "description": "List of departure date ranges for flexible travel exploration. Use when user says \"next month\", \"spring\", or wants to discover deals across multiple date periods with OR logic. Example: [{start: \"2025-12-10\", end: \"2025-12-15\"}, {start: \"2025-12-20\", end: \"2025-12-25\"}] for non-contiguous periods."
    },
    "return_arrival_time_range": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "latest": {
              "type": "string",
              "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
              "description": "Inclusive latest local time-of-day (HH:MM, 24-hour)."
            },
            "earliest": {
              "type": "string",
              "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
              "description": "Inclusive earliest local time-of-day (HH:MM, 24-hour)."
            }
          },
          "description": "Local time-of-day window (\"HH:MM\", 24-hour). Either bound may be omitted.",
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Round-trip only. Filter the RETURN leg by local arrival time-of-day."
    },
    "return_departure_time_range": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "latest": {
              "type": "string",
              "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
              "description": "Inclusive latest local time-of-day (HH:MM, 24-hour)."
            },
            "earliest": {
              "type": "string",
              "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
              "description": "Inclusive earliest local time-of-day (HH:MM, 24-hour)."
            }
          },
          "description": "Local time-of-day window (\"HH:MM\", 24-hour). Either bound may be omitted.",
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Round-trip only. Filter the RETURN leg by local departure time-of-day."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "locale": {
      "type": "string",
      "description": "User's BCP 47 locale inferred from the conversation (e.g. \"fr-FR\", \"en-US\", \"ja-JP\"). Used for formatting dates, numbers, and selecting currency."
    },
    "search": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "limit": {
              "type": "integer",
              "maximum": 300,
              "minimum": 1,
              "description": "TOTAL number of flights returned (1–300). Caps the whole result set, not a per-page size; it only trims what comes back, since the providers still bound the real count."
            },
            "origin": {
              "type": "string",
              "pattern": "^[A-Z]{3}$",
              "description": "Origin IATA city code (e.g. PAR, NYC, LON) or airport code (e.g. CDG, JFK, LHR). A city code searches every airport of the city, which is what a user naming a city wants. ALWAYS convert place names to codes yourself before calling (Paris → PAR, Mexico City → MEX, Miami → MIA); a name like \"Paris\" fails validation. See origin_type for how an untyped code is read. Required."
            },
            "max_price": {
              "type": "number",
              "description": "Maximum total price for the whole trip and ALL passengers together, in the requested currency. Send the user's whole-trip budget unchanged, or multiply a per-person budget by the number of passengers.",
              "exclusiveMinimum": 0
            },
            "max_stops": {
              "type": "integer",
              "maximum": 2,
              "minimum": 0,
              "description": "Maximum stops per leg (0-2). 0 = nonstop — send `max_stops: 0` when the user says \"direct only\" / \"non-stop\" / \"no layovers\"; 1 when the user says \"at most one stop\"."
            },
            "trip_type": {
              "enum": [
                "oneway",
                "roundtrip"
              ],
              "type": "string",
              "description": "Optional. Derived from return_date when omitted."
            },
            "multi_fare": {
              "type": "boolean",
              "description": "Defaults to TRUE: several branded fares per itinerary (the upsell ladder). Set false for a single fare per itinerary and much smaller responses."
            },
            "cabin_class": {
              "anyOf": [
                {
                  "enum": [
                    "economy",
                    "premium_economy",
                    "business",
                    "first"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Cabin class filter. Use null when the user did not explicitly request a cabin; null or omission lets the provider use economy as its search default without filtering returned fares by cabin. When the user explicitly requests economy, premium economy, business, or first, send that value; results must match it on the longest segment, while shorter segments may use another cabin."
            },
            "destination": {
              "type": "string",
              "pattern": "^[A-Z]{3}$",
              "description": "Destination IATA city code (e.g. MIL, BCN, TYO) or airport code (e.g. MXP, BCN, NRT). A city code searches every airport of the city, which is what a user naming a city wants. ALWAYS convert place names to codes yourself before calling (Tokyo → TYO, São Paulo → SAO); a name like \"Tokyo\" fails validation. See destination_type for how an untyped code is read — LAX alone is the Los Angeles CITY. Required."
            },
            "direct_only": {
              "type": "boolean",
              "description": "DEPRECATED — send `max_stops: 0` instead. Still accepted: `direct_only: true` is folded into `max_stops: 0` before the search runs and only `max_stops` reaches the platform. Setting it beside a non-zero `max_stops` is an error."
            },
            "origin_type": {
              "enum": [
                "city",
                "airport"
              ],
              "type": "string",
              "description": "How to read origin: \"city\" searches every airport of the city; \"airport\" only that one airport. With no type sent, the platform applies one rule: a code that names a multi-airport city is searched as the city; every other code is searched as the airport. NYC, LON, PAR → the city. JFK, LHR, CDG → the airport. LAX, MIA, LAS — codes a city shares with its main airport — → the CITY, every airport of it. If the user named the airport (\"LAX\", \"JFK\", \"Heathrow\"), send \"airport\"; if they named the city (\"Los Angeles\", \"New York\"), send the city code and omit the type. On a live search the provider decides which airports a city holds, so untyped LAX returns flights into other Los Angeles airports — Ontario (ONT) among them, often as the cheapest offers. Each offer reports the airports flown on its legs; the offer-level city code does not change."
            },
            "return_date": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "Single return date (YYYY-MM-DD) for a round trip. Omit for one-way."
            },
            "via_airports": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[A-Z]{3}$"
              },
              "description": "Restrict connections to these IATA airport codes. Nonstop itineraries still pass. Example: [\"CDG\",\"AMS\"]. Every connection in a returned itinerary is at a listed airport; sources search at most 9 per leg. Must not overlap exclude_via_airports."
            },
            "aircraft_types": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[A-Z0-9]{3}$"
              },
              "description": "Restrict every segment to these IATA aircraft equipment codes. Example: [\"320\",\"321\"]. Use only when the user names equipment; most users do not."
            },
            "departure_date": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "Single departure date (YYYY-MM-DD) — no arrays or ranges. Required."
            },
            "changeable_only": {
              "type": "boolean",
              "description": "Keep only fares that allow a voluntary change (with or without a fee). Same conservative behavior as refundable_only. Each returned fare echoes the resolved `changeable` flag."
            },
            "nearby_airports": {
              "type": "boolean",
              "description": "Ask the providers to also search alternate airports around each leg's origin and destination. WIDENS the search. Use when the user says \"or any nearby airport\"."
            },
            "refundable_only": {
              "type": "boolean",
              "description": "Keep only fares that can be cancelled before departure (with or without a fee). Narrowing and conservative: fares whose rules cannot be verified are dropped, so some carriers disappear entirely. Each returned fare echoes the resolved `refundable` flag."
            },
            "destination_type": {
              "enum": [
                "city",
                "airport"
              ],
              "type": "string",
              "description": "How to read destination: \"city\" searches every airport of the city; \"airport\" only that one airport. With no type sent, the platform applies one rule: a code that names a multi-airport city is searched as the city; every other code is searched as the airport. NYC, LON, PAR → the city. JFK, LHR, CDG → the airport. LAX, MIA, LAS — codes a city shares with its main airport — → the CITY, every airport of it. If the user named the airport (\"LAX\", \"JFK\", \"Heathrow\"), send \"airport\"; if they named the city (\"Los Angeles\", \"New York\"), send the city code and omit the type. On a live search the provider decides which airports a city holds, so untyped LAX returns flights into other Los Angeles airports — Ontario (ONT) among them, often as the cheapest offers. Each offer reports the airports flown on its legs; the offer-level city code does not change."
            },
            "exclude_carriers": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[A-Z0-9]{2}$"
              },
              "description": "IATA 2-letter marketing carrier codes to exclude (blacklist). Example: [\"FR\",\"U2\"]. ALWAYS convert airline names to codes yourself (Ryanair → FR, Frontier → F9); a name like \"Ryanair\" fails validation. A brand that operates several marketing carriers needs every code listed (\"no Wizz Air\" → W6, W9). Use when the user says \"no Ryanair\", \"avoid budget airlines\", etc. Must not overlap include_carriers."
            },
            "include_carriers": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[A-Z0-9]{2}$"
              },
              "description": "IATA 2-letter marketing carrier codes to include (whitelist). Example: [\"AF\",\"KL\"]. ALWAYS convert airline names to codes yourself (Air France → AF, Delta → DL); a name like \"Delta\" fails validation. A brand that operates several marketing carriers needs every code listed (easyJet → U2, EC, DS). Use when the user says \"Air France only\", \"fly Delta\", etc. Must not overlap exclude_carriers. Matching means EVERY segment is marketed by a listed carrier (codeshares count by marketing carrier). When nothing matches, the search returns no offers with reason no_matches; the platform never widens to other carriers. Tell the user no itinerary satisfied the airline filter and ask which filter to relax."
            },
            "arrival_time_range": {
              "type": "object",
              "properties": {
                "latest": {
                  "type": "string",
                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                  "description": "Inclusive latest local time-of-day (HH:MM, 24-hour)."
                },
                "earliest": {
                  "type": "string",
                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                  "description": "Inclusive earliest local time-of-day (HH:MM, 24-hour)."
                }
              },
              "description": "Filter the OUTBOUND leg by local arrival time-of-day. Example: { \"latest\": \"20:00\" }. Use when the user says \"arrive before dinner\", \"land by noon\".",
              "additionalProperties": false
            },
            "single_carrier_only": {
              "type": "boolean",
              "description": "Keep only itineraries marketed by ONE carrier end to end. Use when the user says \"same airline the whole way\" or wants to avoid split-carrier connections."
            },
            "checked_bag_included": {
              "type": "boolean",
              "description": "Keep only fares whose price already includes a checked bag. Use when the user says \"with a bag included\", \"I need to check luggage\"."
            },
            "departure_time_range": {
              "type": "object",
              "properties": {
                "latest": {
                  "type": "string",
                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                  "description": "Inclusive latest local time-of-day (HH:MM, 24-hour)."
                },
                "earliest": {
                  "type": "string",
                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                  "description": "Inclusive earliest local time-of-day (HH:MM, 24-hour)."
                }
              },
              "description": "Filter the OUTBOUND leg by local departure time-of-day. Example: { \"earliest\": \"08:00\", \"latest\": \"12:00\" }. Use when the user says \"morning flight\", \"leave after 6pm\".",
              "additionalProperties": false
            },
            "exclude_via_airports": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[A-Z]{3}$"
              },
              "description": "Ban connections at these IATA airport codes. Example: [\"LHR\"] when the user says \"anything but Heathrow\". Lists longer than 9 are still fully enforced. Must not overlap via_airports."
            },
            "same_origin_airport_only": {
              "type": "boolean",
              "description": "Round trips only: keep itineraries that return to the departure airport."
            },
            "origin_alternate_airports": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[A-Z]{3}$"
              },
              "description": "ADDITIONAL departure airports searched ALONGSIDE `origin`, e.g. [\"EWR\",\"LGA\"] with `origin: \"JFK\"`. WIDENING ONLY — the anchor in `origin` is always searched. THE ANCHOR RANKS AND TRUNCATES the result set, so put the airport that matters most to the user in `origin`, not in this list: on one measured route, anchor JFK + alternate EWR came back 15 JFK / 35 EWR, while anchor EWR + alternate JFK came back 2 JFK / 48 EWR. Works with an airport or a city anchor: `origin: \"NYC\"` with [\"BOS\"] searches New York's airports and Boston. On a round trip the whole side is mirrored, so these airports also apply to where the RETURN lands. Some sources search only the anchor."
            },
            "return_arrival_time_range": {
              "type": "object",
              "properties": {
                "latest": {
                  "type": "string",
                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                  "description": "Inclusive latest local time-of-day (HH:MM, 24-hour)."
                },
                "earliest": {
                  "type": "string",
                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                  "description": "Inclusive earliest local time-of-day (HH:MM, 24-hour)."
                }
              },
              "description": "Round-trip only. Filter the RETURN leg by local arrival time-of-day.",
              "additionalProperties": false
            },
            "max_total_duration_minutes": {
              "type": "integer",
              "description": "Cap on EACH leg's total elapsed travel time, in minutes (gate to gate, layovers included). Use when the user says \"nothing longer than 12 hours\" → 720.",
              "exclusiveMinimum": 0
            },
            "connection_time_max_minutes": {
              "type": "integer",
              "minimum": 0,
              "description": "Maximum layover length, in minutes, for EVERY connection of EVERY leg. Use when the user says \"no long layovers\" (\"under 3 hours\" → 180)."
            },
            "connection_time_min_minutes": {
              "type": "integer",
              "minimum": 0,
              "description": "Minimum layover length, in minutes, for EVERY connection of EVERY leg. Use when the user wants a comfortable connection (\"at least 90 minutes to change planes\"). Must not exceed connection_time_max_minutes."
            },
            "return_departure_time_range": {
              "type": "object",
              "properties": {
                "latest": {
                  "type": "string",
                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                  "description": "Inclusive latest local time-of-day (HH:MM, 24-hour)."
                },
                "earliest": {
                  "type": "string",
                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                  "description": "Inclusive earliest local time-of-day (HH:MM, 24-hour)."
                }
              },
              "description": "Round-trip only. Filter the RETURN leg by local departure time-of-day.",
              "additionalProperties": false
            },
            "same_connection_airport_only": {
              "type": "boolean",
              "description": "Keep only itineraries whose connections arrive at and depart from the SAME airport (no cross-town airport change)."
            },
            "same_turnaround_airport_only": {
              "type": "boolean",
              "description": "Round trips only: keep itineraries whose return departs from the airport the outbound arrived at."
            },
            "destination_alternate_airports": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[A-Z]{3}$"
              },
              "description": "ADDITIONAL arrival airports searched ALONGSIDE `destination`, e.g. [\"EWR\",\"LGA\"] with `destination: \"JFK\"`. WIDENING ONLY — the anchor in `destination` is always searched. THE ANCHOR RANKS AND TRUNCATES the result set, so put the airport that matters most to the user in `destination`, not in this list: on one measured route, anchor JFK + alternate EWR came back 15 JFK / 35 EWR, while anchor EWR + alternate JFK came back 2 JFK / 48 EWR. Works with an airport or a city anchor: `destination: \"NYC\"` with [\"BOS\"] searches New York's airports and Boston. On a round trip the whole side is mirrored, so these airports also apply to where the RETURN departs from. Some sources search only the anchor."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Live search for a committed itinerary with optional filters. Use it when the user has settled on a route and precise dates: origin + destination + departure_date (+ return_date for a round trip). No date ranges and no date arrays. Any date flexibility (\"give or take a day\", open windows, an ask with no anchor date at all, or a range implying several candidate departure/return pairs) goes to flight_calendar instead."
    },
    "trip_id": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "Existing trip_id to associate this search with. Forward whenever the user is mid-trip-build (you have seen a trip_id in a recent trip(...) tool result and the user has NOT pivoted to a different trip context, e.g. a new origin city or unrelated request). Drop on pivot. Echoed back in the result so the cart widget can append the next selection to the same trip."
    },
    "currency": {
      "type": "string",
      "description": "ISO 4217 currency code for displaying prices (e.g. \"EUR\", \"USD\", \"GBP\", \"JPY\"). ALWAYS set this — omitting it falls back to USD which is rarely what users actually want. Infer from the strongest signal available: (1) the user's explicit ask (\"show me prices in pounds\"), (2) the conversation language/locale (French → EUR, Japanese → JPY, German → EUR, Spanish/Catalan/Italian/Portuguese → EUR, English UK → GBP, English US → USD), (3) the origin city's country (CDG/ORY → EUR, LHR/LGW → GBP, NRT/HND → JPY, JFK/LAX → USD, etc.). When in doubt between two plausible currencies, prefer the one matching the user's likely home country."
    },
    "price_check": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "offer_token"
          ],
          "properties": {
            "max_price": {
              "type": "number",
              "description": "Not applied in price_check (JIN-245); omit even if the upstream call had this filter set. With offer_token present the BFF re-shops closest-match and ignores it, so the candidate can come back above the cap.",
              "exclusiveMinimum": 0
            },
            "cabin_class": {
              "enum": [
                "economy",
                "premium_economy",
                "business",
                "first"
              ],
              "type": "string",
              "description": "Not applied in price_check (JIN-245); omit even if the upstream call had this filter set. With offer_token present the BFF re-shops closest-match and ignores it, so the candidate can come back in a different cabin."
            },
            "direct_only": {
              "type": "boolean",
              "description": "Not applied in price_check (JIN-245); omit even if the upstream call had this filter set. With offer_token present the BFF re-shops closest-match and ignores it, so the candidate can come back with a stopover."
            },
            "offer_token": {
              "type": "string",
              "minLength": 1,
              "description": "offer_token from flight_calendar or find_destination results. Uniquely identifies a specific flight offer for live pricing."
            },
            "exclude_carriers": {
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 2,
                "minLength": 2
              },
              "description": "IATA 2-letter marketing carrier codes (blacklist). Not applied in price_check (JIN-245); omit even if the upstream call had this filter set."
            },
            "include_carriers": {
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 2,
                "minLength": 2
              },
              "description": "IATA 2-letter marketing carrier codes (whitelist). Not applied in price_check (JIN-245); omit even if the upstream call had this filter set."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Get confirmed live fares for a specific flight offer. Returns fare brands with trip_item_token for booking. The BFF treats offer_token and the filter fields (direct_only, cabin_class, max_price, include_carriers, exclude_carriers) as MUTUALLY EXCLUSIVE: when offer_token is present it performs a \"closest-match\" re-shop and ignores all five (JIN-245, still open). Omit them here, and do NOT assume the re-shopped candidate still matches what the user picked upstream — compare the returned offer against their stated preference and say so if it differs. The wider shop filters (max_stops, refundable_only, …) belong to `search` only."
    },
    "user_intent": {
      "type": "string",
      "description": "A concise summary of what the user is trying to accomplish, derived from their message or the\nconversation context that triggered this tool call.\nThis is used to understand the user's intent and context to improve the overall user experience.\n\n- For short, self-contained prompts (e.g. \"I want new shoes\"), copy the user message as-is.\n- For longer conversations or detailed requests, summarize the core goal and any relevant\n  context in 1-2 sentences. Focus on intent, constraints, and preferences - not the full\n  dialogue.\n\nBefore sending, strip all personally identifiable information (PII), including but not\nlimited to:\n  - Names (first, last, usernames, handles)\n  - Email addresses\n  - Phone numbers\n  - Physical addresses (street, city, zip/postal code, country when tied to an individual)\n  - Dates of birth or exact ages\n  - Government-issued ID numbers (SSN, passport, driver's license, etc.)\n  - Payment or financial information (card numbers, bank accounts, etc.)\n  - IP addresses or device identifiers\n  - Account credentials (passwords, tokens, API keys)\n  - Health or biometric data\n  - Any other information that could identify a specific individual\n\nReplace stripped values with a generic placeholder (e.g. \"[name]\", \"[email]\", \"[address]\").\n\nExamples:\n  User: \"I want red running shoes under $100\"\n  -> \"I want red running shoes under $100\"\n\n  User: \"Hi, I'm John Smith, [email protected], and I'm looking for flights from Paris to\n         Tokyo for 2 adults departing around mid-June, budget around EUR2000 total\"\n  -> \"Looking for flights from Paris to Tokyo for 2 adults, mid-June, budget ~EUR2000\"\n\n  User: \"I need help resetting my password for account ID acct_12345\"\n  -> \"I need help resetting my password for account ID [account_id]\""
    },
    "traveler_counts": {
      "type": "object",
      "properties": {
        "adults": {
          "type": "integer",
          "default": 1,
          "maximum": 9,
          "minimum": 1,
          "description": "Number of adult travelers (12+ years)"
        },
        "infants": {
          "type": "integer",
          "default": 0,
          "maximum": 4,
          "minimum": 0,
          "description": "Infant travelers (under 2), traveling on an adult's lap. Seated infants (own seat) are not supported."
        },
        "children": {
          "type": "integer",
          "default": 0,
          "maximum": 8,
          "minimum": 0,
          "description": "Number of child travelers (2-11 years)"
        }
      },
      "description": "Traveler counts. Defaults to 1 adult.",
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "rooms": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 8,
          "minimum": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "Shorthand: number of rooms (the platform auto-distributes adults + children). Use when the user named a room count but not the per-room split."
    },
    "adults": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 16,
          "minimum": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "Shorthand: total adults across all rooms. Use ONLY when there is no ambiguity (1 or 2 adults = single room). For 3+ adults, or odd splits, ask the user how they want to split rooms and pass occupancies[] instead — e.g. 4 adults → [{adults:2},{adults:2}] (double + double) vs a single 4-sleeper is a meaningfully different search. If the user does not clarify, the server defaults to 2-adults-per-room (remainder in the last room), so every 4-adult request becomes two double rooms. Do NOT combine with occupancies[] — use one or the other."
    },
    "checkin": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ],
      "description": "Check-in date (YYYY-MM-DD)."
    },
    "filters": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "offset": {
              "type": "integer",
              "minimum": 0,
              "description": "Skip this many hotels (default 0). Rejected once a search returned search_handle / next_handle: page with next_handle instead."
            },
            "chain_ids": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Filter by hotel chain. Each entry is a brand slug (e.g. \"accor\", \"hilton\") OR a numeric chain id. Slugs are expanded to all sub-brands (e.g. \"accor\" → Accor, ibis, Novotel, Mercure, Pullman, Sofitel, …). Every entry is applied as sent: one that matches no chain is rejected with a validation error."
            },
            "min_rating": {
              "anyOf": [
                {
                  "type": "number",
                  "maximum": 10,
                  "minimum": 0
                },
                {
                  "type": "null"
                }
              ],
              "description": "Minimum guest review rating (0-10 scale). Omitted or 0: no rating floor, unrated hotels included."
            },
            "max_results": {
              "type": "integer",
              "maximum": 200,
              "minimum": 1,
              "description": "Requested page size (default 50); next_handle returns the next page of the same search. A hotel_name or hotel_ids search returns every named hotel that has rates."
            },
            "min_reviews": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": 0
                },
                {
                  "type": "null"
                }
              ],
              "description": "Minimum number of guest reviews."
            },
            "facility_ids": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Filter by hotel facility, applied at platform search time, not post-filtered. Each entry is one of these names (or a numeric facility id): pool, outdoor_pool, indoor_pool, rooftop_pool, infinity_pool, heated_pool, kids_pool, spa, sauna, hot_tub, hammam, gym, parking, free_parking, valet_parking, ev_charging, wifi, free_wifi, restaurant, bar, room_service, airport_shuttle, pets_allowed, family_rooms, air_conditioning, wheelchair_accessible, elevator, 24h_front_desk, beachfront, private_beach, adults_only, kids_club, water_park, golf_course, tennis_court, casino, terrace, garden, non_smoking_rooms, laundry, concierge, business_center, meeting_rooms, shared_kitchen, luggage_storage. For a facility the user requires, send that ONE name: with several entries the standard search keeps hotels having at least one of them, not all. These are hotel-level facilities — breakfast is a rate board type, and sea view, balcony or a private kitchen are room features, none of which can be filtered here. A name outside the list is rejected with the accepted names."
            },
            "hotel_type_ids": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Filter by property type. Each entry is one of these names (or a numeric type id): hotel, apartment, aparthotel, resort, hostel, guesthouse, bed_and_breakfast, inn, ryokan, riad, villa, chalet, cottage, cabin, lodge, holiday_home, country_house, farm_stay, homestay, condo, residence, motel, campsite, luxury_tent, holiday_park, houseboat. Several entries keep properties of ANY of those types. \"boutique\", \"luxury\" or \"romantic\" are styles, not types, and cannot be filtered here. A name outside the list is rejected with the accepted names."
            },
            "max_star_rating": {
              "anyOf": [
                {
                  "type": "integer",
                  "maximum": 5,
                  "minimum": 1
                },
                {
                  "type": "null"
                }
              ],
              "description": "Maximum star rating (1-5). Pair with min_star_rating to bound a range."
            },
            "min_star_rating": {
              "anyOf": [
                {
                  "type": "integer",
                  "maximum": 5,
                  "minimum": 1
                },
                {
                  "type": "null"
                }
              ],
              "description": "Minimum star rating (1-5). Pair with max_star_rating to bound a range."
            },
            "max_budget_per_night": {
              "anyOf": [
                {
                  "type": "number",
                  "exclusiveMinimum": 0
                },
                {
                  "type": "null"
                }
              ],
              "description": "Keep only hotels whose CHEAPEST per-night price (per room, in the request currency) fits this budget; qualifying hotels keep all their rates. Also applies in Mode A (rate lookup)."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional filter overrides applied on top of the tenant default filter set. Every property filter is applied as sent."
    },
    "trip_id": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "Existing trip_id to associate this search with. Used only by the Jinko cart widget. The platform accepts the field on every surface for schema consistency; a surface without the widget does not use it. Forward whenever the user is mid-trip-build (you have seen a trip_id in a recent trip(...) tool result and the user has NOT pivoted to a different trip context, e.g. a new origin OR destination city or unrelated request). Drop on pivot. Echoed back in the result so the cart widget can append the next selection to the same trip."
    },
    "checkout": {
      "anyOf": [
        {
          "$ref": "#/properties/checkin/anyOf/0"
        },
        {
          "type": "null"
        }
      ],
      "description": "Check-out date (YYYY-MM-DD)."
    },
    "children": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "integer",
            "maximum": 17,
            "minimum": 0
          },
          "maxItems": 8
        },
        {
          "type": "null"
        }
      ],
      "description": "Shorthand: ages of all children across all rooms. If children are present, prefer occupancies[] so the caller controls which room each child goes in (ages affect pricing and some providers reject invalid age/room combinations)."
    },
    "currency": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 3,
          "minLength": 3
        },
        {
          "type": "null"
        }
      ],
      "description": "ISO 4217 currency code (e.g. \"EUR\", \"USD\", \"GBP\", \"JPY\"). ALWAYS set this — omitting it falls back to USD which is rarely what users actually want. Infer from the strongest signal available: (1) the user's explicit ask (\"show me prices in pounds\"), (2) the conversation language/locale (French → EUR, Japanese → JPY, German → EUR, Spanish/Catalan/Italian/Portuguese → EUR, English UK → GBP, English US → USD), (3) the destination country (Italy/France/Germany → EUR, UK → GBP, Japan → JPY, US → USD). When in doubt between two plausible currencies, prefer the one matching the user's likely home country."
    },
    "destination": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "query": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 200,
                  "minLength": 1
                },
                {
                  "type": "null"
                }
              ],
              "description": "Free-text destination (for example \"Paris\", \"Times Square\", \"Menorca\" or \"Tuscany\"). The platform parses it once into a city + country or coordinates, then applies the same shared location normalization as structured inputs; the raw query is not forwarded to a supplier. Max 200 chars."
            },
            "latitude": {
              "anyOf": [
                {
                  "type": "number",
                  "maximum": 90,
                  "minimum": -90
                },
                {
                  "type": "null"
                }
              ],
              "description": "Latitude for geo-radius search. Pair with longitude."
            },
            "city_name": {
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 1
                },
                {
                  "type": "null"
                }
              ],
              "description": "City name (e.g. \"Paris\"). Spell it the way an English-language booking site would: \"Munich\" not \"München\", \"Florence\" not \"Firenze\", \"Rome\" not \"Roma\", \"Vienna\" not \"Wien\". Keep the local form where that IS the international one (\"Regensburg\", \"Livorno\", \"Nürnberg\", \"Lyon\"), and never an archaic exonym (\"Leghorn\", \"Ratisbon\"). The catalog stores one group per spelling and does not fold translations, so the wrong form usually resolves to a near-empty group instead of failing — see destination_resolution.catalog_hotel_count. Case, accents and hyphens ARE folded (\"Mahon\" = \"Mahón\", \"Saint Malo\" = \"Saint-Malo\"), so those need no correction. In Mode B: pair with country_code as the destination. In Mode A (with hotel_name): pair with hotel_name to narrow the fuzzy-lookup scope."
            },
            "hotel_ids": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1
                  },
                  "minItems": 1
                },
                {
                  "type": "null"
                }
              ],
              "description": "Mode A — re-shop a known set of hotel IDs (skips destination resolution)."
            },
            "longitude": {
              "anyOf": [
                {
                  "type": "number",
                  "maximum": 180,
                  "minimum": -180
                },
                {
                  "type": "null"
                }
              ],
              "description": "Longitude for geo-radius search. Pair with latitude."
            },
            "radius_km": {
              "anyOf": [
                {
                  "type": "number",
                  "maximum": 50,
                  "exclusiveMinimum": 0
                },
                {
                  "type": "null"
                }
              ],
              "description": "Geo-radius in km (default 20 for explicit coordinates, max 50). Requires latitude+longitude."
            },
            "hotel_name": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 120,
                  "minLength": 2
                },
                {
                  "type": "null"
                }
              ],
              "description": "Mode A — free-text hotel name when the user named a specific property they want to book (e.g. \"Hotel Calimala\", \"The St. Regis Rome\", \"Hôtel Costes\"). Server runs a fuzzy trigram match over the 1.74M-hotel catalog; uses the top hit when its confidence is ≥ 0.7 (auto-pick safe). If no candidate clears that threshold, returns HTTP 422 with error.code = HOTEL_NAME_LOW_CONFIDENCE + top_candidates + suggested_retry — the agent should confirm a candidate with the user or fall back to the suggested city destination. ALWAYS pair with country_code and city_name when known; lookup precision drops sharply on common names without scope."
            },
            "country_code": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 2,
                  "minLength": 2
                },
                {
                  "type": "null"
                }
              ],
              "description": "ISO 3166-1 alpha-2 country code (lowercase preferred, e.g. \"fr\"). Must be paired with city_name OR hotel_name. In Mode B it disambiguates the city; in Mode A it narrows the fuzzy lookup."
            }
          },
          "description": "Destination — provide exactly one shape; unused fields may be null or left out. Two distinct modes:\n\nMODE A (rate lookup — you know which hotel):\n  • { hotel_ids } to re-shop a known set.\n  • { hotel_name, country_code?, city_name? } when the user named a specific property. Server resolves via fuzzy lookup; returns 422 HOTEL_NAME_LOW_CONFIDENCE if no candidate scores ≥ 0.7.\n\nMODE B (hotel search — you're exploring):\n  • { query } for a natural-language destination. The platform parses it once into city + country or coordinates and never forwards the raw query to a supplier.\n  • { city_name + country_code } for ambiguous city names or when the user named a primary city (\"Mahón, ES\" for Menorca).\n  • { latitude + longitude + radius_km } when exact coordinates and an area radius are already known.\nIn Mode A, property filters (min_rating / star / min_reviews / facility / chain / hotel_type) cannot be combined with hotel_name / hotel_ids: the request is rejected — the user already named the property. filters.max_budget_per_night applies with hotel_ids or hotel_name.",
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Destination — provide exactly one shape; unused fields may be null or left out. Two distinct modes:\n\nMODE A (rate lookup — you know which hotel):\n  • { hotel_ids } to re-shop a known set.\n  • { hotel_name, country_code?, city_name? } when the user named a specific property. Server resolves via fuzzy lookup; returns 422 HOTEL_NAME_LOW_CONFIDENCE if no candidate scores ≥ 0.7.\n\nMODE B (hotel search — you're exploring):\n  • { query } for a natural-language destination. The platform parses it once into city + country or coordinates and never forwards the raw query to a supplier.\n  • { city_name + country_code } for ambiguous city names or when the user named a primary city (\"Mahón, ES\" for Menorca).\n  • { latitude + longitude + radius_km } when exact coordinates and an area radius are already known.\nIn Mode A, property filters (min_rating / star / min_reviews / facility / chain / hotel_type) cannot be combined with hotel_name / hotel_ids: the request is rejected — the user already named the property. filters.max_budget_per_night applies with hotel_ids or hotel_name."
    },
    "next_handle": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "Opaque continuation handle returned by a prior hotel_search. Send this field by itself, or with every other field null. A first request needs destination, checkin and checkout."
    },
    "occupancies": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "adults"
            ],
            "properties": {
              "adults": {
                "type": "integer",
                "maximum": 8,
                "minimum": 1,
                "description": "Adult travelers in this room (12+)."
              },
              "children_ages": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "maximum": 17,
                  "minimum": 0
                },
                "maxItems": 6,
                "description": "Ages of children in this room (0-17). Required for child pricing."
              }
            },
            "additionalProperties": false
          },
          "maxItems": 8,
          "minItems": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "One entry per room (structured). PREFERRED whenever the party is larger than 2 adults or has children — it removes ambiguity about how guests are split across rooms. Example: [{ \"adults\": 2 }, { \"adults\": 1, \"children_ages\": [5] }]. Do NOT combine with the shorthand fields (adults/children/rooms) — use one or the other."
    },
    "user_intent": {
      "type": "string",
      "description": "A concise summary of what the user is trying to accomplish, derived from their message or the\nconversation context that triggered this tool call.\nThis is used to understand the user's intent and context to improve the overall user experience.\n\n- For short, self-contained prompts (e.g. \"I want new shoes\"), copy the user message as-is.\n- For longer conversations or detailed requests, summarize the core goal and any relevant\n  context in 1-2 sentences. Focus on intent, constraints, and preferences - not the full\n  dialogue.\n\nBefore sending, strip all personally identifiable information (PII), including but not\nlimited to:\n  - Names (first, last, usernames, handles)\n  - Email addresses\n  - Phone numbers\n  - Physical addresses (street, city, zip/postal code, country when tied to an individual)\n  - Dates of birth or exact ages\n  - Government-issued ID numbers (SSN, passport, driver's license, etc.)\n  - Payment or financial information (card numbers, bank accounts, etc.)\n  - IP addresses or device identifiers\n  - Account credentials (passwords, tokens, API keys)\n  - Health or biometric data\n  - Any other information that could identify a specific individual\n\nReplace stripped values with a generic placeholder (e.g. \"[name]\", \"[email]\", \"[address]\").\n\nExamples:\n  User: \"I want red running shoes under $100\"\n  -> \"I want red running shoes under $100\"\n\n  User: \"Hi, I'm John Smith, [email protected], and I'm looking for flights from Paris to\n         Tokyo for 2 adults departing around mid-June, budget around EUR2000 total\"\n  -> \"Looking for flights from Paris to Tokyo for 2 adults, mid-June, budget ~EUR2000\"\n\n  User: \"I need help resetting my password for account ID acct_12345\"\n  -> \"I need help resetting my password for account ID [account_id]\""
    },
    "guest_nationality": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        },
        {
          "type": "null"
        }
      ],
      "description": "Guest nationality (ISO 3166-1 alpha-2, uppercase, e.g. \"FR\"). Affects rate availability + tax handling at search time. Separate from traveler nationality used for booking documents."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "trip_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "ID of an existing trip. If not provided, a new trip will be created."
    },
    "version": {
      "description": "Deprecated legacy widget field. Accepted and ignored for compatibility; it does not provide optimistic concurrency."
    },
    "add_item": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "rooms": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "trip_item_token"
                    ],
                    "properties": {
                      "traveler_ids": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Optional traveler IDs occupying this specific room."
                      },
                      "trip_item_token": {
                        "type": "string",
                        "minLength": 1,
                        "description": "Hotel rate token (htl_*) from hotel_search for THIS room. All rooms in the array must come from the same hotel and the same stay (same check-in/check-out dates) — typically one rate per requested occupancy from the same hotel_search response."
                      }
                    },
                    "additionalProperties": false
                  }
                },
                {
                  "type": "null"
                }
              ],
              "description": "MULTI-ROOM HOTEL ONLY: book 2–8 rooms of the SAME hotel and SAME stay as ONE booking with ONE reference. One entry per room, each with its own htl_* rate token from hotel_search (e.g. one rate per occupancy). All tokens must belong to the same hotel and identical check-in/check-out dates. Mutually exclusive with trip_item_token; for a single room use trip_item_token instead. Not every hotel rate can be booked this way; one that cannot is refused when it is added."
            },
            "traveler_ids": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Traveler IDs to associate with the added item"
            },
            "trip_item_token": {
              "type": [
                "string",
                "null"
              ],
              "description": "Token from flight_search fare options. Contains encoded flight/fare information. Mutually exclusive with rooms — provide exactly one of the two; the unused one may be null or left out."
            },
            "special_requests": {
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 500
              },
              "maxItems": 10,
              "description": "HOTEL ONLY. Free-text special requests for the property, one per entry — e.g. \"Expected arrival around 11:30 PM\", \"Quiet room on a high floor, if available\", \"Baby cot requested\", \"Non-smoking room\". Forwarded to the hotel supplier with the booking as REQUESTS ONLY: neither Jinko nor the hotel guarantees them, and a confirmed booking does not mean they will be honoured — tell the user so. Applies to the whole stay (every room). At most 10 entries of 500 characters each and 1500 characters in total; blank entries are dropped. Ignored on any item that is not a hotel."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Add a flight or hotel to the trip. Use trip_item_token from flight_search (offer__* format) or offer_id from hotel_search (htl_* format). For MULTIPLE ROOMS of the same hotel stay, make ONE add_item call with the rooms array (2–8 htl_* tokens, same hotel + dates) — do NOT add the same hotel as separate items."
    },
    "offer_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Deprecated: offer_id is now encoded into trip_item_token by flight_search. Only needed for legacy tokens without encoded offer_id."
    },
    "remove_item": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "item_id"
          ],
          "properties": {
            "item_id": {
              "type": "string",
              "description": "ID of the trip item to remove. Get this from trip.trip_items[].id"
            }
          },
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Remove an item from the trip by its ID."
    },
    "user_intent": {
      "type": "string",
      "description": "A concise summary of what the user is trying to accomplish, derived from their message or the\nconversation context that triggered this tool call.\nThis is used to understand the user's intent and context to improve the overall user experience.\n\n- For short, self-contained prompts (e.g. \"I want new shoes\"), copy the user message as-is.\n- For longer conversations or detailed requests, summarize the core goal and any relevant\n  context in 1-2 sentences. Focus on intent, constraints, and preferences - not the full\n  dialogue.\n\nBefore sending, strip all personally identifiable information (PII), including but not\nlimited to:\n  - Names (first, last, usernames, handles)\n  - Email addresses\n  - Phone numbers\n  - Physical addresses (street, city, zip/postal code, country when tied to an individual)\n  - Dates of birth or exact ages\n  - Government-issued ID numbers (SSN, passport, driver's license, etc.)\n  - Payment or financial information (card numbers, bank accounts, etc.)\n  - IP addresses or device identifiers\n  - Account credentials (passwords, tokens, API keys)\n  - Health or biometric data\n  - Any other information that could identify a specific individual\n\nReplace stripped values with a generic placeholder (e.g. \"[name]\", \"[email]\", \"[address]\").\n\nExamples:\n  User: \"I want red running shoes under $100\"\n  -> \"I want red running shoes under $100\"\n\n  User: \"Hi, I'm John Smith, [email protected], and I'm looking for flights from Paris to\n         Tokyo for 2 adults departing around mid-June, budget around EUR2000 total\"\n  -> \"Looking for flights from Paris to Tokyo for 2 adults, mid-June, budget ~EUR2000\"\n\n  User: \"I need help resetting my password for account ID acct_12345\"\n  -> \"I need help resetting my password for account ID [account_id]\""
    },
    "payment_type": {
      "enum": [
        "checkout",
        "intent"
      ],
      "type": "string",
      "description": "Payment flow type: \"checkout\" for Stripe Checkout (default), \"intent\" for Payment Intent."
    },
    "schedule_quote": {
      "type": "boolean",
      "description": "Schedule a fresh quote on the current cart state. Triggers async re-pricing on the BFF; poll trip(get) until trip.quote_status is \"completed\", \"partial\", or \"failed\". Only \"completed\" covers the whole cart. trip.quoted_total is the quoted sell total; trip.totals includes unquoted search prices, and trip.status is a legacy lifecycle field. Call this AFTER any traveler or cart-composition change so subsequent steps see fresh prices. book(create) will silently re-quote if the cart drifted from the last quote."
    },
    "idempotency_key": {
      "type": [
        "string",
        "null"
      ],
      "description": "Idempotency key to prevent duplicate processing"
    },
    "upsert_travelers": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "travelers"
          ],
          "properties": {
            "contact": {
              "anyOf": [
                {
                  "type": "object",
                  "required": [
                    "email",
                    "phone"
                  ],
                  "properties": {
                    "city": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Billing city. Required by some carriers."
                    },
                    "email": {
                      "type": "string",
                      "format": "email",
                      "description": "Email address for booking confirmations"
                    },
                    "phone": {
                      "type": "string",
                      "description": "Phone number in international format: a leading + and the country code, e.g. \"+12025550147\". Spaces, hyphens, dots and parentheses are tolerated and removed. A number without the leading + is rejected with INVALID_PHONE_NUMBER."
                    },
                    "title": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Title of the person paying (e.g. \"mr\", \"ms\", \"mx\"). Required by some carriers."
                    },
                    "zip_code": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Billing postal code. Required by some carriers."
                    },
                    "country_code": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Billing country as an ISO 3166-1 alpha-2 code (e.g. \"FR\")."
                    },
                    "terms_accepted": {
                      "type": "boolean",
                      "description": "Whether the traveller accepted the CARRIER's terms and conditions, which are separate from Jinko's. Send true only if they were actually shown and accepted."
                    },
                    "street_and_number": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Billing street and number. Required by some carriers."
                    }
                  },
                  "additionalProperties": false
                },
                {
                  "type": "null"
                }
              ],
              "description": "Contact for the trip lead (email + phone). Optional while building the cart, but required before booking — the connectors reject bookings without a contact phone."
            },
            "travelers": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "contact": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "email": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "email"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Email address"
                          },
                          "phone": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Phone number in international format: a leading + and the country code, e.g. \"+12025550147\". Spaces, hyphens, dots and parentheses are tolerated and removed. A number without the leading + is rejected with INVALID_PHONE_NUMBER."
                          }
                        },
                        "additionalProperties": false
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Contact information"
                  },
                  "is_lead": {
                    "type": "boolean",
                    "description": "Whether this traveler is the lead/primary contact"
                  },
                  "identity": {
                    "anyOf": [
                      {
                        "type": "object",
                        "required": [
                          "first_name",
                          "last_name",
                          "passenger_type"
                        ],
                        "properties": {
                          "title": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Title (Mr, Mrs, Ms, etc.)"
                          },
                          "gender": {
                            "anyOf": [
                              {
                                "enum": [
                                  "MALE",
                                  "FEMALE"
                                ],
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Gender. Required for flights; optional for hotel-only bookings."
                          },
                          "last_name": {
                            "type": "string",
                            "description": "Last name as on travel documents"
                          },
                          "first_name": {
                            "type": "string",
                            "description": "First name as on travel documents"
                          },
                          "middle_name": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Middle name"
                          },
                          "nationality": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Nationality (ISO 3166-1 alpha-2 country code)"
                          },
                          "date_of_birth": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Date of birth (YYYY-MM-DD). Required for flights, and for a CHILD or infant (LAP_INFANT, SEATED_INFANT) staying at a hotel; optional for an adult on a hotel-only booking."
                          },
                          "frequent_flyer": {
                            "anyOf": [
                              {
                                "type": "object",
                                "required": [
                                  "airline",
                                  "number"
                                ],
                                "properties": {
                                  "number": {
                                    "type": "string"
                                  },
                                  "airline": {
                                    "type": "string"
                                  }
                                },
                                "additionalProperties": false
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Frequent-flyer / loyalty membership. airline = IATA carrier that issued the membership (e.g. LH); number = membership number."
                          },
                          "passenger_type": {
                            "enum": [
                              "ADULT",
                              "CHILD",
                              "LAP_INFANT",
                              "SEATED_INFANT"
                            ],
                            "type": "string",
                            "description": "Passenger type based on age. SEATED_INFANT is not currently supported for flights — bookings with it are rejected; book infants as LAP_INFANT."
                          },
                          "redress_number": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "DHS redress control number (TRIP program). Flights only."
                          },
                          "known_traveler_number": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "US trusted-traveler Known Traveler Number (TSA PreCheck / Global Entry). Flights only; sent to the airline as Secure Flight data so PreCheck prints on the boarding pass."
                          },
                          "redress_issuing_country": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "ISO 3166-1 alpha-2 country that issued the redress number. Defaults to US downstream; ignored without redress_number."
                          },
                          "known_traveler_issuing_country": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "ISO 3166-1 alpha-2 country that issued the Known Traveler Number. Defaults to US downstream; ignored without known_traveler_number."
                          }
                        },
                        "additionalProperties": false
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Traveler identity information. Required if traveler_id is not provided."
                  },
                  "passport": {
                    "anyOf": [
                      {
                        "type": "object",
                        "required": [
                          "number",
                          "expiry_date",
                          "issuing_country"
                        ],
                        "properties": {
                          "type": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Document type in the CARRIER's vocabulary, when the booking requires one (carriers list it in required_customer_details as government_id_type; values are carrier-specific, e.g. \"passport_id\", \"international_passport\", \"national_id\"). Omit unless asked."
                          },
                          "number": {
                            "type": "string",
                            "description": "Passport number"
                          },
                          "expiry_date": {
                            "type": "string",
                            "description": "Passport expiration date (YYYY-MM-DD)"
                          },
                          "issuing_country": {
                            "type": "string",
                            "description": "Issuing country (ISO 3166-1 alpha-2 code)"
                          }
                        },
                        "additionalProperties": false
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Passport information for international travel"
                  },
                  "traveler_id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "ID of a pre-saved traveler. If provided, fetches traveler details from storage."
                  }
                },
                "additionalProperties": false
              },
              "description": "List of travelers for the trip. Replaces all existing travelers (idempotent). Required to complete a booking; the first traveler also supplies the booking contact name."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Set travelers on the trip. Replaces all existing travelers (idempotent operation)."
    }
  },
  "additionalProperties": false
}