start_add_phone

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries most of the disclosure burden and does it well: nothing is sent before the user acts, which response fields exist per channel, that sms lacks deep_link, that empty dids mean unconfigured regions, and that the user never sees tool output. However, it omits session expiry, rate limits, and what happens if a session is abandoned.

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 'Agent usage:' divider cleanly separates the return-shape description from the operational routing instructions, and the closing paragraph about clients folding tool results is uniquely valuable. The second sentence is a long run-on enumerating fields, which costs a point on structure.

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 fully documents the return surface per channel, plus the auth prerequisite (PROOF_API_KEY or start_login) and the critical behavior that tool results are hidden from the user, telling the agent to relay the link or SMS text itself. Nothing needed to call this correctly is missing.

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 single `channel` parameter is fully documented in the schema at 100% coverage with an enum, so the baseline is 3. The description does add real meaning by mapping each enum value to a different response shape and rendering path, going modestly beyond the schema's terse 'Channel for phone verification'.

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?

'Start adding a new phone number by reverse OTP' gives a specific verb, resource and mechanism, immediately distinguishing it from start_add_email, delete_circle and the get_add_phone_status polling sibling. It also states the initiator of the exchange, which is the key semantic of this tool.

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 spells out the exact follow-on flow per channel: pass deep_link to render_auth_link on telegram/whatsapp, render sms_message plus a non-empty did on sms, and then poll get_add_phone_status with the session ID. It even carries an explicit exclusion ('Never hand a qr_text to a link renderer').

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