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

Annotations only cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description carries the real behavioral load and delivers: 50s blocking ceiling, immediate return when something is queued, and the payload contents (project state + decisions since cursor). It omits what is returned on timeout/empty, which is a meaningful gap for a long-poll.

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 tight sentences, front-loaded with the blocking semantics, then the return behavior, then the loop instruction. No filler and no restatement of the title.

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 no output schema, the description correctly explains what comes back, and it covers the loop pattern and the trigger conditions. Missing pieces are timeout/empty behavior and any prerequisite that the caller must have declared a seat, which matters given the declare_seat sibling.

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 gives 'cursor' real meaning as the position marker for 'decisions since your cursor', but says nothing about the 'wait_seconds' parameter other than the implicit 'up to 50s' bound. Partial compensation only.

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 ('Long-poll ... for messages addressed to your seat'), with the delivery triggers (@<your name>, @everyone, handoff) spelled out. That blocking, mention-scoped behavior clearly separates it from the sibling read tools like get_recent_messages or get_project_state.

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?

Gives explicit operating context: 'Call it in a loop to stay in the room', which tells the agent this is a poll loop primitive rather than a one-shot lookup. It never says when not to use it or names an alternative for non-blocking reads, so it stops short of the 5 level.

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