ListPlus

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

Well beyond the annotations, the description discloses pricing tiers, key requirements, the 25/1000 record ceilings, the shape of the response ('findings per record with proposed fixes') and confirms no side effects ('Nothing is stored or changed'), which is valuable given there is no output schema. It stops short of saying what happens when the record limit is exceeded (error vs. truncation) or how findings are prioritized.

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 definition is compact and front-loaded with the most decision-relevant fact (FREE, with limits), followed by the check inventory and the side-effect guarantee. The mid-sentence ellipsis list is dense but each clause carries real information; 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 four-parameter tool with no output schema, the description covers cost, quotas, return shape and mutation safety, which is most of what an agent needs. Gaps remain around behavior at the quota boundary and the dangling `options`/pricing reference, which an agent cannot resolve from either the description or the 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?

Schema description coverage is 100%, so every parameter including the `ai` flag, `language`, and `categories` is already documented in structured fields; the tool description adds no parameter-level detail of its own. It also does not clarify the key requirement the schema's `ai` text references, nor reconcile the mention of an `options` object that does not exist in the schema (additionalProperties: false).

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 ('check contact records for errors') and enumerates the concrete check classes (email typos, role mailboxes, duplicates, phone/country mismatch, LinkedIn status text in names, placeholders), which makes the tool unmistakably a bulk record validator. It never names the overlapping sibling verify_email, so an agent must infer the boundary between single-address verification and full-record checking.

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-tier thresholds ('up to 25 records without a key, 1000 with one') and the note that `ai` is PAID tell the agent something about cost-driven selection, but there is no explicit 'use this when…' or 'use X instead' statement. Nothing tells the agent when to prefer enrich_records or verify_email over this tool.

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?

Beyond the annotations it discloses the commercial model (paid, requires a key, charged per hit for e-mail and phone, per-field credit prices and caps), the side effect (records land in the key's agent list in ListPlus, visible to the user), and the async contract (wait up to 25 s, then return a job_id to poll). That is exactly the cost/effect/latency context an agent needs before a non-read-only call.

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?

Cost and the estimate-first instruction are aggressively front-loaded, which is correct for a paid tool, and most sentences carry distinct information. The run of per-field price and cap figures is dense and could be trimmed to the two or three values that matter most.

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 6-parameter, async, billable mutation with no output schema, the description covers cost, key requirement, side effects, timeout, and the follow-up polling tool. An agent has everything required to call it safely and 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 coverage is 100%, so baseline is 3; the description still adds meaning by explaining the economic intent of the estimate flag (free, no key, price only) and the per-field charge structure that makes max_credits relevant. It does not clarify request_id deduplication or language 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?

The description uses a specific verb and resource plus a concrete field inventory (work e-mail, mobile, job title, LinkedIn, company, domain, industry, size, place) and states the input shape (name + company). It never names or contrasts itself with siblings like find_person or check_records, so the agent must infer which enrichment path is right.

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 operating sequence: run estimate:true first for a free exact price, then the paid call, then poll get_job if the 25 s window elapses. It does not say when to prefer find_person or verify_email instead, so the alternative-selection guidance is incomplete.

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 safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds genuinely new behavioral facts: the call is FREE but rate-limited, and the result includes a 'how sure' confidence measure rather than definitive matches. It stops short of saying what happens on a miss (empty result vs. fuzzy candidate list), which is the one behavior an agent would still want.

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, front-loaded with the cost/rate-limit signal and the return shape before the input recipes. Every clause carries information - the parenthetical '(not Gmail etc.)' and the quoted query example are both load-bearing rather than 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 10-parameter open-world lookup with no output schema, the description supplies the return fields and the main input patterns, which is the bulk of what matters. The residual gaps are the undocumented `eu_only` and `language` switches and the no-match behavior.

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 only 40% across 10 parameters, so the description has to compensate and largely does: it explains which identifiers are interchangeable (name pair + company/domain, LinkedIn URL, work e-mail, or `query`) and warns that `email` must be a work address, not Gmail. Gaps remain for `name` vs. first_name/last_name, `eu_only`, and `language`, none of which are explained anywhere.

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 ('find a person') and enumerates exactly what comes back: name, job title, company, location, LinkedIn profile, and a certainty signal. It also draws a hard boundary against the sibling enrich_records ('No e-mail or phone in the answer'), so an agent can separate the two 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 concrete input recipes: first_name + last_name + company (or domain), a LinkedIn URL, a work e-mail, or a natural-language question in `query` with the example 'CFO of Tink in Berlin'. It names the alternative tool explicitly and the condition that selects it (need e-mail/phone -> enrich_records), which is exactly the routing an agent needs.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value on cost ('FREE (key)') and on output character (records returned in the order sent), but it never explains what the possible 'state' values are or how long results remain retrievable — important gaps for a polling 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?

A single dense sentence with the cost note front-loaded and the return contents enumerated in a sensible order. Some phrasing ('the fields we found') is terse to the point of being slightly ambiguous, but nothing is redundant.

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 and no annotations covering runtime behavior, the description should describe the polling lifecycle and result-retention semantics; it covers the return payload shape and cost but omits state values and failure modes. Adequate to call the tool, incomplete for handling 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 coverage is 50%: the 'language' parameter is documented in the schema, but 'job_id' has no schema description. The description implies job_id identifies an enrich_records job, yet it doesn't say where to obtain it, its format, or what happens with an invalid/expired id, so it only partially compensates.

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 specific resource (an enrich_records job) and what it returns (state, end time, records with found fields), which distinguishes it from siblings like check_records. The verb is implicit rather than stated, but 'the state of an enrich_records job' is concrete enough to identify the operation.

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 through the reference to enrich_records — an agent can infer this is the follow-up call after starting that job. There is no explicit guidance on when to poll, how often, or what to do if the job is still running, and no statement of alternatives.

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 declare readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description adds real behavioral context the annotations do not cover — the 0.3-credit cost per address, the free re-check within 7 days, and the fact that results are returned synchronously for the whole batch. It does not explain partial failures or how errors are surfaced, which keeps it from a 5.

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

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

A single dense sentence with parentheticals; the pricing and the deliverability question are front-loaded. It is efficient, though the nested parentheses make it slightly harder to parse than a two-sentence split would be.

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 burden of describing return values and does so by enumerating the four result states. Combined with cost, caching, and batch-size details, an agent has enough to call this correctly and budget for it.

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 50%: the `language` parameter is documented in the schema but ignored entirely in the description, and the description's 'up to 25 addresses per call' merely repeats the schema's maxItems/maxItems constraint. It does add the useful idea that multiple addresses are answered together, but contributes little else beyond what the schema already encodes.

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

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

The description names a specific verb and resource ('verify e-mail address') and enumerates the four possible outcomes (valid, invalid, catch_all, unknown), which is more than a restatement of the title. None of the siblings (check_records, enrich_records, find_person) touch email deliverability, so an agent can 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?

Usage is implied rather than stated: it is clear you call this when you need deliverability, and the 7-day free-recheck note hints you should not re-verify recently checked addresses. However, there is no explicit when-not guidance, no naming of an alternative tool, and no note on what to do with 'unknown' or 'catch_all' results.

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, so safety is covered; the description adds the non-obvious economics — the call is FREE, part of the payload requires a key, and a key unlocks balance and day budget. This auth/cost tiering is exactly the kind of context annotations cannot express. It does not say whether results are cached or localized beyond the language parameter.

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 dense sentence that front-loads "FREE" and the payoff, with zero filler. The parenthetical about the key is slightly compressed but readable, and the call-to-action closes it cleanly.

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

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

There is no output schema, so the description must carry the return contents — and it does, listing actions, fields, pricing, limits, and key-gated balance. Combined with the free/key distinction, an agent knows what to expect back; only the response shape (structured vs. prose) is left unspecified.

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 single optional parameter has 100% schema coverage including its enum values and a note that it governs the language of `tell_your_user`. The description adds nothing about the language parameter, so the schema does all the work — the baseline 3 for full coverage 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 enumerates exactly what the tool returns — available actions, fillable fields with per-record price, free limits, and (with a key) balance and day budget — which is specific enough to distinguish it from the operational siblings (check_records, enrich_records, find_person). The verb is implicit in the tool name rather than stated, so it falls just short of a 5.

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?

"Call this first if unsure" gives a clear entry-point rule that no sibling offers. It stops short of saying when NOT to call it (e.g. once you already know the action and fields), so there is no explicit exclusion.

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