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

The description goes far beyond the annotations by explaining the durable cursor read, at-least-once delivery, the confirming read for timed_out, and the best-effort in-process wake-up. It also discloses rejection codes, auth requirements, and the read-only nature, all of which align with readOnlyHint=true and idempotentHint=true.

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 long but well-structured with clear sections (overview, delivery guarantee, loop, requirements, rejection codes). Every sentence provides essential operational context for a complex long-poll tool, so it earns its place. It is slightly dense but appropriately sized for the behavior it documents.

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 the complexity (long-poll, delivery guarantees, session ownership, plan requirements), the description is exceptionally complete. It covers the purpose, usage loop, prerequisites, error codes, auth, and timeout semantics. An output schema exists, so return-value details are not the description's responsibility.

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% with detailed parameter descriptions, so the baseline is 3. The tool description adds further value by integrating after_event_id and timeout_s into the usage loop, explaining the cursor semantics, and directing the agent to the schema for full details. This incremental context justifies a score 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: 'BLOCK until the session owner posts the next `steer` event to a Governed Session from the AIDB Studio cockpit, then return it.' It clearly distinguishes itself from sibling tools by highlighting its read-only, long-poll nature and explicitly stating it never writes events, unlike me.session_event.

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 provides an explicit 'THE LOOP' workflow that tells the agent exactly when to call this tool and how to sequence it with me.session_event. It also covers exclusions (e.g., owner-scoped, foreign session ids read as not found) and gives handling instructions for timed_out responses, including an alternative action (call again with the returned after_event_id).

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