event_list

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

With no annotations provided, the description carries the full behavioral burden, and it does well. It discloses the compact projection behavior ('view="compact"' trimmed view NOT missing fields), explains the server-side filter implementation history, and clarifies the default output shape. It doesn't mention auth requirements, rate limits, or pagination beyond the cap note, but the output-schema presence reduces that burden.

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 well-structured with the main purpose first, a history/context note, then the compact-projection detail. It's readable and front-loaded with the core purpose. The history note about fixing server-side filters is useful context but slightly verbose for the tool's operational description. Still, every sentence earns its place — the firehose-to-filtered evolution explains why this tool exists.

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?

Given 6 optional parameters with 100% schema coverage and an output schema that documents the return shape, the description covers the essential concerns: default behavior, compact vs. full projection semantics, the cap behavior, and filter scoping options. The tool is a read/list operation with no mutation concerns, so the absence of auth/permission caveats is acceptable. Very complete for its 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 baseline is 3. The description adds significant value beyond the schema: it explains the compact vs. all projection difference (important for agents deciding whether to request full payloads), clarifies the 60-row cap on compact view versus uncapped for fields='all', and the project_id 'auto' semantics for active project resolution. The limit schema description also provides the cap context, supplementing well.

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 clearly states 'List recent events in the system, optionally filtered' with a specific verb+resource. It explains all four filters are server-side and that the tool previously only exposed a global firehose. The purpose is distinct from sibling tools like task_status, team_status, and agent_activity_query, which target specific entities rather than a cross-system event stream.

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 gives clear context on when to use the tool (listing recent system events, optionally filtered by type/source/entity/project). It doesn't explicitly name alternative tools for exclusions, but the filtering options and the note about it being a firehose vs. filtered tool provide clear usage guidance. It lacks explicit when-not-to-use guidance but is otherwise strong.

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