ClearBounce Email Verification

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new context: the call is free, the status values are enumerated, and progress plus completion-only summary counts are described. The only thing it leaves implicit is whether repeated polling is rate-limited or has eventual-consistency delay.

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?

Front-loaded with the core action and cost, then the return shape, then the routing advice — a logical order with little waste. The enumerated status list is slightly verbose given an output schema exists, but it is cheap and clarifies the returned shape.

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?

Covers the full lifecycle an agent needs: the job is created by verify_bulk, this polls it, statuses and progress are returned, summary counts appear only on completion, and drill-down requires get_bulk_results. With an output schema present, it need not describe return structure further.

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?

One parameter at 100% schema coverage, so the schema already explains jobId; the description merely restates that it comes from verify_bulk. Baseline 3 applies since the description adds no format, constraint, or lifecycle detail beyond the schema.

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 progress of a bulk verification job) and ties it to the originating tool, verify_bulk. The status/progress/summary breakdown makes it immediately distinguishable from siblings like get_bulk_results and check_credits.

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 says when to use this versus the alternative: report summary counts here, but call get_bulk_results when per-address results are needed. It also notes the dashboard download path as an out-of-band option, so the agent has a complete routing picture.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond them: the balance is scoped to the API key's owning account, and the call is free (consumes no credits) — an important behavioral fact not encoded in any structured field.

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 no waste. The action and scope come first, and the cost note ('Free') trails as a quick value-add.

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-argument read with an output schema and rich annotations, the description supplies everything an agent needs: what it returns, whose balance it is, and that it costs nothing. Return-value shape is already handled by the 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?

Zero parameters, so there is nothing for the description to disambiguate; baseline of 4 applies. The description sensibly explains that the account is derived from the API key rather than passed as an argument.

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 ('Return the remaining verification credit balance') plus the account scoping (the account that owns the API key). Among siblings that all perform email verification actions, this is the only balance-read tool, so the distinction 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?

The zero-parameter read and the word 'remaining' imply you check this before or after consuming credits in verify_email/verify_bulk, but the description never states when to call it or explicitly points at those siblings. Usage is inferable rather than instructed.

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?

Beyond the readOnly and idempotent annotations, the description discloses that candidates are unverified pattern-based guesses, that finding is free while verification costs credits, and that the tool should not verify without user approval. This is substantial behavioral context that the agent would otherwise lack.

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 core purpose, then efficiently covers return behavior, cost implications, and the required verification workflow. Every sentence delivers essential operational information without 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 tool with two fully documented parameters and an output schema, the description covers purpose, result nature, cost, consent, and the exact follow-up action with verify_email. No critical operational detail is missing for an agent to call it correctly.

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 fully describes both parameters with examples, so the description's mention of full name and company domain adds limited new meaning. It reinforces the source fields but does not introduce additional parameter-level semantics beyond what the schema provides.

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 opens with a specific verb and resource: find a person's business email from full name and company domain. It clearly differentiates the tool from verify_email by describing find as generating pattern-based candidates rather than confirming deliverability.

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 workflow guidance: show candidates, inform the user about credit costs, ask before verifying, then call verify_email one at a time by confidence until a deliverable result is found. This makes the tool's role relative to verify_email and the approval process unambiguous.

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, and non-destructive, so the safety profile is covered; the description adds genuinely new context: the call is free (no credits) and results are capped at 500 per call. It doesn't describe what happens if the job is still running, which is the one behavioral gap.

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 what is returned, followed by routing guidance and pagination options. No filler and each sentence 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 read-only results tool with a full output schema and 100% parameter documentation, this is complete: it covers the precondition (completed job), cost, routing versus siblings, and paging behavior. Nothing needed to invoke it correctly 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 coverage is 100%, so baseline is 3, and the description adds usage context beyond the schema: status filtering is optional and offset is the paging mechanism for large jobs. The 'up to 500 results per call' detail slightly repeats the limit field's max, but the paging/filter framing adds real meaning.

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?

A specific verb and resource: retrieves per-address results of a completed verify_bulk job, and names the returned fields (status, sub-status, score). It is clearly separable from verify_bulk (which runs the job) and verify_email (which re-checks a single address).

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 states when to use it ('user needs to know which addresses passed or failed') and when not to ('do not re-verify them with verify_email'), plus the precondition that the job must be completed, which implies check_bulk_status. Nothing 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.

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

Beyond annotations, the description discloses that the job runs asynchronously in the background, takes roughly 1-10 minutes, costs 1 credit per unique address, deduplicates for free, and returns a jobId rather than immediate results. It also reveals a meaningful side effect (credit consumption) and the need for user confirmation, which annotations alone do not convey.

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 compact but information-dense. Purpose, accuracy benefit, cost model, async behavior, and follow-up action each appear in tight prose, and the most critical facts are 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?

For a tool with one parameter and an output schema, the description covers everything needed to call it correctly: constraints, cost, async return, follow-up status polling, and user-confirmation guidance. It also distinguishes the tool from the sibling verify_email tool without needing further context.

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 schema already documents the emails parameter and its 2-to-10,000 item range at 100% coverage, so the baseline is 3. The description adds valuable semantics beyond the schema: duplicates are removed for free and cost is calculated per unique address, so an agent understands the real meaning of the list contents.

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 opens with a specific verb and resource: 'Verify a list of email addresses (2 to 10,000) as one bulk job.' It also differentiates from single-address verification by highlighting the bulk pipeline's per-domain caching and greylist retries, so an agent can see why this tool exists apart from verify_email.

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 explicitly explains when to choose bulk verification over one-by-one verification and names the follow-up tool, check_bulk_status, with the jobId. It also gives a clear behavioral instruction to confirm with the user before spending many credits, which is a strong usage guideline.

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/idempotentHint/non-destructive, and the description adds genuinely non-obvious behavior: it performs a live remote mailbox check (openWorldHint context) and consumes 1 credit per call. That cost disclosure is the kind of thing an agent cannot derive from annotations, though it doesn't cover rate limits or failure 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?

Three tight sentences, front-loaded with the core action, then output shape, then cost. The enumeration of return fields partially duplicates the existing output schema, which is the only 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 one-parameter tool with a full output schema and clear annotations, the description covers action, mechanism, and cost. The missing piece is explicit sibling routing, which keeps it from a 5.

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?

Single required 'email' parameter with 100% schema description coverage including an example, so the schema fully carries parameter meaning. The description adds no syntax or normalization rules, which is acceptable at this baseline.

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?

Specific verb+resource ('Verify a single email address') with the mechanism named ('real time with a live mailbox check'). The word 'single' explicitly separates it from the sibling verify_bulk, so an agent can route correctly without opening schemas.

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 by the word 'single' — there is no explicit statement telling the agent to use this rather than verify_bulk for batches or get_bulk_results/check_bulk_status for existing jobs. The alternative relationship is inferable but never spelled out.

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