list_events
Find upcoming events — the tool for planning an outing. Compose filters freely: a date range (from/to), free text (q, accent-insensitive: "musica" finds "Música"), category, a price ceiling (price_max), and a point plus radius (near_lat/near_lng/radius_km — e.g. the coordinates of a place from get_place, or of the user). All filters are applied to the WHOLE calendar before paging, never to a first slice. Results are chronological by next occurrence; page with offset while hasMore is true. Each event carries numeric price ({min, max, currency, isFree, known} — known: false means the source publishes no price, not that it is free), lat/lng, and purchase ({mode, tool, url, platform}) telling you HOW to attend: reserve → reserve_event_tickets; rsvp → rsvp_event; external → only a human can buy, at url; free → just go. Events within the next 7 days include a weatherForecast. On a city-wide agenda, the first page lists availableCategories. Use get_event for the full description, line-up and ticket types of one event. Omit from/to to see every upcoming event — don't guess date windows to find one event. When filters match nothing, the response carries a hint with the closest events outside them.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "list_events"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free text — every word must appear in the title, venue or description. Accent-insensitive. | |
| to | No | Last day, inclusive, YYYY-MM-DD. Defaults to `from` (a single day). Max range 62 days. Multi-day runs that overlap the range are included. | |
| from | No | First day, YYYY-MM-DD, in the site's local time zone (returned as `timeZone`). Defaults to today; past days are clamped to today. | |
| sort | No | "date" (default) = chronological by next occurrence; "distance" = nearest first (needs near_lat/near_lng). | |
| limit | No | Max events per page (default 20, max 50). | |
| filter | No | Shortcut presets: "agora" = on stage at this exact moment (season runs and day-granular sources are excluded, because their stored window says nothing about whether a session is on right now); "hoje"/"amanha"/"fim-de-semana" = running on those days, including multi-day runs; "gratis" = free to attend, including externally-ticketed events priced at 0. Date presets cannot be combined with from/to; "gratis" can. | |
| offset | No | Skip this many matches — pass the previous response's `nextOffset`. Max 500. | |
| category | No | Event category, by label or slug (case- and accent-insensitive). On a city-wide agenda an unknown category returns the valid list. | |
| near_lat | No | Latitude of the point to search around. Requires near_lng. Events without coordinates and online events are excluded. | |
| near_lng | No | Longitude of the point to search around. Requires near_lat. | |
| price_max | No | Max price of the cheapest ticket, in the event's currency. Free events always pass; events with no published price are excluded unless include_unknown_price is true. | |
| radius_km | No | Radius around near_lat/near_lng in km (default 3, max 50). Each result then carries `distanceKm`. | |
| upcoming_only | No | Only return upcoming or in-progress events (default true). | |
| include_unknown_price | No | With price_max: also return events whose price is not published (check them at `purchase.url`). Default false. |