Spectacular Atlas

Search spectacles

search_events

Read-onlyIdempotent

Find spectacles worldwide (festivals, parades, light and drone shows, eccentric traditions) by trip dates, place, type and size. Returns up to limit events, soonest first (or nearest first when near_lat/near_lng are given), each with dates, status, place, type, size, description, official website and the event's page on spectacularatlas.com.

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": "search_events"
  }
}

Input Schema

Name	Required	Description	Default
`to`	No	Trip end, YYYY-MM-DD: events that have started by this day.
`from`	No	Trip start, YYYY-MM-DD: events running on or after this day.
`sort`	No	Order of results.
`limit`	No	How many events to return (default 10).
`query`	No	Words in the name, place or description, e.g. 'Harbin', 'Kyoto', 'lantern'.
`sizes`	No	Mega: about a million visitors or more or a national flagship; Major: about 200,000 to a million; Notable: smaller.
`types`	No	Types of spectacle: light (Light festivals and light art), lantern (Lanterns), drone (Drone shows), projection (Projection mapping), immersive (Immersive venues), parade (Parades and carnivals), fireworks (Fireworks), ice (Ice and snow), balloon (Balloons and kites), sand (Sand sculpture), animals (Animal spectacles), battles (Food fights and mass battles), contests (Odd contests and races), cultural (Cultural festivals).
`region`	No	One of: East Asia, Southeast Asia, South Asia, Middle East and Central Asia, Europe, North America, Latin America and the Caribbean, Africa, Oceania.
`country`	No	ISO 3166 country code (e.g. JP) or country name.
`near_lat`	No	Latitude of a place to search around.
`near_lng`	No	Longitude of a place to search around.
`radius_km`	No	Search radius around near_lat/near_lng in km (default 250).
`year_round`	No	Venues open all year and regular shows without a season: include them (default), exclude them, or return only them.	include
`confirmed_only`	No	Only events whose dates the organizer has published.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 19, 2026

removedInput schema / properties / top_picks_only

Removed value: -{
-  "description": "Only the best-known spectacles worth a long trip.",
-  "type": "boolean"
-}

changedInput schema / properties / types / description

Previous value: -"Types of spectacle: light (Light festivals and light art), lantern (Lanterns), drone (Drone shows), projection (Projection mapping), immersive (Immersive venues), parade (Parades and carnivals), fireworks (Fireworks), ice (Ice and snow), balloon (Balloon festivals), cultural (Cultural festivals)."New value: +"Types of spectacle: light (Light festivals and light art), lantern (Lanterns), drone (Drone shows), projection (Projection mapping), immersive (Immersive venues), parade (Parades and carnivals), fireworks (Fireworks), ice (Ice and snow), balloon (Balloons and kites), sand (Sand sculpture), animals (Animal spectacles), battles (Food fights and mass battles), contests (Odd contests and races), cultural (Cultural festivals)."

changedInput schema / properties / types / items / enum

Previous value: -[
-  "light",
-  "lantern",
-  "drone",
-  "projection",
-  "immersive",
-  "parade",
-  "fireworks",
-  "ice",
-  "balloon",
-  "cultural"
-]New value: +[
+  "light",
+  "lantern",
+  "drone",
+  "projection",
+  "immersive",
+  "parade",
+  "fireworks",
+  "ice",
+  "balloon",
+  "sand",
+  "animals",
+  "battles",
+  "contests",
+  "cultural"
+]

addedInput schema / properties / year_round

Added value: +{
+  "default": "include",
+  "description": "Venues open all year and regular shows without a season: include them (default), exclude them, or return only them.",
+  "enum": [
+    "include",
+    "exclude",
+    "only"
+  ],
+  "type": "string"
+}

First observedOct 17, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare a safe, idempotent, closed-world read. The description adds real behavioral context beyond them: default/limited result count, the sort-order switch triggered by geo params, and the exact field set returned per event. It stops short of pagination or rate-limit detail, but adds meaningful value on top of a covered safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with what the tool does and the facets, then the return contract. No filler; every clause conveys selection or output information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 14 optional params, no output schema, and enum-heavy filters, the definition supplies the missing return-value explanation (dates, status, place, type, size, description, website, atlas page) and clarifies ordering. Nothing an agent needs to invoke or interpret results is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema carries the load; the description adds (not repeats) semantics by explaining the conditional sort behavior (soonest first, or nearest first when near_lat/near_lng are given) and the capped return count. It does not add format details beyond the schema, keeping it just above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (find/search) plus resource (spectacles: festivals, parades, light and drone shows) and the facets used to search (trip dates, place, type, size). An agent can tell this is the broad search tool versus get_event (single lookup) and list_filters (facet enumeration) without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the filter facets ('by trip dates, place, type and size') and the ordering note, but there is no explicit when-to-use or when-not guidance and no sibling (get_event, list_filters) is named as an alternative. An agent can infer the intended context but must connect the dots itself.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Spectacular Atlas tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?