verify_email_otp

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds that this submission is the completing step of a multi-step add-email flow and requires an authenticated Proof account. It says nothing about behavior on an incorrect, expired, or already-used code, nor whether attempts are rate limited.

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 action is front-loaded in the first sentence, and the access prerequisites are separated into their own labeled block so they can be skipped on a re-read. Minor redundancy in "verify an email addition" / "add-email flow", but nothing that wastes the agent's attention.

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 only two required parameters, full schema descriptions, an output schema, and annotations covering the safety profile, the definition covers what an agent needs to make the call. The remaining gap is failure handling — what a rejected code looks like and whether re-submission is allowed.

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 100% and both parameters (session_id, code) carry their own descriptions, so the schema does the heavy lifting. The description ties the code to the add-email flow but adds no format, length, or expiry detail beyond what the schema states. Baseline 3 is appropriate.

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 ("Submit the OTP code to verify an email addition") and names the flow it terminates ("Completes the add-email flow"), which situates it against a large sibling set. It does not explicitly name the adjacent tools (start_add_email, resend_email_otp, get_add_email_status), but the flow framing lets an agent place it.

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 ACCESS paragraph gives concrete prerequisites — either set PROOF_API_KEY and restart, or run start_login, which "opens this tool", then retry. That is real invocation guidance rather than vague context. It stops short of stating when to prefer resend_email_otp or what to do when the code is wrong, so no alternative routing is offered.

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