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

Even though annotations carry readOnlyHint and idempotentHint, the description adds extensive behavioral context: blocking semantics per-poll with 30s default and 55s max, the cancel_then_ask_in_current_client handoff behavior, the one-second re-poll race resolution, the distinct response states (pending, cancelled, expired, missing, unavailable) with 'cancelled/unavailable mean stop, not re-ask' semantics, and a note on legacy clients for nextAction. There is no contradiction with the annotations.

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 information-dense — every sentence carries either a behavioral rule or a boundary condition that the agent needs to act correctly. It's front-loaded with the primary purpose and trigger conditions. It is not verbose for its set of distinct facts, though a sentence or two could potentially be tightened if the goal were extreme brevity.

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?

For the actual complexity of a result-style tool with an output schema, the description covers all the important execution nuances: the meaning of each response state, how to handle a live-but-unanswered question, what to do on cancellation calls, and legacy client behavior. It also covers the race-resolution via a follow-up 1s poll. The output-structure detail of the schema rounds out the documentation without leaving open questions.

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?

Parameter semantics is already handled well by the input schema: both the correlationId and the timeoutMs are fully described, including acceptable formats, defaults, and min/max limits in the schema itself. The description echoes those facts and adds the contextual connection to ask_user/send_notification flows, but does not materially exceed what the schema already conveys; the schema gives a 3, and the description's added value is positive but marginal.

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?

A very specific verb+resource: "Poll once for the user's answer to a previously created question". It names the exact trigger conditions (after ask_user times out, after ask_user with wait:false, or with a linkedCorrelationId from send_notification), which sharply differentiates it from the other siblings — especially ask_user, who creates the question rather than polls it.

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 when-to-use conditions are explicit and enumerate the exact predecessor scenarios, so the agent knows precisely when to invoke this instead of the clearly referenced alternatives ask_user and send_notification. The main gap is that it doesn't have an explicit when-not-to-use clause, though the prerequisite 'previously created question' effectively closes that gap by implication.

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