dequeue

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

With no annotations, the description fully carries behavioral disclosure. It explains drain order (non-content first, then up to one content event), response variants, blocking vs. non-blocking, default wait source, and duplicate detection via connection_token. However, it omits discussion of rate limits, idempotency, or whether the tool has side effects beyond consuming. Still highly transparent.

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 verbose but every clause adds necessary detail for correct invocation. It is front-loaded with the core purpose. Some repetition exists (e.g., 'pending > 0 → call again' mentioned twice in different contexts), but overall it balances completeness with readability.

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 no output schema, the description thoroughly documents all return shapes (updates, pending?, timed_out, error) and their triggers. It also covers edge cases (instant polls, session_closed, default wait override) and connects to sibling tool 'action' for profile default. The only gap is lack of explicit mention of response_format output change, but 'compact' is inferred from param description. Overall complete.

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%, but the description adds valuable context beyond schema descriptions. It explains the fallback for max_wait (300s from profile default), the role of force: true, the session token requirement (implied by token param), and connection_token for duplicate detection. This enriches the schema with practical usage scenarios, elevating it above baseline.

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 opens with a specific verb and resource: 'Consume queued updates.' It then details the queue drain order and response types, clearly distinguishing from sibling tools like 'send' (which would produce updates) and 'action' (which controls profile/sessions). The purpose is unambiguous and well-differentiated.

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?

Provides explicit guidance on when to call the tool again (pending > 0, timed_out), how to use instant polls (max_wait: 0), what to do on session_closed (stop looping), and how to handle default wait and overriding. Also directs to help(topic: 'dequeue') for more details. All usage contexts are covered with clear instructions.

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