find_destination

{
  "type": "object",
  "properties": {
    "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\"]."
    },
    "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\", \"LAX\", \"LON\", \"PAR\"]. When omitted or empty, the system searches globally to discover the best flight deals (destination discovery mode)."
    },
    "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."
    },
    "departure_date_ranges": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "start": {
            "type": "string",
            "description": "Range start date (YYYY-MM-DD)"
          },
          "end": {
            "type": "string",
            "description": "Range end date (YYYY-MM-DD)"
          }
        },
        "required": [
          "start",
          "end"
        ],
        "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\"}]."
    },
    "return_dates": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "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\"]."
    },
    "return_date_ranges": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "start": {
            "type": "string",
            "description": "Range start date (YYYY-MM-DD)"
          },
          "end": {
            "type": "string",
            "description": "Range end date (YYYY-MM-DD)"
          }
        },
        "required": [
          "start",
          "end"
        ],
        "additionalProperties": false
      },
      "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\"}]."
    },
    "stay_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "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."
    },
    "stay_days_range": {
      "type": "object",
      "properties": {
        "min": {
          "type": "integer",
          "minimum": 1,
          "description": "Minimum stay duration in days"
        },
        "max": {
          "type": "integer",
          "maximum": 365,
          "description": "Maximum stay duration in days"
        }
      },
      "required": [
        "min",
        "max"
      ],
      "additionalProperties": false,
      "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}."
    },
    "direct_only": {
      "type": "boolean",
      "description": "When true, only returns nonstop (direct) flights. Useful for avoiding layovers or minimizing total travel time."
    },
    "cabin_class": {
      "type": "string",
      "enum": [
        "economy",
        "premium_economy",
        "business",
        "first"
      ],
      "description": "Preferred cabin class. Options: \"economy\", \"premium_economy\", \"business\", or \"first\". Filters results accordingly."
    },
    "max_price": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Maximum total price per passenger, the currency is user default currency. Filters out results exceeding the limit. Example: 500 = limit of $500/€500/£500 per person."
    },
    "sort_by": {
      "type": "string",
      "enum": [
        "lowest",
        "recommendation"
      ],
      "description": "Sorting preference for search results. Options: \"lowest\" (cheapest first, default) or \"recommendation\" (best overall balance of price, duration, and stops)."
    },
    "trip_type": {
      "type": "string",
      "enum": [
        "oneway",
        "roundtrip"
      ],
      "description": "REQUIRED. Type of trip: \"oneway\" for single-leg flights, or \"roundtrip\" for return flights."
    },
    "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."
    },
    "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."
    },
    "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, john@example.com, 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]\""
    }
  },
  "required": [
    "origins",
    "trip_type"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}