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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond annotations: each number is 'a fresh paid read' and 'spend scope required', disclosing cost and entitlement requirements that an agent would not otherwise know.

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 with no fluff. The core operation and size limit are front-loaded, and the paid-read spend warning is placed second where it is easy to notice. Every phrase 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?

Given the output schema exists and annotations cover read-only/idempotent behavior, the description covers function scope, optionality, limits, cost, and entitlement. It stops just short of complete guidance because it doesn't explicitly contrast with sibling tools or explain what 'spend scope' entails, but an agent can invoke it correctly with available information.

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%, giving baseline 3. The description adds value by mapping product enums to concrete output categories (carrier, line type, routing, cnam/spam/messaging) and reinforcing the 'up to 100' limit and North American scope, which helps the agent reason about parameter values.

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

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

The description clearly states the verb 'lookup', the resource 'North American phone numbers', and the scope 'up to 100 in one call'. It also lists the data dimensions (carrier, line type, routing, optional cnam/spam/messaging), which distinguishes it from siblings like vri_spam_check or vri_number_lookup.

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 bulk nature is implied by 'up to 100 in one call', and the optional product list hints at use cases, but the description never explicitly says when to use this tool over vri_number_lookup for single lookups or vri_spam_check for spam-only checks. No exclusions or alternative routing are 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 readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the description does not need to restate those. It adds 'and progress' beyond a simple status read, but does not disclose behaviors like job lifecycle, polling semantics, or what happens before a job completes. This is consistent with annotations and adds modest value.

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 one short, front-loaded sentence that immediately states the core function. Every word earns its place and there is no redundancy with the schema or annotations.

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 one-parameter read-only tool with an output schema and robust annotations, the description is nearly sufficient. The main missing piece is explicit guidance about when to call it relative to job submission, but the schema's job_id source note partially compensates. Overall, an agent can likely invoke this correctly without much ambiguity.

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 job_id parameter already has a clear description stating it comes from vri_bulk_lookup or vri_submit_job. The tool description only says 'by job id,' which adds no semantic value beyond the schema. Baseline 3 applies because the schema handles parameter documentation.

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

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

The description clearly identifies the tool as returning status and progress for a VRI bulk lookup job, and specifies that it is keyed by job id. Though it lacks an explicit verb like 'retrieves', the meaning is unambiguous and distinct from sibling submit/lookup 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 provides no guidance on when to use this tool versus vri_bulk_lookup, vri_submit_job, or other siblings. It does not mention that this should be called after a job is submitted or that it is for polling progress. Usage context must be inferred entirely from the tool name and schema.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful behavioral context by promising a fresh read of live numbering infrastructure and explicitly stating that carrier data is never cached, which is valuable beyond the 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?

The description is two tight sentences with no filler. It front-loads the singular scope and core data domains, then adds the behavioral guarantee. Every clause earns its place, and it does not redundantly repeat 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?

With a full output schema, 100% parameter coverage, and annotations covering the tool's safety profile, the description supplies the remaining decision-relevant context: single-number live lookup and optional product selection. An agent has enough information to select and invoke this tool 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 both parameters are already fully documented in the input schema. The description adds only mild semantic context, such as clarifying that the lookup is for one number and that products are optional, which meets but does not exceed the baseline.

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 concrete read operation ('Live intelligence for ONE North American phone number') and enumerates the exact data domains returned: carrier, line type, LRN, porting activation, and optional CNAM, spam reputation, and messaging provider. The 'ONE' scope clearly distinguishes it from bulk siblings like vri_bulk_lookup.

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 clear context: use this for a single number where you need fresh carrier/routing intelligence and optionally additional data products. It does not explicitly name alternatives or state when not to use it, but the emphasis on 'ONE' and the later 'never cached' guarantee imply the boundaries against bulk and stale-data tools.

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 indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful context: it performs a live line-type read, returns approximate local time, applies an 8am-9pm calling window, and explicitly excludes DNC/reassigned/litigator data. This goes beyond the structured annotations without contradicting them.

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 carry a clear value proposition, a summary of outputs, and an important limitation. The 'ONE verdict' opening is immediately meaningful, and there is no filler or 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 single-parameter, read-only tool with an output schema, the description covers the decision-use case, key outputs, and a boundary of the tool's scope. The 8am-9pm window is specified, and because the output schema exists, exhaustively listing return fields is unnecessary. A brief note on error handling would round it out, 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?

The only parameter, phone_number, has 100% schema description coverage ('US/Canada number, any common format'). The description only restates the North American scope and adds no new parameter-level detail, so the baseline of 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?

The description states a specific purpose: a single verdict on whether a North American number can receive SMS and whether now is a reasonable time to send. It enumerates concrete outputs (sms_capable, VoIP flag, spam reputation, local time window) and explicitly distinguishes itself from legal-compliance tools. This makes it easy to separate from siblings like vri_spam_check or vri_number_lookup.

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 a clear use context ('for AI outreach') and an explicit exclusion ('not a legal compliance determination'). However, it never names alternative sibling tools or states when to choose this over vri_spam_check or vri_number_lookup, leaving the routing to implication rather than explicit guidance.

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, and destructiveHint=false, covering the safety profile. The description adds the useful constraint of 'one North American phone number' but does not disclose additional behavioral details such as response shape, data sources, 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?

A single, front-loaded sentence captures the tool's purpose with no filler. Every word earns its place, and the key scope qualifiers ('one', 'North American') are included without 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 simple, single-parameter, read-only tool with an output schema and full schema coverage, this description is complete enough. It tells the agent what the tool does and its geographic/single-number scope, while the annotations and schema cover safety and parameter details.

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 schema already documents the only parameter with 100% coverage, so the description adds little beyond reinforcing that it accepts one phone number. 'North American' aligns with the schema's US/Canada note but does not meaningfully extend the schema's meaning.

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

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

The description clearly identifies the tool as providing spam/scam/robocall reputation for a single phone number. The 'one North American phone number' qualifier distinguishes it from bulk-oriented siblings, though it does not name them explicitly or use an explicit verb like 'checks'.

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 domain terms 'spam/scam/robocall' and the single-number scope, so an agent can infer when to use it. However, the description offers no explicit when/when-not guidance or mention of alternatives such as vri_bulk_lookup or vri_sms_deliverability.

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?

The description discloses important non-obvious behaviors: balance is reserved up front, the job runs in the background, and jobs bill the account that owns the API key. These go beyond the annotations (readOnlyHint=false, idempotentHint=false) and help the agent set correct expectations. There is no contradiction with the 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?

Two dense sentences with no fluff. The first sentence delivers the core action, resource, and limit. The second adds billing, background execution, and the status-check path. 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?

With 100% schema coverage, an output schema, and informative annotations, the description covers the key context: async behavior, balance reservation, billing ownership, and monitoring via vri_bulk_status. It does not explicitly differentiate from other bulk/sync sibling tools, but 'ASYNC bulk' and the status reference imply the intended boundary.

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%: both 'phone_numbers' and 'products' are documented in the schema. The description mostly restates max 10000 and NA/US-Canada scope, and it does not add meaning for the 'products' parameter. Baseline 3 applies because the schema already handles parameter documentation.

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: 'Submit an ASYNC bulk lookup job.' It also specifies scope ('up to 10000 North American phone numbers') and highlights the asynchronous nature, which distinguishes it from synchronous lookup siblings like vri_number_lookup or vri_spam_check.

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 clearly establishes when to use the tool: for bulk async lookups up to 10000 numbers. It also gives operational guidance: check progress with vri_bulk_status and expect account-level billing via the API key. It does not explicitly name alternatives or state when not to use this tool, so no exclusions are provided.

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