wait_for_confirmation

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

Annotations only carry readOnlyHint=true, so the description does the heavy lifting: exponential backoff parameters (2s initial, 1.5x, 30s max, jitter), the timeout→pending continuation semantics, the terminal states and what to do on approval (check proof_token), and the auth requirement to even call it. This is unusually rich behavioral context beyond the annotation.

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 core behavior and terminal states are front-loaded and waste no words. The long approval-link clause and the ACCESS paragraph earn their place but are dense and slightly over-extended for a single tool entry.

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?

There is no output schema, so the description must describe return states — and it does (pending/approved/denied plus proof_token guidance). Combined with backoff, timeout, and auth coverage, an agent has everything needed to call and interpret this tool correctly.

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 100%, so both parameters are already documented in the schema, and the description adds little new about `id` or `timeout_seconds` themselves (it restates the pending-on-timeout behavior that the schema already covers). Baseline 3 applies; the description's param-adjacent value is really about return states, not parameters.

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 confirmation until the approver responds,' immediately separating it from read-once siblings like get_confirmation and list_confirmations. The terminal-state vocabulary (approved/denied/pending) further pins down what the tool returns, so the agent knows this is a blocking wait, not a fetch.

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?

'Call this after create_confirmation with the returned confirmation ID' gives explicit sequencing, and the description names the alternative (get_confirmation_approval_link) along with the exact conditions that select it and the timeout_at precondition where it refuses. It even states the prerequisite to enable the tool (PROOF_API_KEY) and explicitly rules out start_login.

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