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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals the interactive nature ('the system sends a message and the user replies'), lists the return payload (session ID, deep_link, qr_code, qr_text), and states the access requirement. This goes well beyond the schema and informs the agent that the tool initiates a user-interactive process, though it does not mention potential timeouts, error conditions, or that the session needs polling via a status tool.

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 organized into two focused paragraphs: the first explains the operation and output, the second covers access prerequisites. It is appropriately sized for the tool's interactive complexity and front-loads the core purpose. The access instructions are slightly verbose but necessary for correct invocation, and every sentence adds value.

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?

The description covers the immediate call purpose, return values, and authentication prerequisite. However, it does not mention what to do after obtaining the session ID and QR code (e.g., share with user, wait for reply, then check status via get_add_phone_status). Given the tool is part of a multi-step OTP flow and no output schema exists, this omission leaves an agent without clear next-step guidance, making the description not fully complete.

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?

The schema already covers the single parameter fully with an enum and description ('Channel for phone verification'). The tool description adds no additional detail about the channel values or their implications, but given 100% schema coverage, the baseline of 3 applies. The description does implicitly tie the channel to the OTP message, but this is 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?

The description states a specific verb and resource: 'Start adding a new phone number.' It further clarifies the mechanism (reverse OTP) and return values, which distinguishes it from sibling tools like start_add_email or set_primary_phone. An agent can clearly identify the tool's purpose without needing to open 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?

The description explicitly provides a prerequisite ('needs a Proof account') and a usage path: authenticate the client or sign in with start_login, then call this tool again. This gives concrete guidance on when to use the tool and references the relevant sibling for authentication. It does not, however, mention when not to use it (e.g., if a phone is already added) or point to get_add_phone_status for follow-up, leaving a small gap.

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