Emailable MCP by usefulapi

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

Goes well beyond the annotations: it quantifies the cost (1 credit per email), warns of a possible saved-card charge, notes test_ keys spend nothing, states the batch cannot be cancelled here, and explains why the openWorld/non-idempotent call is never retried. These are the exact operational risks the destructiveHint and idempotentHint flags hint at but do not explain.

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 cost warning is front-loaded in caps and every subsequent sentence carries a distinct load: billing behavior, key type, cancellation/retry policy, return value and polling path, and compliance scope. No sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a non-idempotent, credit-spending, open-world mutation with no output schema, the description covers cost, failure recovery, return shape ('returns the batch id'), and the follow-up tool. Nothing an agent needs before invoking or after failing 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 the schema already documents emails, confirm, retries, and response_fields, including the 1-5000 bound and the const:true confirm requirement. The description's 'up to 5000 email addresses' restates the schema's maxItems and adds no syntax or default detail for retries or response_fields. 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 ('starts a bulk verification of up to 5000 email addresses') and immediately marks it as credit-spending, which cleanly separates it from emailable_verify_email (single address) and emailable_get_batch (polling). The agent can route correctly 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?

Explicitly names the alternatives and the conditions that select them: poll with emailable_get_batch, and if the call fails or times out check emailable_get_account before retrying. It also states when NOT to blindly retry, with the reason (double charge).

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 this a read-only, non-destructive, open-world call, so the safety burden is covered. The description adds that the result is scoped to the calling API key and lists its payload fields, but says nothing about rate limits, quota exhaustion semantics, or error behavior for an invalid key.

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 fragments: what it returns, when to use it, and the endpoint. Zero filler and the payload content is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so describing the returned fields (owner email, available_credits) is exactly the compensating detail needed, and it is present. A little more on how credits are consumed or what happens on auth failure would make it fully self-sufficient.

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 no parameters, so per the baseline there is nothing for the description to disambiguate. The schema is empty by design and the description correctly makes no parameter claims.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (the account behind the API key) and names the concrete fields returned, owner email and available_credits, plus the underlying endpoint. Siblings are obviously distinct operations (batch/verify), so it is easy to place, though it never explicitly contrasts itself with 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?

"Check it before a large batch" gives a concrete triggering condition, which is real usage guidance. It stops short of naming alternatives or stating when not to call it, so it is clear context without exclusions.

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, but the description adds material behavior: inline retention of 30 days for batches up to 1,000 emails, a 5-day temporary download_file link, the caution to share it only with the account owner, and the fact that replies may be truncated below the requested limit.

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 purpose is front-loaded and the dense single paragraph carries almost no filler; retention windows and the sharing caution are high-value. It is long and packs multiple concerns (pagination, download link, cost) into one block, which slightly hurts scanability.

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 full burden and does so: it names the response sections, the conditional inline emails array with its retention, the download_file fallback, and the pagination cursor. An agent can call this and interpret the response without further documentation.

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 meaning by explaining that the returned page may hold fewer results than limit and how to continue via emails_page.next_offset, and by linking download_file to larger batches. It does not elaborate on partial or include_emails beyond what the schema already says.

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 (batch status/results) and explicitly ties it to the producing sibling emailable_create_batch, so it is distinguishable from create_batch at a glance. It even enumerates the returned fields (message, progress, reason_counts, total_counts), removing ambiguity about what 'batch' means here.

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 tells the agent how to consume results: paginate with emails_page.next_offset, and use download_file for large batches. It also notes the call is free, which is a practical selection signal. It does not state when NOT to use this over emailable_get_account or emailable_verify_email, so it falls short of explicit exclusions.

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?

Goes well beyond the annotations: credit cost per call, credit refunded on unknown, no automatic retries, the try_again-timeout recovery path and the 5-minute no-recharge window, plus the legal constraint on verified addresses. Annotations declare destructive/openWorld but say nothing about billing or idempotency-in-practice; the description supplies all of that.

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?

Information-dense and front-loaded with the credit warning, which is the highest-stakes fact. Slightly long, and the enumerated return fields pad it, but with no output schema those details earn their 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?

With no output schema, the description carries the return-value burden and does so completely: state values, reason, score range, flags, did_you_mean, and parsed components. Combined with cost, retry, and compliance guidance, an agent has everything needed to call and interpret this 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema cannot convey: the timeout parameter's failure mode ({status: 'try_again'}) and the fact that repeats within 5 minutes aren't charged. It does not describe the smtp or accept_all flags, leaving those to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('verifies one email address') and the singular scope implicitly distinguishes it from the sibling emailable_create_batch, which handles many addresses. An agent can tell what this does and when it is the wrong choice without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real usage context: it spends credits, test keys spend none, terms permit verifying opt-in subscribers, and it explains the retry path when the reply is {status: 'try_again'}. It does not explicitly say 'use emailable_create_batch for multiple addresses', so the alternative is left to inference from 'one email address'.

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