Mailvett: Email Validation API for AI Agents

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

The description goes beyond the annotations by disclosing that it does not verify mailbox existence (a key behavioral limitation) and specifying the output structure (verdict, score, reason codes). The title also clarifies no SMTP probing. This adds meaningful context on top of readOnlyHint and idempotentHint, though it does not mention potential network latency or rate limits.

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 informative but slightly long; each sentence contributes meaning (checks, output, limitation) and the structure is front-loaded with the action. It avoids redundancy and is organized logically, though it could be trimmed by merging some of the enumerated checks into a more compact list.

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 there is no output schema, the description adequately explains the return format (verdict, score, reason codes) and the limitation of not verifying mailbox existence. It covers the key aspects an agent needs to call the tool correctly and interpret results. Missing details like error handling or timeouts are minor given the simplicity and the annotations.

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 input schema already provides 100% coverage for the 'emails' parameter, including accepted formats ('Name <email>' or mailto: links) and the 10-item limit. The description adds no new parameter details beyond reiterating 'up to 10', so it does not enhance the schema's semantic value.

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 clearly states a specific verb ('Check') and resource ('email addresses'), enumerating the exact checks performed (syntax, MX, provider, etc.) and the output format. This fully distinguishes the tool's purpose and is unambiguous, even without siblings.

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 provides clear context on when to use the tool (validating email deliverability) and explicitly states a limitation ('Does not verify that the mailbox itself exists'), which informs when not to use it. However, it does not name alternatives since there are no sibling tools, and it could be more explicit about use cases, but the limitation serves as guidance.

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