BounceBan MCP by usefulapi

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the balance and limits are shared across all API keys on the account, which affects how an agent interprets the result. It stops short of describing the return shape, but that is minor here.

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 waste, with the action and its crucial scope caveat ('without starting verification') front-loaded. Every sentence carries information the agent needs.

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 simple zero-arg read with no output schema, the description says what is returned at a high level (credit balance, rate limits) and adds the account-wide sharing trait. It could note whether the call costs credits or how limits are expressed, but nothing essential to 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. Nothing in the description misleads about inputs.

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 (read) and resource (verification credit balance and account rate limits), and explicitly scopes it away from the verification siblings with 'without starting verification'. An agent can distinguish this from bounceban_verify_email or bounceban_create_bulk_verification without reading 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?

Gives clear usage context: call it to check credits and rate limits rather than to run a verification. It doesn't name an alternative tool or state exclusions, but for a zero-parameter account-status read the condition for use is 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 establish that this is a non-destructive, idempotent, read-only operation, so the bar is lower. The description adds meaningful behavioral context beyond annotations: results are retained for 90 days, no verification is started, no following page is fetched automatically, and pending responses should be handled by checking the task later.

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 and compact. Each sentence adds operational value: pagination scope, retention, non-start behavior, state filtering guidance, and pending response handling.

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 and no parameter descriptions, so the description must do more work. It covers return cursor behavior and important operational details, but it omits the meaning of the required id parameter and does not fully explain how to use the input cursor.

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 parameter meaning. It explains state filtering semantics well, but it does not explain the required id parameter or clarify that the cursor parameter is used to fetch the next page, leaving two of three parameters 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 states a specific verb and resource: read up to 100 existing email results plus a next-page cursor. It is clear what the tool returns, but it does not explicitly contrast itself with sibling tools such as bounceban_bulk_status or bounceban_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 gives useful usage guidance: omit state to get all processed results while a task is running, filter by state with the caveat that in-progress results may be omitted, and treat a pending response by waiting and checking the existing task later. It does not explicitly route the agent to an alternative sibling tool, but the when-to-use context is strong.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds value beyond them: it discloses rate-limit sensitivity on polling and decodes status semantics ('importing/verifying' = still pending, 'finished' = task ended). It stops short of covering other terminal states (e.g., failed/cancelled) or what happens with an unknown id.

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?

Four short sentences, purpose first, then exclusion, then polling constraint, then status glossary — all front-loaded with no filler. The final sentence is dense and lower-case, and the glossary is partial, so it's tight but not maximally clean.

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 read-only polling tool with full annotation coverage and no output schema, the description covers purpose, exclusion, rate limits and status interpretation. The remaining omissions — meaning of `id`, the full set of status values, and any sense of what 'aggregate results' contains — are modest but real for an agent that has no output schema to fall back on.

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 one required parameter with 0% schema description coverage, and the description never explains it — nothing says `id` is the bulk task identifier returned by bounceban_create_bulk_verification or what form it takes. With a single trivial parameter the gap is small, but the description adds no meaning beyond the schema's own constraints.

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: 'Read progress and aggregate results of an existing bulk task.' It partially differentiates from siblings by ruling out verification ('Does not start verification'), which separates it from bounceban_create_bulk_verification, but it never contrasts with bounceban_bulk_results, whose purpose ('aggregate results') it partly overlaps.

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 gives real operating context: an exclusion ('Does not start verification') and polling guidance ('Wait between polls and honor account rate limits'). What's missing is an explicit routing statement for the closest alternative, bounceban_bulk_results, so the agent must infer which to call for full per-email output.

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 annotations (which say non-idempotent, non-destructive, open-world), it discloses that the call consumes verification credits, is asynchronous, requires an explicit confirm flag, and that duplicate submissions create new tasks – a genuine operational consequence. The credit-cost and no-polling warnings are exactly the context an agent cannot infer from structured fields.

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?

Four tight sentences, front-loaded with the batch bounds and the confirm precondition, then the credit/no-polling caveats, then the mode tradeoffs. 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 an async, credit-consuming mutation with no output schema it covers cost, confirmation, and the absence of polling, but it never says what the response contains (presumably a task identifier) or how that identifier relates to bulk_status, and one parameter is undocumented.

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. It does well for emails (batch size 1–1,000), confirm (must be true), and greylisting_bypass (explains the auto/speed/robust tradeoff), but leaves 'name' and 'disable_catchall_verify' entirely undefined, so two of five parameters remain opaque.

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 (submit), a bounded resource (1–1,000 emails), and the operating mode (regular-mode asynchronous verification), which separates it from the single-email verify sibling 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 explains the precondition (confirm:true must be set), warns to check the dashboard before resubmitting after a lost or invalid response, and notes there is no callback or automatic polling – which implicitly routes the agent to the status/results siblings. It never names an alternative tool explicitly, so it stops 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?

Beyond the readOnly, idempotent, and non-destructive annotations, the description adds important behavior: it spends no verification credits, returns success/verifying/queue states, enforces polling limits, retains results for 90 days, and never starts another verification.

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 action and cost behavior, then adds polling, retention, and no-new-verification constraints. Every sentence provides useful operational context without repetition.

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 simple single-status read tool with annotations covering safety and no output schema, the description is complete enough. It explains the returned status values, polling behavior, credit impact, retention window, and that it will not initiate a new verification.

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 single id parameter relies on the description for meaning. The description clarifies that id refers to an existing single verification, but it does not explain where to obtain the ID or address the schema's format constraints such as pattern and maxLength.

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 states a specific verb and resource: read an existing single verification ID. It distinguishes this from starting a verification by saying it never starts another verification, which helps separate it from siblings like bounceban_verify_email and bulk tools.

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 gives clear polling guidance: honor try_again_at, poll no more than 10 times within 5 minutes, then stop. It implies this is for checking an existing verification rather than creating one, but it does not explicitly name the sibling tool to use when a new verification is needed.

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?

Substantial value beyond the annotations: per-request credit cost including repeats, the confirm gate, the 15-second result window, and the two possible return shapes (final result vs. queue/verifying task ID). Annotations already declare readOnly=false and idempotent=false, but the description makes the cost/non-idempotency consequence concrete rather than abstract. It stops short of describing auth requirements or error/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?

Front-loaded with the action, then cost, precondition, return behavior, and the follow-up route — no filler sentences. The final sentence about basic-only mode returning unknown/score -1 is useful but slightly opaque without context on which mode is being invoked.

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 non-idempotent, credit-consuming action with no output schema, the description covers cost, precondition, latency window, return shapes, follow-up, and one edge-case result. The remaining gaps are disable_catchall_verify's semantics and error handling, which leave the agent slightly under-informed for a paid write operation.

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 description must compensate. It explains confirm (must be true) and, implicitly, the email param, but disable_catchall_verify is never mentioned — the closing sentence about catch-all/SEG-protected addresses gestures at that concern without naming the parameter or saying what toggling it does. Partial compensation only.

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?

Opens with a specific verb and resource ('Verify one email') and scopes it to regular mode, which cleanly separates it from create_bulk_verification and the bulk_* siblings. It also names bounceban_single_status as the follow-up reader, so the agent can place it in the workflow 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?

Gives a hard precondition ('requires confirm:true'), a follow-up route ('Read that existing ID with bounceban_single_status later'), and an explicit prohibition ('Never resubmit simply because it is still pending'). What's missing is an explicit statement of when to prefer bulk verification for many addresses.

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