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

The description clearly discloses that a successful verification consumes the OTP so it cannot be reused, and that expired codes fail. It also enumerates the exact failure reasons ('invalid' | 'expired' | 'not found'), adding meaningful behavioral detail beyond the readOnlyHint=false annotation.

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?

Every sentence adds necessary information: what it does, success/failure behavior, consumption side effect, required identifier selection, and when to call. It is compact but complete, well-structured, and free of filler.

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?

Given the output schema and the strong input schema, the description covers the essential operational context: the verification flow, required identifier, expiring/consumption behavior, and expected return statuses. An agent has enough information to call this tool correctly without ambiguity.

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 already provides 100% coverage with detailed descriptions for each parameter. The description adds crucial usage semantics not fully captured by the schema: you must pass either phone_number or message_id, and message_id is preferred because it disambiguates multiple OTPs for the same number.

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?

Description states a specific verb ('Verify'), the exact resource ('the OTP MyOTP delivered'), and the intended context (end-user code submission). The stated outcomes—success or failure with reasons—clearly differentiate it from a plain status check like check_otp_status.

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 when to call: 'Call this after collecting the code from the user (login form, signup screen, etc.)'. It also clarifies the required identifying parameter, prefers message_id over phone_number, and explains why. It does not name alternative tools or explicitly say when not to use them, but the context is clear.

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