poll_webhook_events

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

With no annotations provided, the description carries the full behavioral burden. It does disclose the destructive nature ('consumes' implies payloads are removed from the queue), the auth requirement (secret_key), and the free pricing. However, it does not disclose what happens on an empty queue, whether polling is one-shot or long-polling, or the effect of the clear_on_read flag.

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?

Two tight sentences with no filler. The pricing and core action are front-loaded, and the auth prerequisite is stated in the second sentence. The '[Free / $0.0000 USDC]' prefix is minor noise but costs little. Efficient and scannable.

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?

An output schema exists, so return values need no explanation. But with no annotations, the description should cover more of the behavioral surface: it omits clear_on_read semantics, empty-queue behavior, and any relation to the sibling create_webhook_listener workflow. Adequate for a simple poll tool, but with noticeable gaps.

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 must compensate. It adds genuine provenance for secret_key ('returned when the listener was created'), which is useful. But it adds nothing for hook_id or clear_on_read, leaving those to be inferred from their names. Partial compensation at best.

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 uses a specific verb ('Polls and consumes') and a specific resource ('queued webhook payloads from an ephemeral listener'). This naturally distinguishes it from the sibling create_webhook_listener, which creates the listener rather than polling it, and from dead_letter_queue, which handles failed events. However, it does not explicitly name or contrast any sibling, so it stops short of full differentiation.

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 usage context is implied rather than stated: the mention of an 'ephemeral listener' and the requirement of 'the secret_key returned when the listener was created' signals that this tool is used after create_webhook_listener, on the same listener. But there is no explicit 'use this when...' guidance, no exclusions, and no named alternative to route around.

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