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

With no annotations, the description carries the burden of revealing behavior. It discloses the ordering ('newest first'), pagination mechanism ('Use cursor for the next page'), and nuanced filter behavior such as q being case-insensitive substring over multiple fields. This goes beyond a minimal 'list events' statement, though it stops short of describing error handling or response structure.

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?

The description is two sentences, with the first sentence leading with the action and key resource, then listing filters, and the second sentence handling pagination. Every word serves a purpose; no filler or repeated schema information.

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?

The description competently covers filtering, ordering, and pagination, which are the primary usage concerns. Since there is no output schema, it could have described the response shape (e.g., array of events and a cursor), but the absence is not critical for a list operation. Overall, it is mostly complete for a tool of this complexity.

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 coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by clarifying the accepted date formats for both since and until (the schema only specifies format for since), and by explaining the cursor's role in pagination. These additions enhance understanding of the parameters beyond their individual schema entries.

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?

The description opens with 'List events captured by a bucket, newest first,' a specific verb and resource that clearly states what the tool does. It also distinguishes itself from siblings like get_event (single event) and list_buckets by focusing on listing events for a specific bucket with an explicit sort order.

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?

The description provides clear usage context by enumerating composable filters and instructing to use cursor for pagination. It does not explicitly name alternatives (e.g., 'use get_event for a single event'), but the context strongly implies when this list tool is appropriate, which meets the 'clear context, no exclusions' level.

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