Search Local Events
search_eventsFind events matching a user's natural-language request. Combines semantic search over venue vibes, geographic radius filtering, date/cost/category hard filters, and strict safety tags. Returns ranked event facts, original event-source links when available, and the filters that shaped the results. Call this ONCE per user query with the structured args you inferred from their question — do not try to issue multiple speculative calls.
The tool cannot buy tickets, create or modify events, edit calendars, or message organizers. Calls record private quota and request telemetry.
Tag vocabulary is fixed (49 canonical tags across 6 facets: ambiance, social, time, age, venue_type, activity). See the vibe_tags field description.
Safety-critical tags (queer-friendly, family-friendly, all-ages, 18-plus, 21-plus) are hard filters: if included, venues without that tag are excluded entirely — never just down-ranked. Only include a safety tag when the user's query explicitly requested it.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Ordering axis. Results are always grouped chronologically by calendar day (in `timezone`); `sort` orders WITHIN each day. 'date' (default) = by start time; 'distance' = nearest first; 'demand' = most popular first; 'relevance' = semantic score first (best with query_text). | |
| limit | No | Number of events to return. Default 20. Prefer small (5-10) when the user asked for a single recommendation. | |
| date_end | No | ISO-8601 end of the search window. Default: 14 days from date_start. 'Tonight' → date_start + 6 hours. 'Next weekend' → date_start + 2 days. | |
| max_cost | No | Upper bound on event cost in USD. 'cheap' ≈ 15, 'affordable' ≈ 30, 'under $X' → X. Leave unset if the user didn't constrain price. | |
| min_cost | No | Lower bound on event cost. Rarely useful — only set when the user explicitly excluded free events. | |
| timezone | No | 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 | No | 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 venues. | |
| categories | No | 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 | No | Latitude (only if you already have precise coordinates — otherwise pass place_name). | |
| center_lng | No | Longitude (paired with center_lat). | |
| date_start | No | ISO-8601 start of the search window. Default: now. For 'tonight' pass now. For 'this weekend' pass the upcoming Saturday midnight. NOTE: the window matches by OVERLAP — an event that STARTED before date_start but is still running during the window (multi-day festival, a show that ends after midnight) is included. Filter client-side on `start` if you strictly need events that begin inside the window. | |
| local_only | No | 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 | No | Human-readable location if the user mentioned one: 'Westminster, CO' or 'Five Points Denver'. Prefer this over lat/lng when you have a name. Always include the state abbrev when the city name is ambiguous. | |
| query_text | No | 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 | No | 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 | No | 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: - 'walking distance' / 'on my block' → 2-3 - 'near me' in a dense downtown or neighborhood → 5-7 - 'near me' in a suburb → 10-15 - 'metro area' / 'anywhere in <city>' → 25-30 - rural 'near me' or 'within driving distance' → 25-50 For 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. Max 500. Use 'local_only: true' instead of a small radius when you're unsure of local density. | |
| max_events_per_venue | No | 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. |