List events

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and a closed-world profile, so safety needs no restating. The description adds the semantic link to webhook payloads and the backfill use case, but says nothing about ordering of results, how far back events are retained (critical for a 'catch up after downtime' tool), or rate limits. That retention gap is a real behavioral omission.

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 opening 'List events.' is a bare restatement of the name and title, consuming a line without adding information before the substantive sentence arrives. The remaining text is tight and front-loads the webhook-equivalence claim, but the redundant lead-in costs it a point.

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 six optional parameters, a nested date filter, an enum, and no output schema, the description should say more about what a result looks like and how to page through a large backlog. It covers the two main filters and the purpose but leaves ordering, retention, and the cursor-based traversal strategy unaddressed.

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 enum values, limit bounds, created[] operators, and cursor directions are all already documented. The description adds a little interpretation — that filtering by resource_id shows 'everything that happened to one object' — but gives no syntax hint for the type enum or the cursor workflow. Baseline 3 is appropriate.

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 gives a specific verb and resource and adds a useful identity claim: these are 'the same objects delivered to your webhooks,' which separates event records from the delivery records handled by list_event_deliveries. It does not, however, explicitly distinguish itself from get_event or list_event_deliveries by name, so an agent must infer the boundary from the sibling names alone.

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?

One concrete use case is offered — 'Use it to catch up after downtime' — which tells the agent this is a polling/backfill tool rather than a real-time mechanism. There is no guidance on when to prefer get_event for a single event, when list_event_deliveries is the right call, or what happens past the retention window, so alternatives are left implicit.

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