lookup

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description's one addition beyond structured data is 'Free', which usefully tells the agent this call consumes no balance or credits — real behavioral context for a budget-related tool. It adds nothing about pagination, latency, or auth, so this is a modest contribution rather than rich disclosure.

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 short sentence fragment, front-loaded with the cost signal ('Free') before the payload contents. It is efficient with no padding, though it is arguably terse to the point of under-specification rather than genuinely concise.

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 zero parameters, an output schema defining the return shape, and annotations covering safety, the description only needs to establish scope and routing — and it establishes scope adequately. It omits any routing to sibling tools, which for a tool sitting among nine lookups is a real gap. Minimum viable rather than complete.

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 nothing for the description to disambiguate; the baseline for a parameterless tool applies. The schema is trivially complete and the description correctly avoids inventing inputs.

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 the resource (the account) and enumerates what it returns: available balance, connection limits, allowed products. That is specific enough for an agent to know this is the account/limits introspection tool. It does not, however, contrast itself with any sibling such as vri_bulk_status or vri_operation_status.

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 explicit when-to-use statement, no when-not-to-use, and no named alternative among the ten sibling tools. The 'Free' prefix hints that cost is a decision factor, which is a mild usage signal, but the agent must infer that this is a pre-flight/limits check before submitting jobs.

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 readOnlyHint=false, idempotentHint=false and openWorldHint=true; the description goes well beyond them by disclosing that each number is a fresh paid read, that a spend scope is required, that live customer keys draw on balance, that repeating a call can charge again, and how request_id converts a repeat into a safe retry. This is exactly the cost/idempotency behavior an agent needs before invoking a billable open-world tool, and it is consistent with the annotations rather than 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?

The purpose and batch limit are front-loaded, followed by cost, retry and testing guidance in short declarative clauses with no filler. The telegraphic style ('Live customer keys spend balance') is dense but every sentence carries a distinct operational fact.

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?

An output schema exists, so return values need not be described, and the description covers the critical unknowns for a billable bulk tool: spend scope, re-charge risk, retry safety, cost capping and test keys. The remaining gap is sibling routing — nothing tells the agent when to prefer vri_number_lookup, vri_quote or vri_spam_check instead.

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 phone_numbers, products, max_cost and request_id thoroughly, and the baseline is 3. The description largely restates the schema's cost-cap and request_id semantics ('Use max_cost to cap the quote', 'reuse a stable request_id with identical arguments'), adding only the retry-charge linkage that the schema implies, so there is little net-new parameter 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 gives a specific verb and resource ('Live lookup'), the batch ceiling (up to 100 North American phone numbers in one call) and the returned data sets (carrier, line type, routing, optional cnam/spam/messaging). It clearly reads as the bulk counterpart to the sibling vri_number_lookup, though it never names that sibling explicitly, so differentiation is inferred from 'bulk'/'up to 100' 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 actionable operational context: use max_cost to cap the quote, use a test key for integration tests, and reuse request_id with identical arguments for a safe retry. What it does not provide is an explicit when-not or a named alternative (e.g. vri_number_lookup for a single number, vri_quote for pricing only), which keeps it short of a 5.

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=true, so the safety profile is fully covered. The description adds only that this reports 'status and progress', implying a pollable job, but says nothing about terminal states, polling cadence, or job expiry. Some value added, but thin.

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 efficient sentence with the resource and key front-loaded and zero filler. It is arguably too terse rather than too long, but structurally it is clean.

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?

An output schema exists so return values need not be described, and the single required param is documented. However, the description omits the workflow context (submit -> poll status -> fetch results) that would tell an agent where this tool fits relative to vri_submit_job and vri_job_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?

One parameter with 100% schema description coverage, which already explains the job_id comes from vri_submit_job or the REST Jobs API. The description's 'by job id' restates the schema rather than adding format or constraint detail, 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 resource (VRI bulk lookup job) and what is returned (status and progress), keyed by job id. It is clear on its own, but it never distinguishes itself from the closely related siblings vri_job_results and vri_operation_status, leaving the agent to infer the boundary.

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 guidance, no polling guidance, and no mention of alternatives. Given siblings like vri_job_results (results of a job) and vri_operation_status (status of an operation), the absence of any routing cue is a real gap.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds non-annotation context: zero cost, owner-scoped visibility, and cursor-termination behavior — genuinely useful traits beyond the structured fields.

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 front-loaded clauses, no filler, purpose stated before the operational caveats. It is arguably under-specified rather than padded, so conciseness itself is fine.

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 an output schema present, return values need not be explained, and annotations cover safety, so the remaining burden is modest. The description covers cost, scope and pagination; the only real omission is sibling disambiguation among the several status/lookup tools.

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 0%, so the description must carry all three parameters and it does not. It explains cursor iteration (as 'next_cursor', which does not match the schema's 'cursor' field name) but says nothing about limit's cap or job_id's meaning, and the naming mismatch risks confusing an agent.

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 fragments 'Free, owner-scoped stored results' plus 'never re-submit a completed job' identify this as the retrieval side of the job lifecycle, implicitly contrasted with vri_submit_job. It stops short of an explicit verb and does not differentiate from other status/result readers such as vri_operation_status or vri_bulk_status.

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 operational instructions ('Follow next_cursor until null', 'never re-submit a completed job') and a cost signal ('Free'), which is useful when-versus-when-not context. However it never says when to call this instead of sibling status tools, leaving selection to inference.

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

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

Adds substantial context beyond the annotations: live keys spend balance, repeat calls can charge again, request_id reuse with identical arguments avoids a second charge, and the read is never cached. This explains why readOnlyHint is false and idempotentHint is false, and gives the agent an actual safe-retry path.

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 capability, then layers billing and retry guidance in short declarative sentences. It is on the longer side and slightly repetitive around charging, but every sentence carries actionable 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?

Covers scope, cost, retry semantics, test mode, and optional data sets for a tool with a complete schema and an output schema that handles return values. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates max_cost as a cap and request_id as a retry key, and names the optional products (cnam/spam/messaging), but adds no syntax or format detail the schema does not already carry.

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 ('Live intelligence for ONE North American phone number') and enumerates exactly what comes back: carrier, line type, LRN routing, porting date, plus optional cnam/spam/messaging. The capitalized 'ONE' cleanly separates it from the vri_bulk_lookup sibling.

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 operational guidance: cap spend with max_cost, use a test key for integration tests, reuse request_id for safe retries. It does not explicitly name vri_bulk_lookup as the alternative for multi-number work, so the routing is implied by 'ONE' 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 readOnly, idempotent and non-destructive, so safety is covered. The description still adds real value by disclosing cost ('Free') and a non-obvious operational constraint about not resubmitting pending work with a new ID.

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 dense sentence that front-loads the cost signal and the usage trigger with zero filler. It is perhaps terse to the point of omitting needed detail, 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?

An output schema exists, so return-value explanation is unnecessary, and annotations cover the safety profile. Still, for a tool whose entire contract is 'pass an operation ID', the description says nothing about acquiring that ID, which is the main completeness 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 0% and operation_id is undocumented in both the schema and the description. The description never explains what an operation ID is or where the agent obtains it, leaving the sole parameter's semantics entirely unexplained.

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 recognizable verb+resource ('check an operation') with a specific condition ('after an interrupted call'). However, it does not distinguish this from siblings like vri_bulk_status or vri_job_results, which all sound like status-checking tools; the agent must guess from the name alone which one applies.

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 when-to-use context ('after an interrupted call') plus an important behavioral rule ('pending work must not be resubmitted with a new ID'). It lacks explicit named alternatives, but the triggering scenario is clear enough to route an agent.

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, so the safety profile is covered. The description adds genuinely useful context beyond them: the estimate is free, it uses account pricing, and it deduplicates valid numbers rather than performing lookups.

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 dense sentence with the most decision-relevant fact ('Free') front-loaded and no filler. It is terse to the point of being elliptical, 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?

An output schema exists, so return-value explanation is unnecessary, and the description covers cost and non-lookup behavior. However, with 0% schema description coverage it leaves the products enum and include_sms_assessment undocumented and gives no guidance on when a quote should precede a real lookup.

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 0% across 3 parameters. The description implies phone_numbers are validated and deduplicated, which adds some meaning, but products and include_sms_assessment receive no explanation anywhere, leaving the agent guessing about the enum options and the SMS assessment flag.

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 action (free estimate of lookup cost) and a key constraint (no lookup is performed), which cleanly separates it from the lookup siblings like vri_bulk_lookup and vri_number_lookup. It is clear but leans on the title 'Estimate lookup cost' to fully name the resource.

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: the 'free' and 'no lookup' phrasing suggests calling this before committing to a paid lookup or submit_job, but there is no explicit when-to-use or when-not-to-use statement and no sibling is named as an alternative.

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 readOnlyHint=false (it costs money), idempotentHint=false, and openWorldHint=true; the description adds the crucial context behind those flags — live keys spend balance, repeat calls can charge again, and a stable request_id is the safe-retry path. It also discloses the semantic caveat that unknown reputation never clears a number to message, which no annotation conveys.

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?

Dense but front-loaded: capability statement first, then the negative scope, then return contents, then operational cautions. A few clauses overlap (the delivery-test disclaimer and the compliance disclaimer), but nearly every sentence carries distinct 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?

Covers what the tool is, what it returns (sms_capable, VoIP flag, spam reputation, local time with calling-window flag, reasons), its limits, cost/retry behavior, and its relationship to sibling tools. An output schema exists, so return-format detail is appropriately delegated.

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 cross-parameter behavioral meaning: request_id is framed as both a billing-safety and receipt-retrieval mechanism, and max_cost as a pre-lookup quote cap. These tie the parameters to consequences rather than merely restating their types.

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 — line-type-based SMS capability and reputation signals for a North American number — and names exactly what it is not (delivery test, compliance check). It also differentiates from siblings by noting it performs its own LRN and spam lookup so vri_number_lookup need not precede 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?

Explicit when/when-not guidance: avoid calling after number_lookup for the same data, use a test key for integration tests, use max_cost to cap the quote, reuse request_id for safe retries. Alternatives and exclusions are spelled out rather than implied.

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: annotations say idempotentHint=false and nothing about cost, while the description discloses that live keys spend balance, that repeat calls can charge again, and that reusing a request_id with identical arguments yields a safe no-charge retry. It also documents the max_cost cap and the explainable risk block.

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 purpose, then packs billing/retry/cost/test-key guidance into four short sentences with no filler. Slightly telegraphic and dense, but every sentence carries actionable 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?

An output schema exists, so return values need no further explanation; the description nonetheless summarizes the risk block. With billing, retry, cost-cap, and test-key behavior all covered, an agent has everything needed to invoke it 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 the schema already documents all three parameters, including the request_id retry semantics and the max_cost rejection rule. The description largely restates that (cost cap, safe retry) rather than adding new syntax or format detail, 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+resource and scope: 'Spam/scam/robocall reputation for one North American phone number.' The 'one number' scoping and the named `risk` output distinguish it from bulk/other lookup siblings without needing to open 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 clear operating context — live keys spend balance, test keys for integration tests, max_cost to cap the quote — but never explicitly says when to prefer this over vri_number_lookup, vri_bulk_lookup, or vri_quote. Context is clear; alternatives are 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?

With annotations only covering the read/write/idempotency profile, the description adds substantial behavioral context the annotations cannot: balance is reserved up front, the job runs in the background, a customer API key is required, live keys actually spend balance, and a repeated call can charge again unless a stable request_id is reused. This is exactly the cost/billing disclosure an agent needs before invoking a billable 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?

The scope statement is front-loaded, followed by cost, auth, retry and testing guidance. Every sentence carries distinct operational information with no filler.

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

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

An output schema exists, so return values need no explanation. Combined with the annotations covering the safety profile and the description covering billing, auth, retry and monitoring, an agent has everything required to call 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 all four parameters are already documented in the schema, including max_cost's rejection behavior and request_id's retry semantics. The description's mentions of max_cost and request_id restate that information rather than adding new syntax or format detail, so the baseline 3 applies.

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

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

The description names a specific verb, resource and scope: 'Submit an ASYNC bulk lookup job for up to 10000 North American phone numbers.' It differentiates from the synchronous sibling by emphasizing ASYNC/background execution and explicitly routes to vri_bulk_status for progress.

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 operational guidance: check progress with vri_bulk_status, cap spend with max_cost, use a test key for integration tests, and reuse request_id to avoid double charges. It does not explicitly state when to prefer this over the synchronous vri_bulk_lookup sibling, so the alternative-selection rule 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.