NeverBounce MCP by usefulapi

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

Annotations only declare the generic write/non-destructive/non-idempotent profile, but the description adds the operationally critical facts: no credits are spent here, credits are spent in the follow-up call at 1 per billable address, concurrency limits of 10 jobs and 50 runs/day, and the account-lock risk of many small jobs. It also names the return value (job_id) and the endpoint. This is exactly the context annotations cannot carry.

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 WRITE marker and the core action, then the critical negative constraint (no verification, no credits), then the follow-up tool, then the rate-limit caution. Dense but every clause carries decision-relevant 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?

A mutation tool with no output schema, but the description still discloses the return value, the credit model, concurrency limits, and the required follow-up call. Nothing an agent needs in order to invoke this correctly is left out.

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 baseline is 3, but the description adds real guidance beyond the schema: the 100-address cap is tied to the tool's contract and the batching rule constrains how the 'emails' parameter should be populated. It does not explain 'filename' or 'leverage_historical_data', which the schema already covers adequately.

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 ('creates a bulk verification job'), bounds the input ('up to 100 e-mail addresses given in this call'), and explicitly distinguishes itself from neverbounce_start_job. An agent knows exactly what this does and what it does not do without opening the 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 explicit sequencing ('run neverbounce_start_job afterwards'), explicit exclusions ('does NOT start the verification and spends NO credits'), and a batching rule ('put ALL the addresses of one list into ONE job') with the account-lock rationale behind 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 readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered by structured data. The description adds genuinely useful behavior the annotations don't: the 200,000-character truncation with a note when longer, and the inclusion-by-default filtering semantics. That is real added context, though it says nothing about auth needs or 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?

The most important fact – the truncation limit and where to go instead – is front-loaded in the first sentence, and the trailing 'POST /jobs/download' is a compact endpoint marker. No sentence is redundant.

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 still explains the return value (CSV text of submitted columns plus email_status) and its truncation caveat. Combined with the annotations covering side effects, an agent has everything needed to call this 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?

Schema coverage is 100% and every parameter carries its own default note, so the schema does the heavy lifting. The description still adds the framing that the booleans are result-type toggles that default to inclusive, which helps an agent understand the filtering model as a whole rather than parameter-by-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?

The description states exactly what the tool returns – job results as CSV text containing the submitted columns plus email_status – and names the sibling tool (neverbounce_get_job_results) it differs from. An agent can distinguish it from neverbounce_get_job 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?

It gives the explicit escape hatch: 'use neverbounce_get_job_results to page through large jobs', and explains the filtering behavior ('set a type to false to leave it out'). The when-to-use-this vs. when-to-use-the-alternative decision is fully spelled out.

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. The description adds real value beyond them: it explains that despite being a POST to /account/info, it spends no credits — resolving the exact ambiguity an agent would have about a POST-shaped read. It doesn't disclose rate limits or auth requirements.

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?

One dense sentence enumerating returned fields, plus a short cost clarification and the endpoint. Front-loaded and waste-free, though the field list is telegraphic.

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?

No output schema exists, so the description carries the return-value burden and does list the key fields (credits left paid/free, credits used, job state counts). Adequate for a zero-parameter read; job-state labeling detail is the only minor gap.

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 the baseline is 4; there is nothing for the description to compensate for.

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 (retrieve account info: credits left/used and job counts by status). Clearly distinct from the job/email siblings, though it never names them.

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 — checking remaining credits before running verification jobs is the obvious use, but the description never says when to call it or what alternative exists.

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 cover the safety profile (readOnly, non-destructive, openWorld), so the description's job is to add context — and it does: it discloses the full status vocabulary including the non-obvious 'under_review' and 'failed' states, defines 'billable' as credits consumed, and names the underlying endpoint (POST /jobs/status). It omits rate limits or polling cadence, which keeps it from a 5.

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 key actions — what is returned and to poll until complete — are front-loaded in a compact two-sentence block. The long parenthetical list of status values and counters is dense but each item is genuinely informative, so little is wasted.

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 carries the burden of describing return values and does so thoroughly enough for an agent to interpret a response. Nothing critical is missing for a single-parameter read, though guidance on what to do after 'complete' (e.g. fetching results) is absent.

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 itself explains that job_id comes from neverbounce_list_jobs or neverbounce_create_job. The description adds no format, range, or sourcing detail beyond that, so the baseline 3 applies.

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 resource (a single verification job) and enumerates exactly what is returned: status, failure reason, timestamps, totals, bounce estimate and percent complete. That implicitly separates it from neverbounce_get_job_results and neverbounce_download_job_results, though the siblings are never named, so an agent must infer the boundary itself.

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?

"Poll this until status is complete" gives an explicit operational instruction and the terminating condition, which is exactly the guidance an agent needs for a status endpoint. It does not state what to do before a job exists or when to prefer get_job_results instead, so no exclusions are offered.

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 the safety profile is covered; the description adds real value by disclosing that results are paged and that the job must be complete first — a failure mode the agent would otherwise hit blind. It stops short of describing pagination termination or error behavior, so not a 5.

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 compact sentences with zero filler; the return contents come first, the sibling alternative and precondition follow. Every clause carries information an 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?

With no output schema, the description does the work of sketching the return shape (data, result, flags, suggested_correction, address info) and names the completion precondition. The one soft spot is "address info," which is left unexpanded, but nothing essential to invoking 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 description coverage is 100% and the page parameter's description already explains passing the previous reply's next_page, so the schema carries the parameter burden. The description only adds the word "Paged" and adds no format or constraint detail beyond the schema — the baseline 3 applies.

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 and, unusually, enumerates what each result row contains (submitted data plus verification fields). It also explicitly distinguishes itself from neverbounce_download_job_results, so an agent can separate the two sibling tools without inspecting 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?

Gives an explicit alternative and the condition that selects it ("use neverbounce_download_job_results for a CSV") plus a hard precondition ("The job must be complete"). That covers when-to-use, when-to-use-something-else, and the prerequisite in one line.

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 bar is low. The description adds useful context beyond that: default ordering (most recent first as NeverBounce returns them), the field set returned, and the underlying POST /jobs/search endpoint. It does not mention rate limits or pagination behavior explicitly, keeping it from a 5.

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?

Effectively two sentences with the resource and ordering front-loaded, followed by the filterable fields. The long parenthetical list of result totals is slightly dense but each item is informative rather than 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?

There is no output schema, so the description's enumeration of returned fields (id, status, filename, timestamps, totals, bounce estimate, percent complete) is genuinely necessary and present. Pagination params are covered by the schema; only per-call behavioral details like rate limits are absent.

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 all five parameters are documented at the schema level. The description echoes the filterable fields (id, exact filename, status) but adds no new syntax or semantics, and does not mention page or items_per_page. 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 description clearly identifies the resource (bulk verification jobs of the account) and the scope (list/search with filters), and enumerates returned fields. It stops short of naming a sibling for contrast, though the 'list of jobs' framing is distinguishable from neverbounce_get_job by implication only.

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 states 'Filter by id, exact filename or status,' which tells the agent how to narrow results but not when to choose this over neverbounce_get_job or neverbounce_get_job_results. Usage is implied (browse jobs) rather than explicitly bounded.

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 destructiveHint=true, readOnlyHint=false and idempotentHint=false, and the description goes well beyond them: exact cost model (1 credit per billable address, cross-referenced to total.billable in neverbounce_get_job), irreversibility ('cannot be stopped or undone'), a required safety parameter, and a 1000-credit ceiling for this 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?

Front-loaded with 'WRITE' and the cost warning, then the safety rule, then the precondition, then the free-sample caveat, then the endpoint. Every clause carries decision-relevant information 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?

With no output schema, the description still tells the agent what financial effect the call has and where to check the billable count beforehand. For a destructive, credit-spending operation with 3 parameters, nothing material 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 the baseline is 3; the description still adds value by tying max_credits to a concrete enforcement rule and by pointing to neverbounce_get_job's total.billable as the figure it is compared against, and by clarifying that run_sample spends nothing. It doesn't add new syntax or edge cases for job_id.

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 ('STARTS a created job'), its billing consequence, and the underlying endpoint. It is clearly distinguished from neverbounce_create_job, which makes the job but does not run it.

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 explicit preconditions ('must be in status waiting or waiting_analyzed'), an explicit exclusion with an alternative ('start bigger jobs in the NeverBounce dashboard'), and a free escape hatch ('run_sample true ... spends nothing'). Nothing about when to call it 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?

Adds substantial context beyond the annotations: per-call credit cost, the account-lockout risk of looping, and the underlying endpoint (POST /single/check). The credit spend is consistent with destructiveHint=true and readOnlyHint=false; nothing contradicts the annotation profile.

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?

Opens with the cost/effect warning, then purpose, then usage rules, then endpoint — front-loaded and dense. Every sentence (credit cost, loop prohibition, alternative tool) carries decision-relevant 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?

There is no output schema, but the description enumerates the response shape (result enum values, flags, suggested correction, optional parsed parts), so an agent knows what comes back. Cost, misuse risk, and the escape hatch for bulk work are all present.

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 baseline is 3; the description goes slightly beyond by explaining that address_info yields parsed address parts and contextualizing the outcome values. It does not add format guidance for timeout beyond the schema's 1-60 range, so it is a modest lift rather than a full one.

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 ("Verifies ONE e-mail address") and enumerates the return surface (result values, flags, suggested correction, parsed parts). It also names the sibling it is not for (neverbounce_create_job for lists), so an agent can distinguish it from other neverbounce_* tools 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?

Gives explicit when-to-use ("single address at the point of entry"), explicit when-not ("do NOT call it in a loop over a list or database"), the consequence (account lock), and the named alternative (neverbounce_create_job). This is the strongest form of routing guidance.

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