BillionVerify

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true, so the agent knows this is a non-idempotent write with external effects. The description adds the notification scope (verification lifecycle), which is useful context, but does not disclose whether the endpoint must be verified, whether creation fails on duplicate URLs, or anything about the returned webhook identifier. For a mutation tool, more behavioral detail would help.

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 a clear verb-resource-entity structure. Nothing is wasted and the core purpose is stated first.

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 2-parameter creation tool with full schema coverage and annotations covering the safety profile, the description covers the essential purpose but stops short of explaining what happens on creation (e.g., returned webhook ID, activation requirements) and doesn't note the absence of idempotency in a way an agent would act on. Adequate but with clear gaps.

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 url and events are fully documented in the schema, including the HTTPS requirement and the event enum values. The description adds no parameter-level detail beyond the schema. 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?

States a specific verb 'Create' and resource 'webhook endpoint', and scopes its purpose to 'verification lifecycle notifications', which distinguishes it from siblings like list_webhooks and delete_webhook. An agent can immediately tell this is the creation counterpart to those tools.

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

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

The description implies usage (create a webhook to receive verification lifecycle notifications) but gives no explicit when-to-use versus alternatives, no mention of list_webhooks for inspection, and no prerequisites like required permissions or whether duplicate URLs are allowed. Sibling tool delete_webhook makes the create/delete pairing inferable, but no explicit routing guidance is provided.

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 and idempotentHint=false, so the safety profile is covered. The description adds that deletion is permanent and that notification delivery stops immediately, which is genuinely useful behavioral context beyond the annotations, but it omits whether the endpoint can be recovered or what happens to in-flight deliveries.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The action is front-loaded and the consequence sentence immediately follows, so nothing needs re-reading.

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 destructive tool with full annotation coverage and no output schema, the description supplies what is needed to call it correctly and notes the irreversibility. It stops short of covering recovery or downstream effects of removing an endpoint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single required parameter with 100% schema description coverage, so the schema already documents webhook_id fully. The phrase 'by identifier' adds no syntax, format, or source-of-value detail beyond the structured field. 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 (delete) plus resource (webhook endpoint) and scoping detail (by identifier). It is immediately distinguishable from create_webhook and list_webhooks in the sibling set 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 permanence and the immediate stop of notifications imply this is the destructive path, but the description never states when to use this versus deactivating or re-creating a webhook, nor any prerequisites or warnings. Usage is implied rather than guided.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description layers on the fact that the balance is scoped to the authenticated account, which is useful but modest added value beyond annotations.

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 no filler. Every word earns its place: verb, qualifier ('current'), resource, and scope.

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 no-param read tool with annotations carrying the full safety profile and no output schema, the description identifies the returned quantity ('current credit balance') and the account scope. It does not mention currency/credit units or formatting, 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?

The tool takes zero parameters, which is the baseline-4 case per the rubric. There is nothing to disambiguate, and the description correctly implies no input is required.

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 (Get) and resource (credit balance) with explicit scope ('authenticated account'). No sibling tool deals with billing or balance, so the agent can immediately distinguish it from the webhook, verification, and task-status siblings.

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 purpose implies when to use it (to check remaining credits before issuing paid operations), but there is no explicit when/when-not guidance or named alternative. With no siblings covering billing, the absence is low-risk, so this lands at minimum-viable.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds that filtering parameters change the return format from a URL to CSV content, which is a meaningful behavioral trait beyond annotations. However, it does not mention URL expiration 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?

A single well-structured sentence that front-loads the primary purpose and appends the conditional mode. Every clause carries information and 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?

Given no output schema, the description should explain return values and it does: signed URL vs CSV content. With full annotation coverage and complete schema documentation, the only gap is the absence of details like URL expiration, authentication needs, or pagination for large results.

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 all 7 parameters are documented in the schema. The description adds that the boolean filter parameters (role, valid, invalid, etc.) trigger CSV output instead of a signed URL, which is a useful semantic layer not present in the schema. But beyond that mapping, the description does not elaborate on parameter behavior.

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 ('Get a signed download URL') with the resource clearly being 'completed results'. It also reveals a second output mode ('or CSV content when filtered or rebuilt from history'), which is genuinely useful. The sibling 'get_verification_history' is related but the description does not explicitly differentiate from 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?

The 'when filtered or rebuilt from history' clause implies a conditional context for the CSV mode, but there is no explicit guidance on when to use this tool versus get_verification_history or get_task_status. Usage context is implied rather than stated.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description contributes only the 'asynchronous task' framing; it says nothing about polling cadence, task expiry, or terminal vs. in-progress states, which are the behavioral details an agent actually needs here.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tightly worded sentence with the resource and scope front-loaded and zero filler. Appropriate sizing for a one-parameter, read-only lookup.

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 is the only place that could explain possible status values (pending/running/succeeded/failed) and whether the task result is retrievable here or elsewhere. That gap matters for an async status tool, though the call itself is simple enough that the definition is still workable.

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 single task_id parameter is already fully documented with its origin ('returned by a previous verification request'). The description adds no format, length, or validity information beyond the schema, 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 ('Get') and resource ('current status of an asynchronous verification task'), which is unambiguous and clearly distinct in kind from sibling list/stats tools. It does not explicitly name how it differs from get_verification_history or get_verification_stats, but the 'status of a task' framing is specific enough to route correctly.

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 when-to-use statement, prerequisite, or alternative is given. The reader must infer from the word 'asynchronous' that this is a polling call made after a prior verification request — and that dependency is only spelled out in the schema's parameter text, not the description.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful scoping detail that history is limited to the authenticated account, but says nothing about ordering, time ranges, or pagination behavior beyond what the schema already states.

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 no filler or redundancy. Every word contributes to stating the tool's purpose.

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 paginated read-only list tool, the description plus annotations and full parameter documentation cover nearly everything needed to invoke it correctly. It could be slightly stronger by noting what a history record contains or how results are ordered, since no output schema exists.

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 page and limit are already documented in the input schema with defaults and bounds. The description adds no additional parameter meaning beyond that, matching the baseline for fully documented schemas.

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 (List) and resource (verification history) scoped to the authenticated account. It is clear what the tool does, though it does not explicitly differentiate itself from the sibling get_verification_stats, which also deals with verification data.

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 guidance on when to use this versus the similarly named get_verification_stats, nor any prerequisites, pagination limits, or exclusion criteria. The agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes that results are aggregated and account-scoped, but says nothing about return format or whether periods bucket by day/week.

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 front-loaded sentence with no filler; the verb and scope come first. Efficient, though it is arguably too terse to carry much guidance.

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, fully-annotated, single-optional-parameter read tool with full schema coverage, the description is adequate. No output schema exists, but the description's 'aggregated statistics' phrasing signals the return shape well enough.

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 single 'period' parameter carries an enum with a default, so the schema fully documents it. The description adds no meaning beyond that, which is the baseline 3 case.

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 (get) and resource (aggregated verification statistics) scoped to the authenticated account, which distinguishes it from the more detailed get_verification_history. It stops short of naming the sibling explicitly, so it is clear but not maximally differentiated.

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 guidance on when to use this over get_verification_history, nor any exclusions or prerequisites. Usage is only implied by the word 'aggregated', leaving the agent to infer the choice between summary and detailed endpoints.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, fully covering the safety profile. The description adds no behavioral context beyond that (no mention of latency, rate limits, or what a healthy/unhealthy result looks like), but it does not contradict anything either.

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 short sentence with the verb and scope front-loaded and no wasted words. Perfectly sized for a no-argument diagnostic tool.

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 parameterless, annotation-covered health check with no output schema, the description is nearly sufficient. It could add a phrase about what constitutes a healthy result, but nothing needed to invoke the tool 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?

The tool takes zero parameters, which is the baseline-4 case per the rubric. Nothing about parameter semantics needs explaining.

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 (check) and resource (health of the BillionVerify MCP server), so an agent immediately knows what the tool does. It does not explicitly contrast itself with siblings, but no sibling performs health checks, so the purpose is unambiguous.

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

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

The description gives no when-to-use guidance, prerequisites, or alternatives. Usage is only weakly implied by the verb 'check' – there is no statement of when a health check is warranted or what to do with the result.

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, idempotentHint=true, destructiveHint=false, and a closed-world scope, so the safety profile is fully covered structurally. The description contributes only the account-scoping qualifier; it says nothing about pagination, result size, or error behavior when no webhooks exist.

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 no filler. The scope qualifier is placed before any would-be caveats, so nothing needs to be trimmed.

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 list tool whose annotations fully carry the safety and idempotency profile, the description covers what is needed to invoke it. The only residual gap is return-shape/pagination detail, which matters somewhat more given there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the baseline there is no parameter surface for the description to explain. Nothing is missing 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?

Names a specific verb (List) and resource (webhook endpoints) and scopes it to "the authenticated account." It is clearly separable from create_webhook and delete_webhook by operation, though it never names a sibling or states an explicit contrast.

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: an agent can infer this is the read/enumeration counterpart to create_webhook and delete_webhook. There is no explicit when-to-use, prerequisite, or exclusion language, and no alternative named.

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 declare this is not read-only, not idempotent, and open-world, so the agent already knows it has effects. The description adds meaningful context beyond that: the operation consumes credits from the connected BillionVerify account, which explains the cost/irreversibility implied by the non-idempotent hint. It does not quantify credit cost per address or note 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?

Three tight sentences with no filler. The core capability and the batch limit come first, and the chunking rule and credit note follow in order of operational importance.

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 state the return shape at a high level ('a verdict for each'), which is what an agent needs to decide how to consume results. It stops short of describing possible verdict values or whether partial failures are possible across the batch.

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 parameters (emails, check_smtp) are already documented in the schema. The description restates the 1-50 range that is already expressed via minItems/maxItems and says nothing about check_smtp or the SMTP trade-off, so it adds little beyond the schema.

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

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

States a specific verb (verify) and resource (email addresses), plus the batch limit and that a per-address verdict is returned. The batch framing implicitly distinguishes it from the sibling verify_single_email, though it never names that sibling 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?

Provides actionable guidance for oversized inputs ('split longer lists into chunks of 50'), which is real usage instruction. However, it never says when to prefer this over verify_single_email or what to do if you only have one address, so routing between siblings 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?

Annotations only flag this as non-read-only, open-world, and non-idempotent; the description adds the material fact that it consumes credits from the connected BillionVerify account, which is real cost information an agent needs. It does not mention rate limits or what happens on cache hits beyond force_refresh's schema note.

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 purpose, then the mechanics, then the cost. No filler or repetition of the tool name.

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 3-parameter tool with no output schema, the description covers purpose, mechanism, and the credit cost, which is enough to invoke it correctly. It stops short of hinting at the result shape (e.g., deliverable vs undeliverable), which would help an agent interpret the response.

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 email, check_smtp, and force_refresh are already documented. The description reinforces check_smtp ('optionally the mailbox over SMTP') but says nothing extra about force_refresh or caching behavior beyond the schema, so the baseline of 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 ('Verify whether a single email address can receive mail') and enumerates the actual checks performed (syntax, domain mail servers, optional SMTP). The word 'single' cleanly distinguishes it from the sibling verify_batch_emails.

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?

Scope is implied by 'single email address' versus the obvious batch sibling, and the description notes that SMTP checking is optional, but it never explicitly says when to pick this over verify_batch_emails or when to enable check_smtp. Usage must be inferred rather than read.

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