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

Annotations only give a blunt safety profile (not readOnly, not idempotent, not destructive); the description goes well beyond them by disclosing the two-state machine (pending vs approved), the retry_after backoff contract, the once-only token issuance, and the anonymous/no-auth precondition. This is exactly the behavioral context an agent needs to drive a device flow correctly.

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 dense sentences, front-loaded with the purpose, the pending-state contract, and the terminal-state contract in order of use. No filler; the embedded JSON example earns its space by pinning the response shape.

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?

Strong overall coverage for a stateful polling tool, and it even describes the pending and success payloads despite an output schema existing. It omits failure terminals (challenge denied or expired), which matter in a device-login flow, leaving a small completeness gap.

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 only 50% — challenge_id and authorization carry no descriptions — but the prose compensates by specifying that the same challenge_id must be reused across polls and that authorization takes the 'Bearer <token>' form. It adds real meaning over the bare schema, though it never explains where challenge_id originates.

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 ('poll a device login to token issuance') plus scope markers (UC-091, RFC 8628), making it immediately distinguishable from the sibling start_device_login. An agent knows exactly what this endpoint accomplishes without opening the schema.

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?

Explicitly describes the polling loop: while pending, wait retry_after seconds and re-call with the same challenge_id, and on approval pass access_token to every other tool. It lacks an explicit statement that start_device_login must precede it or what to do on denial/expiry, but the operative usage conditions are unusually clear.

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