Verifai — Email Verification & Domain Intelligence

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

Annotations already declare a non-read-only, non-destructive, closed-world write, and the description adds the owner-only privilege requirement plus the payment precondition, which is real value. It does not disclose idempotency behavior, whether credits are additive to an existing balance, or what happens if the target key is invalid.

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?

A single sentence that front-loads the most important constraint ('OWNER ONLY') before the action and its precondition. Every clause earns its place with no 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?

For a mutation tool with no annotations describing permissions, no output schema, and 0% parameter documentation, the description covers only authorization and timing. It omits the meaning of 'plan' and 'api_key' and gives no indication of what the call returns or how a partial/failed credit addition behaves.

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 all parameter meaning, and it only implicitly maps 'credits' and 'target_key'. The 'api_key' credential and especially the 'plan' parameter (default 'paid') are never explained, leaving half the surface undocumented in both schema and description.

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 verb (add) and resource (credits) and identifies the target as a customer's key, which cleanly separates it from check_credits and the other siblings. It stops short of naming an explicit alternative, but the purpose is unambiguous.

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?

'OWNER ONLY' sets an authorization precondition and 'after payment is received' sets a timing precondition, both of which tell the agent when this tool is appropriate. No sibling alternatives or exclusions are named, so it falls short of a 5.

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 destructiveHint=false, so safety is covered by structured data. The description adds a genuine behavioral constraint the annotations do not carry: that this requires owner-level authorization. It does not mention rate limits or response shape, but with annotations present the bar is lower.

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?

A single front-loaded sentence with the access restriction first and the returned metrics after. Every clause earns its place and there is no padding.

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 compensates by enumerating the metrics returned (customers, calls, credits outstanding, paid/free split) and by stating the authorization requirement. Only the response format/layout remains unstated, which is minor for a summary-stats tool.

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?

Only one parameter (api_key) with 0% schema description coverage, but api_key is self-evident from its name and is a standard credential across the sibling tools. The description adds no parameter-level detail, so this sits at the minimum-viable baseline for a single trivial parameter.

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 resource (business/admin statistics) and enumerates exactly what it reports: total customers, calls made, credits outstanding, paid vs free split. The 'OWNER ONLY' prefix further scopes it. It is distinguishable from siblings like check_credits or add_credits, though it never names them 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?

'OWNER ONLY' is an implied usage gate — the agent knows this is only callable by an owner — but there is no explicit when-to-use framing or routing to alternatives such as check_credits for a narrower credit query. Usage is implied rather than stated.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not say what is returned, whether an invalid key errors, or any rate/scope constraints, so it merely restates the annotation title 'Check Credit Balance'.

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?

A single short sentence with the resource and target front-loaded and no filler. It is efficient, though its brevity is partly under-specification rather than genuine economy.

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 trivial one-parameter read tool with annotations covering safety, the minimum is met. However, there is no output schema and the description never indicates what a successful check returns (balance, remaining count, error state), leaving a real gap for an agent interpreting 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 description coverage is 0% and the single required api_key parameter has no schema description. The phrase 'for an API key' only loosely ties the argument to the operation and adds no format, source, or validity information to compensate for the coverage gap.

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: 'Check remaining credits for an API key.' It is distinguishable from the closest sibling add_credits (read vs. write), though it never names or contrasts with any sibling explicitly, so it falls short of the sibling-aware 5.

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 offers no when-to-use guidance, no prerequisites (e.g., key must be valid/registered), and no mention of alternatives such as register_free_key or add_credits. Usage is only inferable from the tool name.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds genuinely new operational context by disclosing the 1-credit cost and the fact that results come from external live lookups; it does not contradict the annotations.

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 sentences, zero filler: the first front-loads exactly what data the agent gets, the second front-loads the cost. Every clause carries information an agent needs for selection.

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 substitutes by enumerating return categories. However, it omits the api_key authentication path and gives no failure behavior (e.g., nonexistent domain, lookup timeout), which matters for an openWorld read against external registries.

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 compensate for both parameters and does not. The domain parameter is only inferable from context, and the api_key parameter (a default-empty auth credential) is never mentioned anywhere, leaving the authentication requirement undocumented.

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 the exact resource (a domain) and enumerates the precise data classes returned: DNS record types (A/AAAA/MX/NS/TXT), RDAP registration fields (registrar, created/expiry dates, status), and SSL certificate days remaining. No sibling tool (credit, key, or email verification) overlaps with this scope, so an agent can select it unambiguously.

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 implied by the enumerated outputs – call it when you need DNS/RDAP/SSL data for a domain – but there is no explicit when-to-use statement, no prerequisites, and no named alternative. The 'Costs 1 credit' line hints at a budget consideration but doesn't guide tool selection.

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 a non-read-only, non-destructive, closed-world write. The description adds genuinely new behavioral facts beyond them: the one-per-agent quota and that starter credits are granted, with paid top-ups handled externally. It does not say whether a key is returned in-band, whether registration is idempotent, or what happens on a second attempt.

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 compact sentences with the primary action front-loaded and the quota/alternative details trailing. Every clause carries information; nothing is padding.

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 mutation with no output schema, the description covers purpose, quota, and the paid alternative, but leaves the agent guessing about the result (is an API key string returned? does it need to be stored?) and about failure behavior when the agent already has a key.

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 of 4 applies. No parameter-level detail is missing.

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?

Names a specific verb (register) and resource (free API key) plus the qualifying benefit (starter credits), so an agent knows exactly what the call produces. Sibling differentiation is only implicit — 'free' vs. the paid 'add_credits' path — and no sibling tool is named directly.

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?

States a hard constraint ('one per agent') and indirectly routes paid needs to the operator's top-ups, which is useful selection context. However, it never says when to call this vs. add_credits/check_credits explicitly, nor whether prerequisites such as prior authentication apply.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds meaningful context beyond that: the specific verification stages and the credit cost. It does not, however, address auth (the api_key parameter) or rate/error behavior.

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, no filler. The core capability is front-loaded and the cost caveat is appended where it belongs.

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 verification tool with no output schema, the agent is told what is checked and the credit cost, which is adequate on the safety axis. But the return shape (e.g., deliverability verdict fields) and the undocumented api_key leave gaps an agent would want before calling.

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% — neither 'email' nor 'api_key' is documented in the schema. The description implicitly covers the email input ('one email address') but says nothing about the api_key parameter, its default, or when it is needed, so it fails to compensate for the coverage gap.

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 one email address') and enumerates the exact checks performed: syntax, disposable-provider check, and MX lookup. The word 'one' implicitly contrasts with the plural sibling verify_emails (bulk), letting an agent distinguish them without opening a 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?

Usage is implied by 'one email address' versus the bulk sibling, and the cost note ('Costs 1 credit') is a useful selection signal. However, no alternative tool is explicitly named and there is no statement of when NOT to use this (e.g., for batches) — the agent must infer the routing.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: the 50-address batch ceiling and, importantly, that each address consumes 1 credit — a billing trait the annotations do not convey for an otherwise read-only-labeled 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?

Two short, front-loaded sentences with zero filler. The action and its hard limit come first, followed immediately by the cost implication.

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?

There is no output schema, so the description should ideally hint at what verification results look like (e.g., per-address validity status and how they map to the input order). Cost and limits are covered, but return-shape information is entirely absent for a tool with no output schema.

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% for 2 parameters, so the description must compensate. It clarifies that 'emails' is a batch with a maximum of 50 entries, but the api_key parameter is never addressed and no format guidance (e.g., array vs delimited string) is given beyond the schema's array type.

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 with scope ('Bulk-verify up to 50 emails'), which implicitly contrasts with the singular sibling verify_email. The 'Bulk' qualifier and the 50-address cap make the tool's role easy to distinguish from verify_email, though it never names the 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 when to use it (when you have many addresses to check) via 'Bulk-verify up to 50 emails', and the cost line helps an agent judge whether to invoke it. However, it never explicitly routes the agent between this tool and verify_email, nor states prerequisites beyond the credit cost.

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