MailValid Email Verification

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds two things they don't: the credit-release side effect and the authentication requirement. It still does not disclose error behavior for non-cancellable jobs or whether cancellation is reversible.

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?

Two short sentences with zero filler; the primary action is front-loaded and the side effect follows immediately.

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 one-parameter cancel tool with no output schema and destructive annotations already present, the description covers the action, the state scope, the credit side effect, and the auth requirement. Only the failure mode for invalid job states is left unstated.

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 0% and the single job_id parameter carries no schema description at all. The description only indirectly constrains valid values by implying the job must be pending or processing, and gives no id format or source.

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 specific verb+resource (cancel a bulk job) plus the qualifying state (pending or processing) and a concrete side effect (releases reserved credits). This clearly separates it from the read-oriented siblings like get_bulk_job and list_bulk_jobs, though it does not name any sibling explicitly.

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 phrase 'pending or processing' implicitly scopes when the tool is applicable, telling the agent this is for in-flight jobs only. However, there is no explicit when-not guidance (e.g., what happens for completed/failed jobs) and no mention of alternatives such as simply reading job status first.

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 readOnlyHint=true, and the description adds two useful behavioral facts: an API key is required, and results are only available once the job completes. That conditional-result behavior is genuinely beyond the structured data, though failure modes (invalid/expired job_id) are not covered.

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?

Two short sentences, front-loaded with the purpose and return payload, followed by the auth prerequisite. Every clause earns its place with no redundancy.

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 read-only status/results tool with no output schema, the description covers the return payload and the auth requirement. It omits polling guidance and not-found behavior, which are minor for an agent already holding a job_id.

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 0%, so the single job_id parameter carries no structured documentation. The description partially compensates by stating the job is looked up 'by its job_id', clarifying its role, but adds no format, source, or example for the identifier.

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 specific verb (get) and resource (bulk job), and enumerates what is returned: status, progress, and results when complete. It is clearly a single-job lookup, distinguishable from list_bulk_jobs, though it does not name that sibling explicitly.

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 implies you need a job_id but gives no guidance on when to use this versus list_bulk_jobs (all jobs) or cancel_bulk_job. There is no mention of polling behavior or what to do while the job is still running.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read. The description adds a genuine behavioral fact beyond the annotations — that an API key is required — but says nothing about rate limits, caching, or whether 'lifetime usage' is scoped to the account or key.

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?

Two short sentences, front-loaded with the return content and a required-prerequisite note. No filler or redundancy.

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 zero-parameter read tool with annotations covering safety, the description states both what is returned and the auth prerequisite. With no output schema, it would ideally say a bit more about the shape of the returned data, but it is close to sufficient.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly avoids inventing parameter-like options.

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 gives a specific verb and resource ('Return your current credit balance and lifetime usage'), so the tool's function is unambiguous. It does not explicitly differentiate against siblings, but the siblings (bulk jobs, email verification) are functionally unrelated, so the risk of confusion is low.

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?

Usage is only implied: an agent infers this is the tool to call when it needs balance or usage figures. There is no explicit when-to-use statement and no named alternative, though none of the sibling tools overlap in purpose, so this gap is minor.

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 readOnlyHint=true. Beyond that, the description adds real behavioral context: results are paginated, ordered newest-first, and the call requires an API key (auth requirement). It does not describe what fields come back, but with annotations covering the safety profile this is solid added value.

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?

Two tight sentences, zero waste, with the core list scope and ordering front-loaded before the optional filter and auth note.

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 read-only paginated list tool with no output schema, the description covers ordering, pagination, filtering, and auth. The remaining gap is the shape of returned job records, which an agent might want when deciding between this and get_bulk_job.

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 0%, so the description must carry the parameter burden. It mentions the optional status filter and that results are paginated (covering page/page_size conceptually), but gives no valid status values, no page-size limits, and no default behavior recovery.

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 specific verb (List) and resource (bulk verification jobs) plus scope details: recent, paginated, newest first. It implicitly separates itself from get_bulk_job and submit_bulk_verification, but never names a sibling explicitly.

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?

"Optionally filter by status" and "Requires an API key" imply usage context, but the description never states when to use this list tool versus get_bulk_job for a single job or cancel_bulk_job. No exclusions or alternatives are given.

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 only declare readOnlyHint=false and openWorldHint=true; the description goes well beyond by disclosing asynchronous execution, credit reservation with later settlement, the API-key auth requirement, and the returned payload keys. The one gap is that 'up to N credits' never ties N to the email count.

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?

Five short sentences, each adding a distinct fact: purpose, cost behavior, polling path, callback option, auth, and return shape. No filler and the core action is front-loaded.

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 usefully enumerates the return fields, and it covers the async lifecycle, credit model, auth, and follow-up tool needed to complete the workflow. Nothing essential for correct invocation 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 0%, so the description must carry the load, and it explains webhook_url's purpose (completion callback) and the credit reservation tied to the number of emails. The emails array element format is left implicit, but it is self-evident from the name.

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 specific verb (queue/submit) plus the resource and mode (a list of emails for asynchronous verification). It is immediately distinguishable from the sibling verify_email (single, synchronous) and get_bulk_job (status polling).

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?

Explicitly routes the agent to get_bulk_job for status/results and flags webhook_url as the alternative completion mechanism. It does not, however, state when to prefer verify_email over this bulk path for a small list, so the when-not guidance is incomplete.

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 only declare readOnlyHint=false and openWorldHint=true; the description adds genuinely new behavioral facts: the billing model (billable valid/invalid/catch_all/do_not_mail vs free `unknown`, cache does not change billing), the auth requirement, and the return shape. This is exactly the context an agent needs before invoking a credit-consuming tool.

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?

Three sentences, front-loaded with purpose and checks, then billing, then auth and return shape. No filler, and the parenthetical enumeration of checks is dense but readable.

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?

Low-complexity tool (one required param, no output schema) and the description covers purpose, checks performed, cost, auth, and return keys. What is missing is marginal: how errors surface and whether any rate limits apply.

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?

There is a single parameter with 0% schema description coverage, so the description carries the burden — it clarifies that the input is the email address being verified. Beyond that it adds no format or validation guidance (syntax expectations, normalization), which is the minimum viable for a one-field tool.

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 specific verb and resource ('verify a single email's deliverability') and then enumerates exactly what checks run: syntax, DNS/MX, SMTP mailbox, disposable/role/catch-all detection, and a confidence score. The word 'single' plus the enumeration makes it readily separable from the bulk and demo siblings without opening any 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?

Offers cost-based context (1 credit for billable results, free `unknown`) and the API-key prerequisite, which implicitly helps an agent weigh this against cheaper alternatives. However, it never names `verify_email_demo` or `submit_bulk_verification`, so the decision of when to use this versus those siblings is left to inference.

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