wait_for_verification

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

Annotations only declare readOnlyHint=true, so the description carries substantial extra weight and delivers: exponential backoff parameters (2s initial, 1.5x, 30s max) with jitter, the exact timeout behavior (returns status 'pending' and must be re-called), the lifecycle semantics that make cancelled/revoked final, and the auth requirement. The UX caveat about surfacing the link in reply text is genuine behavioral guidance not available anywhere else.

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?

Purpose and terminal states are front-loaded in the first sentence, with supporting semantics, the UX caveat, and the access prerequisite following in tight, distinct paragraphs. Every sentence carries unique information — no repetition of the schema or annotations.

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 still conveys the key return signal (timeout yields status 'pending'; terminal states are the success/failure outcomes) and covers auth and retry behavior. It does not describe the fuller payload a caller might receive on success, which is a minor gap for an otherwise complete definition.

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%, and the schema already documents both id and timeout_seconds in depth (default 50, max 300, MCP client timeout interaction). The description adds no parameter-level detail beyond what the schema states, so the baseline of 3 applies for a tool whose schema does the heavy lifting.

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?

Starts with a specific verb+resource ('Poll a verification') and enumerates the terminal states that end the poll (verified, failed, expired, revoked, or cancelled). The framing as a wait-until-terminal operation clearly separates it from the one-shot get_verification sibling, which it implicitly contrasts by saying the wait 'returns rather than polling on.'

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 clear usage context: it must be called only after the user can already see something actionable, and it describes the timeout/retry loop ('call it again with the same identifier'). The ACCESS note states a hard prerequisite (Proof account, PROOF_API_KEY, restart, and that start_login does NOT open this tool). It stops short of naming an explicit alternative (e.g. get_verification) for non-blocking checks.

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