Input schema (JSON)
{
"type": "object",
"properties": {
"sort": {
"enum": [
"date",
"distance",
"demand",
"relevance"
],
"type": "string",
"description": "Ordering axis. Results are presented by calendar day in timezone; sort orders within each day. With query_text, the server selects the strongest event-text and venue-vibe matches under every sort, and sort only orders them. Without query_text, the result limit is shared across the days of the window: events starting inside it come before events already under way, and each day contributes its next event on the sort axis."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 100,
"minimum": 1,
"description": "Number of events to return. Default 20. Prefer small (5-10) when the user asked for a single recommendation."
},
"date_end": {
"type": "string",
"format": "date-time",
"description": "Exclusive ISO-8601 end of the search window, including the local UTC offset. Default: 14 days from date_start. The words now, today, tonight, tomorrow and this weekend are also accepted and resolved in the caller's timezone. 'Tonight' → date_start + 6 hours. 'Next weekend' → date_start + 2 days. An event starting exactly at date_end is outside this window."
},
"max_cost": {
"type": "number",
"minimum": 0,
"description": "Upper bound on event cost in USD. 'cheap' ≈ 15, 'affordable' ≈ 30, 'under $X' → X. Events with no listed price stay in the results (most events list none), so present their price as unverified rather than excluding them. max_cost=0 returns only proven-free events. Leave unset if the user didn't constrain price."
},
"min_cost": {
"type": "number",
"minimum": 0,
"description": "Lower bound on event cost. Rarely useful — only set when the user explicitly excluded free events."
},
"timezone": {
"type": "string",
"default": "UTC",
"description": "IANA timezone (e.g. 'America/New_York') used for the calendar-day grouping of results. Default UTC — pass the user's local zone so 'today/tomorrow' day buckets match their clock."
},
"vibe_tags": {
"type": "array",
"items": {
"enum": [
"chill",
"casual",
"lively",
"rowdy",
"intimate",
"loud",
"upscale",
"scene-y",
"romantic",
"date-spot",
"group-friendly",
"solo-friendly",
"family-friendly",
"queer-friendly",
"late-night",
"happy-hour",
"brunch-spot",
"daytime",
"all-ages",
"18-plus",
"21-plus",
"dive-bar",
"cocktail-bar",
"wine-bar",
"brewery",
"winery",
"distillery",
"coffeehouse",
"listening-room",
"dance-club",
"lounge",
"sports-bar",
"theater",
"concert-hall",
"amphitheater",
"arena",
"arts-center",
"art-gallery",
"rooftop",
"outdoor",
"restaurant-venue",
"church-venue",
"warehouse",
"historic",
"open-mic",
"karaoke",
"trivia",
"comedy-focused",
"drag-shows"
],
"type": "string"
},
"maxItems": 12,
"description": "Canonical vibe vocabulary. Include tags the user explicitly or strongly implied. IMPORTANT: the tags `queer-friendly`, `family-friendly`, `all-ages`, `18-plus`, `21-plus` are HARD filters — only include them when the user's query explicitly asked for that property. Including `family-friendly` for a user who just said 'something fun tonight' will exclude most events."
},
"categories": {
"type": "array",
"items": {
"enum": [
"music",
"karaoke",
"sports",
"comedy",
"theater",
"trivia-games",
"food-drink",
"arts-culture",
"community",
"festivals"
],
"type": "string"
},
"maxItems": 10,
"description": "Event category(s). Map the user's intent: 'live music' → music, 'standup' → comedy, 'trivia night' → trivia-games, 'art opening' → arts-culture. 'anything to do' → omit (no category filter)."
},
"center_lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude (only if you already have precise coordinates — otherwise pass place_name)."
},
"center_lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude (paired with center_lat)."
},
"date_match": {
"enum": [
"overlap",
"starts_within"
],
"type": "string",
"default": "overlap",
"description": "overlap includes events already running during the window, such as multi-day festivals or prior-night shows; events ending exactly at date_start are excluded. starts_within requires the event to start at or after date_start and before date_end. Prefer starts_within for requests about events starting tomorrow, on a specified date, this evening, or this weekend. Keep overlap when the user asks what is currently happening or wants ongoing activities."
},
"date_start": {
"type": "string",
"format": "date-time",
"description": "Inclusive ISO-8601 start of the search window, including the local UTC offset. Default: now. The words now, today, tonight, tomorrow and this weekend are also accepted and resolved in the caller's timezone. For 'tonight' pass now. For 'this weekend' pass the upcoming Saturday midnight. The timezone field controls day grouping, not parsing: date-times without an offset are interpreted as UTC. Use date_match=starts_within when the user wants events starting on a particular date or evening."
},
"local_only": {
"type": "boolean",
"default": false,
"description": "Set true when the user's query implies 'in my immediate area' — 'what's on my block', 'nearby tonight', 'close by'. The server clamps the effective radius to a neighborhood-scale max based on local density (≤10mi urban, ≤30mi suburban, ≤50mi rural), even if radius_miles is larger. Prefer this over guessing a small radius — the server knows the density of the area and you don't."
},
"place_name": {
"type": "string",
"description": "Human-readable location if the user mentioned one: 'Westminster, CO' or 'Five Points Denver'. Prefer this over guessed lat/lng when you have a name; existing precise coordinates take precedence. Always include the state abbrev when the city name is ambiguous. An unresolved place returns location_unresolved; correct the place or use known coordinates rather than dropping the location."
},
"query_text": {
"type": "string",
"maxLength": 500,
"description": "Free-text vibe description extracted from the user's query. Keep it short — e.g. 'chill jazz' or 'loud rock club'. Omit when the user's request is purely geographic / tag-based (e.g. 'any comedy shows tonight near me')."
},
"state_hint": {
"type": "string",
"description": "Two-letter state abbreviation to disambiguate place_name (e.g. place_name 'Frederick' + state_hint 'MD'). Unnecessary when place_name already contains the state."
},
"radius_miles": {
"type": "number",
"maximum": 500,
"minimum": 0.5,
"description": "Search radius in miles. OMIT this field to let the server pick a density-aware default: 5mi in dense metros (Chicago, NYC), 15mi suburban, 25mi rural. Only pass an explicit value when the user's phrasing implies a specific scope:\n - 'walking distance' / 'on my block' → 2-3\n - 'near me' in a dense downtown or neighborhood → 5-7\n - 'near me' in a suburb → 10-15\n - 'metro area' / 'anywhere in <city>' → 25-30\n - rural 'near me' or 'within driving distance' → 25-50\n\nFor a user who says 'things to do tonight' in Lincolnwood, Chicago, or any other dense-urban location: omit this field. Passing 15 there pulls events from 8-10 miles away in other neighborhoods, which is worse than the density-aware default.\n\nRange 0.5 to 500. An out-of-range value FAILS the entire call and returns zero events — it is not clamped — so omit the field rather than guessing. Use 'local_only: true' instead of a small radius when you're unsure of local density."
},
"max_events_per_venue": {
"type": "integer",
"default": 1,
"maximum": 20,
"minimum": 1,
"description": "Per-venue diversity cap. Default 1 — each venue contributes at most one event, giving a diverse 'what's on' feed. Raise to 3-5 for 'what's on at <specific venue>' queries where the user expects multiple shows from the same room."
},
"include_unknown_prices": {
"type": "boolean",
"default": true,
"description": "Include events whose admission price cannot be determined. Default true preserves broad discovery; positive price bounds may then include unknown prices, which must be labeled unverified. false keeps only events with a listed price; most events list none, so it can empty an answer, and 'under $X' alone is not a reason to set it. When it leaves three or fewer results, applied_filters.available_if_relaxed reports how many the same search returns with unknown prices included. This never relaxes the proven-free requirement of max_cost=0."
}
},
"additionalProperties": false
}