start_change_number

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true) by disclosing that the account stays on the old number until finish_change_number succeeds, that rate limits surface as errors, that linked devices will fail with a specific message, and the exact return payload.

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?

Information-dense and front-loaded with the purpose, then constraints, then next step. It is a long single block with semicolon-chained parameter notes, which slightly hurts scannability, but nearly every clause carries load-bearing detail.

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 supplies the return shape ({status: 'verification code sent', number}) and the full two-step workflow, device prerequisites, and error conditions. An agent has everything needed to invoke and sequence this tool.

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 already 100%, but the description adds real meaning on top: the captcha token is only needed after a captcha-required error, plus the URL to mint one and the signalcaptcha:// token format — operational detail absent from the schema.

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?

Opens with a precise verb+resource: 'Step 1 of moving this Signal account to a new phone number: asks Signal to send a verification code to the new number.' It explicitly positions itself as the first half of a two-step flow, making it distinguishable from the sibling finish_change_number.

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?

States when to call it, names the follow-up call ('Then call finish_change_number with the same number and the received code'), and gives explicit exclusions: primary device only, fails on linked signal-cli setups. The captcha branch is conditioned on a specific prior error.

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