wait_for_confirmation

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals exponential backoff with jitter, terminal states, the absence of a returned link, timeout behavior, and access requirements. It even warns that a long wait can outlive an approval link while status is still pending.

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 each section earns its place: polling behavior, agent usage, terminal states, link caveat, and access requirements. It is front-loaded with the core purpose and then provides necessary operational detail, though it is slightly denser than strictly required.

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 a polling tool with no output schema and no annotations, the description is remarkably complete. It explains how to invoke it, what states to expect, what to do on timeout, how to get an approval link if needed, and what access setup is required. An agent has enough context to call and interpret the 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 the parameters are already well documented. The description adds useful usage context like 'Call this after create_confirmation with the returned confirmation ID,' but it does not meaningfully extend the parameter semantics beyond what the schema already states.

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?

The description clearly states a specific verb and resource: 'Poll a confirmation until the approver responds.' It also distinguishes this tool from related siblings like get_confirmation and get_confirmation_approval_link by framing it as a polling operation with terminal states and no returned link.

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?

It explicitly says to call this after create_confirmation with the returned confirmation ID, names get_confirmation_approval_link as the alternative when a link is needed, and notes that start_login does NOT open this tool. This is direct when/when-not/alternative guidance.

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