Verify email addresses before you send: honest verdicts, no address kept, EU-hosted.
Scored across 20 tools
Most tools target a clearly distinct resource+action (verify_email vs submit_batch, create/get/update/delete_webhook, list_jobs vs list_batches). A few are close cousins—get_batch (status/progress) vs get_batch_results (per-email rows), and get_verification vs get_batch_results—but the descriptions draw the boundaries explicitly, so misselection is unlikely.
Every tool follows a clean snake_case verb_noun pattern (check_balance, create_api_key, get_batch, list_jobs, revoke_api_key, submit_batch, verify_email). No mixed conventions or vague standalone verbs, so the surface is fully predictable.
20 tools is on the heavier side, but they span four genuinely distinct resource families (verification, batches, API keys, webhooks/billing), so each earns its place. Slightly over what a minimal surface needs, but not bloated.
Strong lifecycle coverage: webhooks have full CRUD, batches support submit/append/poll/list/results, keys cover create/list/revoke, and billing spans balance/usage/transactions/pricing. Minor gaps exist (no batch cancel/delete, no API key update), but nothing that would block core workflows.
Append a chunk of emails (up to 4096) to a batch created by submit_batch with final: false, so a bulk job can grow past the single-call cap. Reserves and queues this chunk exactly like submit_batch, and accepts the same optional checks field; a streamed caller should pass the same checks on every chunk so the whole batch runs one check set. Pass the same api_key used on the original submit_batch call to keep billing and scoping on that account; omit it to use the caller's own session account. Requires the email:verify:bulk scope on whichever account ends up authenticating the call. Set final_chunk true on the last chunk to close intake; the batch then completes once every job (old and new) finishes.
| Name | Required | Description | Default |
|---|---|---|---|
| final | No | Whether this is the batch's final chunk (defaults to true). Set false to keep intake open for a further append_batch_emails call. | |
| checks | No | Optional check wire strings (syntax, mx, smtp, disposable, role, free, catchall); defaults to every check the caller's plan allows, smtp included. A streamed caller should pass the same checks on every chunk so the whole batch runs one check set. | |
| emails | Yes | Email addresses to verify in this chunk (up to 4096). May be empty to close intake without adding more emails. A final chunk is refused when the batch would close with fewer than batch_min (20) distinct valid addresses; the batch then stays open. | |
| api_key | No | Optional pm_live_ (or pm_test_) API key, matching the one used on the original submit_batch call. When present, this chunk is billed and scoped against that key's own account instead of the caller's session account, and the key must carry the email:verify:bulk scope. Omit to use the caller's own session account. | |
| batch_uuid | Yes | Public batch UUID of an open batch (created by submit_batch with final: false). | |
| custom_ids | No | Optional per-email client references, index-aligned 1:1 with emails. Echoed back verbatim in get_batch_results so you can map each result to your input row. Do not put the email address or any PII here, use your own row identifier (e.g. a CRM id). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses rich behavior: it reserves and queues the chunk exactly like submit_batch, keeps billing and scoping on the api_key account, requires the email:verify:bulk scope, and explains that the batch completes only after all old and new jobs finish. It also discloses that an api_key omitted means the caller's session account is used.
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 purpose and then packs auth, billing, checks, and lifecycle into one dense paragraph. It is appropriately sized for a complex batch operation, though the long single paragraph and some repetition slightly reduce readability.
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 six-parameter bulk mutation tool with no output schema and no annotations, the description covers the critical operational context: scope, billing, checks consistency, chunk size, and finalization behavior. The main gap is the final_chunk versus final naming error, plus no explicit note about custom_ids or response shape.
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 would be 3, and the description does add useful meaning for checks, api_key, and intake closing. However, it says 'Set final_chunk true on the last chunk' even though the actual parameter is named 'final', which can mislead an agent into passing a nonexistent 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 a specific verb and resource: appending a chunk of emails (up to 4096) to an existing batch. It explicitly distinguishes this from submit_batch by tying it to batches created with final: false and bulk jobs exceeding the single-call cap.
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 usage conditions: use this to grow a bulk job past the single-call cap, pass the same checks on every chunk, pass the same api_key as the original submit_batch, and set the final chunk to close intake. The alternative path (submit_batch) is named and the selection condition is explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the caller's current token wallet balance, average daily spend, active plan code, and the checks that plan allows (e.g. whether catchall or smtp are available).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. The verb "Read" correctly signals a non-mutating operation and the enumerated return fields add real context, but nothing is said about auth requirements, rate limits, or whether the caller must be authenticated to a specific account.
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 that names the resource and then lists the four returned values with an inline example. No filler and 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?
There is no output schema, so the description must convey return values itself, and it does so by naming balance, average daily spend, plan code, and plan-allowed checks. For a zero-parameter read tool with no annotations, that covers the essentials; only auth/rate-limit context 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 per-parameter semantics to convey; the baseline for a parameterless tool is 4. The description instead uses its space to enumerate return values, which is the useful information here.
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) plus the resource (caller's token wallet) and enumerates the returned fields: balance, average daily spend, plan code, and plan-allowed checks. It is clear what the tool does, but it never distinguishes itself from siblings such as get_usage, get_pricing, or list_transactions, which an agent could plausibly confuse it with.
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?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives. An agent must infer that this is the tool for balance/plan questions, and it gets no help deciding between this and get_usage or get_pricing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new PricklyMails API key under the caller's account and return its raw value once (field raw_key). Pass that value as the api_key argument to verify_email or get_verification to bill verifications against it. environment picks live (default, real billing and real SMTP) or test (a deterministic sandbox: no SMTP, no wallet debit). scopes and enabled_checks default to the project defaults when omitted. Requires the api_keys:create scope on the caller's session.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Display name for the new key, shown in the PricklyMails dashboard. | |
| scopes | No | Optional scope wire strings (e.g. email:verify:single, results:read); when absent the project default scopes are applied. | |
| environment | No | Optional environment, live or test (defaults to live). A test key (pm_test_*) runs a deterministic sandbox: the worker never dials SMTP or resolves DNS, and nothing is reserved or billed from the wallet, so it is safe for integration testing. | |
| enabled_checks | No | Optional check wire strings (syntax, mx, smtp, disposable, role, free, catchall); when absent the default check set is applied. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it warns the raw key is returned only once, describes the live-vs-test environment semantics (real billing/SMTP vs deterministic sandbox with no wallet debit), states that scopes/enabled_checks fall back to project defaults, and names the required session scope (api_keys:create). These are exactly the consequences an agent needs before invoking a credential-creating 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-loads the action and the one-time raw_key return, then layers environment, defaults, and scope requirement in tight declarative sentences. No filler or redundancy; every clause adds 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?
No output schema exists, but the description compensates by naming the return field (raw_key) and its one-time nature. It covers permissions, defaults, and environment semantics. The only gap is that it doesn't describe error/failure behavior or whether the key can be re-read later, though 'once' implies it cannot.
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%, so the schema already documents all four parameters including defaults and the test-key sandbox behavior. The description largely restates those defaults rather than adding new syntax, formats, or constraints, so the baseline 3 is appropriate.
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 ('Create a new PricklyMails API key under the caller's account') and immediately identifies the distinctive return artifact ('return its raw value once (field raw_key)'). This clearly separates it from siblings like list_api_keys and revoke_api_key, which are named in the sibling list.
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 concrete downstream usage: pass the raw value as api_key to verify_email or get_verification to bill verifications against it, and notes environment selection (live default vs test sandbox). It does not explicitly state when NOT to create a key (e.g., when one already exists / use list_api_keys first), so it falls short of the 5-level exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a webhook endpoint that receives job-completion notifications. Returns the signing secret once (field secret); it is never shown again. Uses the caller's own session bearer. Requires the webhooks:create scope on the caller's session.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Target URL that receives event notifications. | |
| events | Yes | Event type strings to subscribe to (e.g. job.completed, job.failed). | |
| description | No | Optional human-readable description of the endpoint. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses that the signing secret is returned only once and never shown again, that the caller's own session bearer is used, and that the webhooks:create scope is required. It does not cover failure modes or limits, keeping it short of 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 short sentences, front-loaded with the action and followed by the two pieces of information an agent most needs (one-time secret, auth requirement). 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?
No output schema exists, yet the description explains the one non-obvious return element (the one-time secret field) and the authentication/scope prerequisites. For a three-parameter creation tool this is complete enough to call 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 description coverage is 100%, so url, events, and description are already documented in the schema; the description adds no syntax or format detail beyond it. The 'secret' mention is about the return value, not a parameter, 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?
States a specific verb and resource ('Create a webhook endpoint') plus its function ('receives job-completion notifications'). This clearly separates it from delete_webhook, get_webhook, list_webhooks, and update_webhook without needing their 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?
The described function implies when to use it (registering a new notification endpoint), but there is no explicit when-to-use guidance, no exclusions, and no routing to sibling tools such as update_webhook for modifying an existing endpoint. Adequate but leaves selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a webhook endpoint by uuid. Idempotent on repeat calls. Uses the caller's own session bearer. Requires the webhooks:delete scope on the caller's session.
| Name | Required | Description | Default |
|---|---|---|---|
| webhook_uuid | Yes | Public UUID of the webhook endpoint, as returned by create_webhook or list_webhooks. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden, and it does so well: idempotency on repeated calls, that the caller's own session bearer is used, and that the webhooks:delete scope is required. It stops short of stating whether a missing uuid errors or succeeds silently and what (if anything) is returned.
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, front-loaded with the action, then idempotency, auth, and scope. No filler, no repetition of the schema, and every sentence adds operational value.
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 delete with no output schema and no annotations, the description supplies the key missing context: auth mechanism, required scope, and idempotency. Minor gaps remain around error behavior for unknown UUIDs and whether a confirmation payload is returned.
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 single parameter is fully documented in the schema, including where the UUID comes from. The description adds only the phrase 'by uuid', so baseline 3 applies – 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?
States a specific verb ('Delete') and resource ('webhook endpoint') plus the identifier used ('by uuid'), which cleanly separates it from create_webhook, update_webhook, get_webhook, and list_webhooks among the siblings. An agent can select it 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?
The operation type makes basic usage inferable (you delete an existing webhook you no longer want), but there is no explicit when-to-use guidance, no mention of alternatives such as update_webhook for disabling versus deleting, and no stated precondition like 'the webhook must exist'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a batch's status, progress, and aggregated results by batch_uuid. Uses the caller's own session bearer. Requires the results:read scope on the caller's session.
| Name | Required | Description | Default |
|---|---|---|---|
| batch_uuid | Yes | Public batch UUID returned by submit_batch or list_batches. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose the auth model and required scope, which is real added value, but it omits pagination behavior, what status values or progress semantics look like, and what happens for a pending, failed, or nonexistent batch.
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 short sentences, front-loaded with the resource and return fields, then the auth requirements. No filler and nothing buried.
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 tool with no output schema, the description usefully previews the returned fields and covers authentication and scope. It is nearly complete; the missing piece is how to interpret status/progress and how it differs from the batch-results sibling.
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 single parameter is documented in the schema as the public UUID from submit_batch or list_batches. The description only restates the identifier in prose, adding no syntax or format detail beyond the schema, so 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 names a specific verb and resource and enumerates what is returned (status, progress, and aggregated results). It is clear on its own, but it does not distinguish itself from the close siblings get_batch_results and list_batches, which is exactly where an agent would hesitate.
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 the preconditions (caller's own session bearer, results:read scope), which is useful routing context, but gives no explicit guidance on when to call this versus get_batch_results or list_batches. Usage is only implied by the return-field list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the per-email results for a batch (uuid, custom_id, status, score, verdict per row; custom_id echoes back whatever was supplied at submit for that email, if any), paginated (API default limit 20, cap 96). Uses the caller's own session bearer. Requires the results:read scope on the caller's session.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results to return (API default 20, cap 96). | |
| offset | No | Number of results to skip (default 0). | |
| batch_uuid | Yes | Public batch UUID returned by submit_batch or list_batches. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: it discloses pagination behavior (API default limit 20, cap 96), the authentication model (caller's own session bearer), and the required authorization scope (results:read). It omits ordering guarantees and error/pagination-termination behavior, keeping it short of 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?
A single front-loaded sentence that leads with the action and resource, then adds auth and pagination detail without preamble. The parenthetical listing of output fields makes it slightly dense but nothing 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?
No output schema exists, so the description usefully describes the returned row fields and covers auth, scope, and pagination limits. It leaves ordering and end-of-results/total-count behavior unspecified, a minor gap for a paginated read 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?
Schema description coverage is 100%, so limit/offset/batch_uuid are already documented; the description's restatement of the 20/96 pagination figures and the custom_id echo semantics largely duplicate schema text or describe output fields rather than parameters. 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 ('Fetch the per-email results for a batch') and even enumerates the row shape (uuid, custom_id, status, score, verdict), which cleanly separates it from the sibling get_batch that returns batch-level metadata.
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 description's framing (fetch results after a batch exists) and it names submit_batch/list_batches as the source of the batch_uuid, but it never states when to prefer this over get_batch or list_batches, nor any exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the public plan grid, top-up pricing, and per-check token costs. No API key needed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the two traits that matter here: the operation is a read and it requires no authentication. It stops short of return shape or caching/rate-limit behavior, but for a public static pricing read that is a modest 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?
Two short sentences, zero filler, with the resource list and the auth note both front-loaded. Every clause earns its place.
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, non-mutating public endpoint with no output schema, listing the three returned data groups plus the auth condition is nearly complete. Only the absence of any hint about response structure 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?
The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter semantics are missing or misdescribed.
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 ('Read') plus three concrete resources (plan grid, top-up pricing, per-check token costs), which distinguishes it from sibling pricing/usage tools like get_usage and check_balance. An agent knows exactly what this returns without opening anything else.
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?
'No API key needed' implies it is safe to call before authentication, which is a useful usage cue. However, it never contrasts this with siblings such as get_usage or check_balance (account-specific spend), so the agent must infer which pricing source to consult.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the caller's verification usage overview over the default window: verdict breakdown, per-check usage, totals, and only the non-zero days of the activity series.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full behavioral burden. It does disclose a meaningful trait beyond the schema: the activity series returns 'only the non-zero days'. However it says nothing about auth requirements, scoping to the caller's own account, rate limits, or whether the data is live vs cached.
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 verb first and the returned sections listed compactly. Every clause carries information; 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 must convey return content, and it does name the four sections (verdict breakdown, per-check usage, totals, non-zero activity days). What is missing is the default window's actual length and any sense of the data's freshness or auth scope.
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. The description correctly implies the window is fixed by the server rather than configurable, but adds no per-parameter detail because there is none to add.
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 a specific resource (the caller's verification usage overview), then enumerates the sections returned. It is clearly distinct from siblings like get_verification, check_balance, or list_transactions, though it never names those alternatives 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 'over the default window' implies the tool takes no windowing input, which is mild implicit guidance, but there is no statement of when to reach for this versus get_verification or check_balance, and no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a verification job and its results by job UUID. Pass the same api_key that owns the job, or omit it to fetch with your own session (needs the results:read scope), which reaches the same job when it was itself submitted by that session.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | Public job UUID returned by verify_email. | |
| api_key | No | Optional. A pm_live_/pm_test_ key that owns the job; this call is read-only and bills no tokens, the key only selects whose job to fetch. Omit to fetch with your own session instead (needs the results:read scope). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose an auth requirement ('needs the results:read scope') and confirms the call is a read, but says nothing about rate limits, whether results may still be pending/in-progress, or pagination 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 primary action in the first clause, and no padding sentences. The trailing clause 'which reaches the same job when it was itself submitted by that session' is slightly convoluted but does convey the equivalence of the two credential paths.
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 annotations, so the description is the only source of behavioral context. It covers purpose and credential handling but leaves the shape of 'results' (status, terminal vs. pending states) unstated for a tool whose output is the whole point.
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 both parameters are already fully documented in the schema (including the read-only/no-token-billing note). The description restates the api_key dual-mode behavior but adds little beyond what the schema text already provides, so 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+resource+key: 'Fetch a verification job and its results by job UUID.' This clearly separates it from siblings like list_jobs (enumeration), verify_email (submission), and get_batch_results (batch-scoped).
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?
Explains the two credential modes for reaching the job (pass the owning api_key vs. omit and use session scope) and names the required scope. However it doesn't contrast with sibling tools such as list_jobs or verify_email, so the when-to-use-this-vs-alternatives dimension is only partly covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single webhook endpoint by uuid. Uses the caller's own session bearer. Requires the webhooks:read scope on the caller's session.
| Name | Required | Description | Default |
|---|---|---|---|
| webhook_uuid | Yes | Public UUID of the webhook endpoint, as returned by create_webhook or list_webhooks. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden and does disclose two real behavioral facts: the caller's own session bearer is used, and the webhooks:read scope is required. 'Fetch' implies a safe read. It stops short of error behavior (missing uuid, not-found, cross-tenant access), which keeps it below 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 short sentences, front-loaded with the action, then the auth mechanics. Every sentence earns its place and there is no filler or restated field documentation.
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 tool with 100% schema coverage and no output schema, the definition covers the essentials plus auth. The remaining gap is failure behavior for an unknown or unauthorized uuid, which an agent would benefit from knowing.
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 schema itself explains that webhook_uuid is the public UUID as returned by create_webhook or list_webhooks. The description's 'by uuid' adds no syntax or format 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?
States a specific verb and resource ('Fetch a single webhook endpoint by uuid'), and the word 'single' plus the uuid requirement cleanly separates it from list_webhooks and the create/update/delete siblings. No ambiguity about what gets returned at a resource level.
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: fetch one existing webhook when you have its uuid. However, no alternative is named (e.g. 'use list_webhooks to enumerate'), and no condition for picking this over list_webhooks is stated, so 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.
List the caller's PricklyMails API keys (uuid, name, active flag, scopes, enabled checks). Requires the api_keys:read scope on the caller's session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It does disclose a key operational requirement: 'Requires the api_keys:read scope on the caller's session,' which is essential auth context. It also lists the returned fields, partially covering output despite no output schema. It doesn't mention pagination or rate limits.
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, no waste. The purpose is front-loaded, the scope requirement follows. Every clause earns its place.
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 no output schema, the description is nearly complete: it names the resource, lists the returned fields, and states the required auth scope. The only omission is return ordering/pagination, which is minor.
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 has zero parameters, so the baseline is 4. The description correctly communicates that no input is required, and the field enumeration refers to output, not input, so there is no parameter ambiguity.
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 clear verb+resource: 'List the caller's PricklyMails API keys.' It even enumerates the returned fields. It does not explicitly contrast with the sibling revoke_api_key or create_api_key, but the verb 'List' is distinct enough that confusion is unlikely.
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?
No explicit guidance on when to use this tool versus alternatives. It doesn't say to use revoke_api_key to invalidate a key or create_api_key to mint one. The tool is simple enough that usage is somewhat implied, but no when/when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the caller's bulk-verification batches, newest first, paginated (API default limit 20, cap 96). Uses the caller's own session bearer. Requires the results:read scope on the caller's session.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of batches to return (API default 20, cap 96). | |
| offset | No | Number of batches to skip (default 0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses ordering (newest first), pagination defaults and cap, that it uses the caller's session bearer, and the required results:read scope. It stops short of describing failure behavior for missing scope or empty results.
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, front-loaded with what the tool returns and how results are ordered. The auth/scope sentence is short and earns its place by adding information not present in the schema.
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 with no output schema, the description covers ordering, pagination, identity scope, and required permission — enough to invoke correctly. Minor gaps remain around error/empty-result behavior, but nothing critical 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%, so limit and offset are already documented in the schema. The description merely restates the limit default/cap rather than adding syntax or interaction meaning, 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?
States a specific verb and resource (list bulk-verification batches), plus ordering (newest first) and pagination behavior. It is clearly distinguishable from sibling single-item readers like get_batch and get_batch_results.
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: it scopes the tool to the caller's own batches and names the required results:read scope, which hints at when it is callable. It never names an alternative (e.g., get_batch for a single batch) or states when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the caller's standalone verification jobs (jobs belonging to a batch are excluded; use get_batch_results for those), newest first, paginated (API default limit 20, cap 96). Uses the caller's own session bearer. Requires the results:read scope on the caller's session.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of jobs to return (API default 20, cap 96). | |
| offset | No | Number of jobs to skip (default 0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses ordering ('newest first'), pagination defaults and cap, the auth model ('caller's own session bearer'), and the required scope. It stops short of describing the response shape or error/empty behavior, but the behavioral profile is otherwise clear.
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 tightly-packed sentence with parentheticals, front-loading the resource and scope before pagination and auth details. No filler sentences and every clause carries 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 list tool with no output schema and no annotations, the description covers the essentials an agent needs: scope exclusions, ordering, pagination limits, auth, and required permission. Only the returned item structure is left unstated, which is a 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?
Schema description coverage is 100%, so both limit and offset are already documented, including the 20/96 values the description repeats. The description adds no semantics beyond the schema, making the baseline 3 correct.
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 ('List the caller's standalone verification jobs') and immediately scopes it by excluding batch jobs, naming the sibling that handles those ('use get_batch_results for those'). An agent can distinguish this from list_batches and get_batch_results 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?
Explicitly states the exclusion condition ('jobs belonging to a batch are excluded') and routes to the correct alternative ('use get_batch_results for those'). It also gives the precondition for use (results:read scope on the caller's session), leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the caller's token wallet ledger transactions, newest first, paginated (API default limit 20, cap 96). Uses the caller's own session bearer. Requires the billing:read scope on the caller's session.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of transactions to return (API default 20, cap 96). | |
| offset | No | Number of transactions to skip (default 0). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden, and it does disclose auth requirements ('caller's own session bearer'), a required scope, ordering, and pagination defaults/caps. It does not state what an empty ledger returns or the shape of a transaction record, which is a real remaining 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?
Two dense sentences that front-load the resource and scope, with no filler. The '(API default limit 20, cap 96)' parenthetical duplicates the schema, a small but real 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 list tool it covers the essentials: scope of data, ordering, pagination, auth, and required permission. The lack of any output schema means the returned transaction fields are undocumented anywhere, which is the one notable omission.
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 both parameters (limit, offset) already document their defaults and the cap. The description restates the limit default/cap but adds no new meaning, and never mentions offset, so baseline 3 is correct.
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: list the caller's token wallet ledger transactions, plus ordering ('newest first'). This separates it in practice from balance/usage siblings like check_balance and get_usage, but no sibling is named explicitly, so it falls short of the top band.
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 resource name and the auth requirement ('Requires the billing:read scope'), but there is no explicit when-to-use statement, no exclusions, and no routing to an alternative tool for adjacent needs such as current balance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every webhook endpoint owned by the caller. Uses the caller's own session bearer. Requires the webhooks:read scope on the caller's session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, but it does add real value: it discloses that the caller's own session bearer is used and that the webhooks:read scope is required. It stops short of covering pagination/result limits or whether disabled endpoints are included.
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 short, front-loaded sentences with no filler. Purpose comes first, then auth mechanics and the required scope — every sentence earns its place.
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-parameter list tool with no output schema, the description covers purpose and the auth/scope prerequisites an agent needs to invoke it. Only pagination or result-volume behavior is unaddressed, which is a minor gap for this tool class.
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 are no parameters whose meaning the description would need to disambiguate, and it adds no redundant parameter discussion.
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 ('List every webhook endpoint') with a clear scope ('owned by the caller'). The plural/'every' phrasing implicitly separates it from the singular get_webhook sibling, but it never names that sibling explicitly, so differentiation is left to inference.
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?
There is no guidance on when to use this over get_webhook or how it relates to the other webhook tools (create_webhook, update_webhook, delete_webhook). The stated scope requirement is a prerequisite, not usage routing; an agent must infer that 'list all' is the intent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revoke one of the caller's PricklyMails API keys by uuid. Idempotent on repeat calls. Requires the api_keys:revoke scope on the caller's session.
| Name | Required | Description | Default |
|---|---|---|---|
| key_uuid | Yes | Public UUID of the key to revoke, as returned by create_api_key or list_api_keys. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose two non-obvious traits: repeat calls are idempotent, and a specific session scope is required. It omits the destructive/irreversible nature of revocation and what happens to requests using the key, so it is strong but not complete.
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 short sentences, action and target front-loaded, with the idempotency and auth facts appended. No filler or 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 single-parameter mutation with full schema coverage and no output schema, the description supplies the operation, identifier, idempotency and authorization requirement. It stops short of describing the effect of revocation (immediate permanent invalidation, impact on in-flight traffic), which is the only meaningful remaining 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?
Schema description coverage is 100% and the key_uuid property already explains it is the public UUID returned by create_api_key or list_api_keys. The description's 'by uuid' adds no format or sourcing detail beyond the schema, so 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 (revoke), a specific resource (one of the caller's PricklyMails API keys) and the identifier used (uuid). No sibling tool performs revocation, so it is trivially distinguishable from create_api_key/list_api_keys 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?
The scope prerequisite ('Requires the api_keys:revoke scope') gates usage and is useful, but there is no explicit statement of when to revoke versus disabling or rotating a key, and no mention of the sibling list_api_keys/create_api_key as the way keys come into existence. Usage is implied by the verb rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a list of emails (up to 4096 per call) for bulk verification. Billed per unique valid address, and governed by the plan's batch_max (see get_pricing); omitting checks runs every check the plan allows, SMTP included. Pass api_key to bill and scope this batch against that pm_live_/pm_test_ key's own account instead of the caller's session account; omit it to use the caller's own session account. Requires the email:verify:bulk scope on whichever account ends up authenticating the call. Returns a batch_uuid; poll it with get_batch or get_batch_results. Set final false to keep intake open, then feed further chunks with append_batch_emails.
| Name | Required | Description | Default |
|---|---|---|---|
| final | No | Whether this is the batch's only or final chunk (defaults to true). Set false to keep intake open, then feed further chunks with append_batch_emails. | |
| checks | No | Optional check wire strings (syntax, mx, smtp, disposable, role, free, catchall); defaults to every check the caller's plan allows, smtp included. A check outside the plan is refused. | |
| emails | Yes | Email addresses to verify (up to 4096). Billed per unique valid address and governed by the caller's plan batch_max (see get_pricing). A batch closed by this call (final: true, the default) needs at least batch_min (20) distinct valid addresses; verify fewer with verify_email. | |
| api_key | No | Optional pm_live_ (or pm_test_) API key. When present, this batch is billed and scoped against that key's own account instead of the caller's session account, and the key must carry the email:verify:bulk scope. Omit to use the caller's own session account. | |
| custom_ids | No | Optional per-email client references, index-aligned 1:1 with emails. Echoed back verbatim in get_batch_results so you can map each result to your input row. Do not put the email address or any PII here, use your own row identifier (e.g. a CRM id). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it discloses per-unique-valid-address billing, plan batch_max limits, the required email:verify:bulk scope, and that passing api_key rebills/scopes the batch to that key's account. The default of running every plan-allowed check, SMTP included, is also surfaced.
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 capacity, with no filler sentences. The middle sentence is dense, packing billing, plan limits, checks defaults and account scoping into one long clause chain, which slightly hurts scannability.
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 5-parameter write/billing tool with no annotations and no output schema, the description still covers lifecycle (batch_uuid plus polling), cost model, permission requirement, chunking, and the minimum-address constraint. Nothing essential for a correct first call 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, but the description adds real meaning beyond the schema: it frames api_key as an account/billing switch rather than just a credential, and summarizes the final/append_batch_emails interaction and the checks default. It stops short of adding format or validation detail the schema doesn't already give.
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 ('Submit a list of emails ... for bulk verification') with an explicit capacity bound (4096 per call). It is clearly separable from the single-address sibling verify_email, which it names for small inputs.
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 routing: poll with get_batch or get_batch_results, set final false and continue with append_batch_emails, use verify_email when below batch_min, and consult get_pricing for batch_max. When-to-use and when-to-use-something-else are both covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a webhook endpoint's url, events, description, or status (active/paused). Unset fields keep their current value. Uses the caller's own session bearer. Requires the webhooks:update scope on the caller's session.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Optional new target URL. Omit to keep the current value. | |
| events | No | Optional new event type strings. Omit to keep the current value. | |
| status | No | Optional new status, active or paused. Omit to keep the current value. | |
| description | No | Optional new description. Omit to keep the current value. | |
| webhook_uuid | Yes | Public UUID of the webhook endpoint to update. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose real behavior: partial-update/merge semantics ('Unset fields keep their current value'), authentication via the caller's own session bearer, and the required webhooks:update scope. It omits what happens on invalid event strings, idempotency, and any rate limits, keeping it short of 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 tight sentences, front-loaded with the action and fields before the merge semantics and auth requirements. No redundant or filler content; every sentence adds information an agent would otherwise have to guess.
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 and no output schema, the description covers the field set, merge behavior, and auth/scope requirements, which is enough to invoke it correctly. It stops short of describing the response body, which the absence of an output schema leaves 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 100%, so the schema already documents each parameter and the 'omit to keep current value' semantics. The description adds the status values (active/paused), which the schema does not enumerate, but otherwise restates the field list rather than adding syntax or validation detail.
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 (update) and resource (webhook endpoint) plus the exact mutable fields and the status enum values. The verb choice cleanly separates it from the create_webhook, delete_webhook, and get_webhook siblings without needing their 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?
The update verb and the note that unset fields keep their current value imply the use case is modifying an existing webhook, and implicitly exclude create/delete. However, there is no explicit when-to-use statement, no prerequisite that the webhook must already exist, and no routing guidance toward alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a single email address and return its deliverability verdict, score, and checks. Pass api_key to bill and scope this verification against that pm_live_/pm_test_ key's own account instead of the caller's session account; omit it to bill your own session's wallet directly (needs the email:verify:single scope).
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Email address to verify. | ||
| api_key | No | Optional. A pm_live_/pm_test_ key to bill and scope this verification; omit to verify with your own session (billed to your wallet, needs the email:verify:single scope). | |
| idempotency_key | No | Optional idempotency key so repeated calls replay the same job. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the billing model (charged to the key holder or the session wallet), the scoping behavior, and the required email:verify:single scope. It stops short of covering rate limits, quota consumption per call, or failure/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?
Purpose and return values are front-loaded, then the parameter nuance follows. It is a single dense semicolon-joined sentence with no filler, though the second clause is long enough to be slightly harder to parse at a glance.
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 describing the returned verdict/score/checks is necessary and it does so. Combined with the billing and scope disclosure, an agent has enough to invoke it correctly, though error handling and quota cost are unaddressed.
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%, so the schema already documents all three parameters, making 3 the baseline. The description restates the api_key billing/scoping semantics with slightly more context than the schema, but adds essentially nothing about idempotency_key or the email format.
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 address') and even previews the return payload (deliverability verdict, score, checks). The word 'single' implicitly separates it from batch siblings like submit_batch, but no sibling is named explicitly, so differentiation is inferred rather than stated.
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 conditional guidance for the api_key parameter (pass it to bill/scope against that key's account, omit it to bill the session wallet). However, it never says when to choose this tool over the bulk alternatives such as submit_batch for multi-address verification, so tool-selection guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
append_batch_emails2 fields changedInput schema / properties / checks / descriptionPrevious value: -"Optional check wire strings (syntax, mx, smtp, disposable, role, free, catchall); defaults to the plan's allowed checks minus smtp. A streamed caller should pass the same checks on every chunk so the whole batch runs one check set."New value: +"Optional check wire strings (syntax, mx, smtp, disposable, role, free, catchall); defaults to every check the caller's plan allows, smtp included. A streamed caller should pass the same checks on every chunk so the whole batch runs one check set."Input schema / properties / emails / descriptionPrevious value: -"Email addresses to verify in this chunk (up to 4096). May be empty to close intake without adding more emails."New value: +"Email addresses to verify in this chunk (up to 4096). May be empty to close intake without adding more emails. A final chunk is refused when the batch would close with fewer than batch_min (20) distinct valid addresses; the batch then stays open."submit_batch2 fields changedInput schema / properties / checks / descriptionPrevious value: -"Optional check wire strings (syntax, mx, smtp, disposable, role, free, catchall); defaults to the plan's allowed checks minus smtp. SMTP is opt-in and still subject to plan gating."New value: +"Optional check wire strings (syntax, mx, smtp, disposable, role, free, catchall); defaults to every check the caller's plan allows, smtp included. A check outside the plan is refused."Input schema / properties / emails / descriptionPrevious value: -"Email addresses to verify (up to 4096). Billed per unique valid address and governed by the caller's plan batch_max (see get_pricing)."New value: +"Email addresses to verify (up to 4096). Billed per unique valid address and governed by the caller's plan batch_max (see get_pricing). A batch closed by this call (final: true, the default) needs at least batch_min (20) distinct valid addresses; verify fewer with verify_email."append_batch_emailscheck_balancecreate_api_keycreate_webhookdelete_webhookget_batchget_batch_resultsget_pricingget_usageget_verificationget_webhooklist_api_keyslist_batcheslist_jobslist_transactionslist_webhooksrevoke_api_keysubmit_batchupdate_webhookverify_emailVerify email deliverability by SMTP. Catch-all/disposable/role detection. EU-hosted, GDPR-ready.
Verify email addresses before you send: single, batch (50) and bulk lists (10,000).
Verify email addresses and clean lists to improve deliverability and sender reputation.
Verify email addresses in bulk: syntax, domain, MX, disposable and role addresses, SPF and DMARC
Add one secure layer between your agents and this server.
