Check a list of email addresses

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

Beyond the annotations (readOnlyHint=true, openWorldHint=true), the description discloses the exact semantics of each result state, including the crucial caveat that 'unconfirmed' means the mailbox itself was never verified, and that typo corrections are surfaced in did_you_mean. It also explains duplicate normalization behavior, which materially affects how an agent should interpret the returned counts.

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 scale limit and sibling relationship are front-loaded, and the three status values are enumerated compactly in a single sentence. Every sentence carries distinct information with no repetition or 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?

With no output schema, the description carries the full burden of describing the return value, and it does: a summary with counts plus one result per address in input order, the status vocabulary, and the did_you_mean field. Nothing an agent needs to call or interpret this tool 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?

Schema description coverage is 100% and there is only one parameter, so the schema already documents the input fully. The description echoes the 500-item cap (already present in the schema) but adds no format or syntax detail beyond that, so it is a baseline 3.

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 names a specific action (check email addresses in bulk) with an explicit scale limit (up to 500) and distinguishes itself from the sibling check_email by adding duplicate collapsing across Gmail dot and +tag variants. An agent can tell exactly what this tool does and how it differs from the single-address tool without opening either schema.

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 grounds usage in the sibling by stating it performs the 'same checks as check_email, plus duplicates', which implies the batch case is the reason to pick this tool. However, it never explicitly says when to prefer check_email instead, nor states prerequisites or rate limits, so the routing guidance is implied rather than spelled out.

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