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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the bar is lower, yet the description adds substantial value: cost is free, execution is pure local with no network and no APIFY_TOKEN, results are deterministic, and it discloses the normalization behavior (extracting 'Name <addr>', lowercasing the domain). That goes well beyond the structured hints.

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 WHAT/WHEN TO USE/WHEN NOT TO USE/COST/RETURNS/EXAMPLE structure is tightly front-loaded, with the purpose and routing condition in the first two blocks and no filler sentences. Every section carries distinct information.

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?

For a single-parameter, read-only, local tool the description covers purpose, exclusions, cost, determinism, normalization semantics and the return shape, even though an output schema exists. An agent has everything needed to call it correctly and interpret results.

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 the schema already documents the emails array, its 1-10000 bounds and the 'Name <addr>' form, so the baseline is 3. The description adds real semantic detail by explaining what normalization is applied to each input and the per-item reason value, which is more than the schema conveys.

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?

States a precise verb+resource (check syntactic validity of email strings) plus the scope ('entirely locally') and even names the normalization side effect. It explicitly contrasts itself with the validate_emails sibling, so an agent can distinguish them 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?

The WHEN TO USE / WHEN NOT TO USE blocks are explicit: use for fast pre-filtering or parsing before validate_emails, and do not use when domain existence, MX, disposable/role detection or typo checks are needed. It names the exact alternative and the condition that selects it.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world. The description adds significant context beyond annotations: it explains the Apify Actor dependency, the APIFY_TOKEN requirement, duplicate skipping, typical run time (3-30s), and crucially the full cost model ($0.00005/run + $0.002/row). The only gap is not detailing the exact error row semantics, though these are partially listed.

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 front-loaded with the WHAT, WHEN TO USE, and BEHAVIOR sections, making it easy to parse. However, the RETURNS section is quite verbose, listing all possible fields and their values, which duplicates information likely available in the output schema.

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 tool's complexity (external API, cost, multiple verdicts, error handling), the description provides a complete picture. It covers purpose, usage, behavior, cost, return values, and an example, leaving no major gaps for an agent to call it correctly. With an output schema present, the RETURNS detail is somewhat redundant but not harmful.

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%, so the schema already documents all seven parameters in detail. The description provides minimal additional parameter meaning beyond what the schema already specifies, particularly for the allow* flags. Baseline 3 is appropriate when the schema does the heavy lifting.

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 WHAT line states a specific verb (validate) and resource (email addresses) and enumerates the exact dimensions checked (syntax, MX, disposable, typo, role accounts, SPF/DMARC). It explicitly names the sibling check_email_syntax and distinguishes itself via the 'WHEN NOT TO USE' line.

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 explicit WHEN TO USE scenarios (cleaning lists, checking before sending, flagging signups) and an explicit WHEN NOT TO USE with the named alternative check_email_syntax. It also clarifies what it cannot do (no SMTP mailbox probing).

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