poll_events

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

Discloses the non-obvious destructive default ('Consumes returned events by default') and the exact escape hatch (peek=true to keep them), which the boolean parameter's schema entry does not convey at all. It also names the runtime prerequisite (event transport running). Note the tension with readOnlyHint=true, since draining a buffer is a state change; the description is the more accurate of the two signals.

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?

Three short sentences: purpose first, then the side-effect/escape-hatch pair, then the prerequisite. No filler and nothing buried.

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 four optional parameters and no output schema, the description covers the two facts an agent could get wrong (consumption semantics and the transport prerequisite). It stops short of describing return shape or ordering relative to since_seq, which the agent must infer from the schema.

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 only 50% (peek and limit have no schema descriptions), and the description fully compensates for the important one by explaining that peek=true preserves events instead of consuming them. limit, types and since_seq are either self-explanatory from the schema or left undocumented, but their meaning is recoverable.

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 and resource: 'Read buffered gateway/webhook events'. An agent immediately knows the operation, though the description never distinguishes it from the sibling wait_events or event_stream_status, which are the closest alternatives.

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?

'Requires event transport to be running' is a useful precondition and the peek flag is framed as a conditional choice. However, there is no guidance on when to poll versus wait_events or check event_stream_status, so the agent must infer the selection rule from sibling names alone.

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