Find Events

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint=false. The description adds real behavioral context beyond them: no API key required, results are sorted soonest-first, and there is no server-side city filter so the agent must post-filter on event.city_normalized. It does not cover pagination/rate limits, but the annotation bar is met.

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

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

Front-loaded with purpose and scope in the first clause, then usage routing, then operational notes. Mostly dense, though the closing instruction to interrogate the human about cities/genres is agent-behavior coaching that sits slightly outside the tool description.

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

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

With an output schema present, return-value explanation is unnecessary, and the annotations plus description cover safety, ordering, auth, and the city-filter gap. The only thing an agent might still wonder about is whether results paginate beyond the limit, which goes unmentioned.

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

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

Schema description coverage is 100%, so the schema already documents from/to, kind, genres, topics, and limit. The description only restates the filter axes in prose and adds no syntax, format, or interaction detail beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb (find), resource (upcoming events), domain examples (concerts, meetups, conferences), the ordering (soonest first), and the filter dimensions. It explicitly carves out the boundary against the sibling get_latest with product=events, so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use ('use this for anything about events'), names the alternative and the narrow condition that selects it ('get_latest with product=events only for a raw newest-first scan'). It also flags the prerequisite that no API key is needed and that city filtering must happen outside the tool.

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