event_list

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

Annotations only supply readOnlyHint=true; the description goes well beyond it by disclosing default sort order (newest first), the order inversion when after_index is used, the truncated/scanTruncated signalling semantics, and that SSO session ids in login events are redacted. These are non-obvious behaviors an agent must know to poll safely.

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 the one-line purpose, then behavior, then parameters; every sentence carries information. The Args block restates parameter names, but at 0% schema coverage that repetition is load-bearing rather than filler.

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 no output schema, the description still names the return signals an agent needs (index, order, truncated, scanTruncated) and gives the correct polling algorithm. Nothing required to call this tool correctly is missing.

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 0%, so the description carries the full burden and does so: limit range 1-1000 with default 100, the four legal min_severity values, since_minutes bounds 1-129600, target's meaning and default, and the interaction constraint on page.

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 opening line states a specific verb (list), resource (engine events), and scope (at or above a severity, newest first). No sibling tool covers events, so there is no ambiguity to resolve against the other 16 tools.

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?

It explains exactly when to use each mode: after_index for following new events (with the repeat-while-truncated loop), since_minutes for a rolling window, and page for older history. It also states a hard exclusion — page is not combinable with since_minutes or after_index — and that omitting target uses the default.

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