Deeplead

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

Annotations mark this non-read-only but non-destructive; the description corroborates with the saveToContacts write side effect and goes further by disclosing the credit model (1 credit per business with email/phone, 0.5 without) and page size. It omits auth requirements and whether the contacts write is reversible.

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?

Four short sentences, each front-loaded with the most decision-relevant facts (source, scale, cost, side effect). The '30 per page' fact is duplicated in the schema, a minor 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?

With an output schema present, return values need no explanation, and the description supplies the cost model, pagination, and contacts side effect. It stops short of noting the 100-page cap or any authentication/credit-balance prerequisites.

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 all 10 parameters are documented in the schema itself, establishing a baseline of 3. The description adds only the credit distinction tied to email/phone presence and the 30-per-page limit, both of which largely restate schema details.

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 (Search) plus resource (local businesses from Google Business Profiles) and quantifies the corpus (23M+). It is clearly distinguishable from siblings like organizations_search and persons_search, which cover different entity types.

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 resource description, but there is no explicit when-to-use or when-not guidance and no alternatives named among the sibling search tools. An agent must infer that this is the local-business search rather than organizations_search.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world write. The description adds behavior annotations do not carry: it is free (useful given the credits_get sibling) and it is idempotent-by-matching ('matched and kept, never duplicated'). It does not describe partial-failure or per-item error behavior for batch submissions.

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, action and scope first, then the two behavioral facts that actually matter (cost, dedup). No filler whatsoever.

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?

Output schema and annotations carry the return-shape and safety burden, and the description covers the two facts structured fields cannot express. Only the batch semantics (up to 1000 items, partial failures) are left unaddressed.

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 array item field set, min/max items, and the organizationId provenance note are all documented in the schema. The description adds nothing about parameter format, 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 verb (Save) and resource (contacts or organizations), and the phrase 'your own' signals it differs from the lookup/search siblings. It is clear, but it never names an alternative tool to contrast against, so differentiation is inferred 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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative among siblings such as organizations_search or contacts_list. The word 'own' faintly implies this is for user-supplied contacts rather than enriched data, but the agent must infer that.

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 mark the tool as read-only and non-destructive. The description adds a meaningful behavioral guarantee: a stable order across pages, which is essential for correct cursor-based pagination. It does not mention auth or rate limits, but for a simple read-only list with an output schema, the added context is sufficient.

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 a single, front-loaded sentence with no filler. It packs the verb, resource, stable-order guarantee, and pagination method into a compact form, making it easy for an agent to parse quickly.

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 two-parameter list endpoint with complete schema descriptions, read-only annotations, and an output schema, the description covers the essential usage and pagination behavior. Return values are handled by the output schema, so the only real omission is explicit alternative routing, which is already captured in the usage_guidelines dimension.

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?

Both parameters are already fully documented in the schema with 100% coverage: limit has default/min/max, and before is defined as 'The nextBefore of the previous page.' The description merely echoes the before behavior and adds no new parameter meaning 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?

Tautological: description restates name/title.

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

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

It tells the agent this is for listing contacts and explains the pagination mechanism ('page with nextBefore'), which is useful for paging through results. However, it never states when to prefer this tool over contacts_create or the search-based siblings, nor does it give any exclusion conditions.

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 the safety profile is covered. The description adds no extra behavioral context such as snapshot semantics, units, or response specifics, but it does not contradict 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?

Three words with no filler, but the phrase is under-specified for a definition: it is a tautological noun phrase rather than an instructive sentence. Conciseness is fine, but the structure lacks a verb or usage statement.

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, read-only balance lookup with an output schema and safety annotations, the description provides enough to understand what will be returned. It is not a complex workflow, so the missing verb and usage note are smaller 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?

The input schema has zero parameters, so there are no parameter semantics to document. The baseline of 4 applies; no compensation is needed from the description.

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?

Tautological: description restates name/title.

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 sentence or phrase explains when to call this tool or when to prefer an alternative. The only implied context is from the title/name, and the sibling tools are unrelated categories, so the description gives no routing 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 establish that this is a non-read-only, non-destructive, closed-world operation. The description adds materially beyond that: a 25-credit charge, a 2-5 minute reporting window, and a 60-minute test expiry. Costs and timing are exactly the behavioral context annotations cannot convey.

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?

Purpose is front-loaded and every sentence carries information (procedure, polling cadence, timing, cost). The middle sentence is long and run-on, packing three separate instructions together, so structure is efficient but not maximally scannable.

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 spelled out, and the description still covers the full usage loop, expected latency, expiry, and credit cost. Nothing an agent needs to invoke this 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?

With zero declared parameters, the baseline is 4. The description goes further by naming the operative inputs (seedEmails, testId) and their intended usage, though these names do not appear in the empty schema, which creates a mild mismatch rather than a clarifying one.

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 ('Start an inbox placement test for a mailbox you send from') and immediately contrasts with the sibling 'deliverability_get_test', which it positions as the polling counterpart. An agent can distinguish the two without opening either schema.

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

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

Explicitly prescribes the workflow: send one email from the mailbox under test to every address in seedEmails with testId in the body, then poll deliverability_get_test about once per minute. It names the alternative tool and the exact trigger for using it, leaving nothing 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 already declare readOnly=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds beyond that: the operation is asynchronous and must be polled, a 'waiting' status exists, and score is only populated once the test is completed. It doesn't quantify rate limits or failure modes, keeping it at a strong 4 rather than 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?

Purpose and polling cadence are front-loaded in the first sentence; the remaining two sentences explain the placement/score/rspamd fields compactly. Some of that return-value detail is arguably duplicated by the output schema, but it is readable and not padded.

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-param read tool with an output schema and full annotation coverage, the description carries the load that structured fields cannot: async polling behavior and status semantics. It is essentially complete, missing only explicit mention that testId originates from deliverability_create_test (which the schema does state).

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 parameter with 100% schema description coverage, including the format pattern and the pointer back to deliverability_create_test. The description adds no additional parameter meaning, so the baseline 3 for schema-covered params 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 scopes the resource precisely as the per-seed-mailbox placement results of a deliverability test, which an agent can separate from deliverability_create_test by name and by the 'where the email landed' framing. It is slightly output-oriented (describing what the result looks like rather than 'get the test results for testId'), so it stops short of a crisp verb+resource statement.

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 concrete operational guidance ('Poll about once a minute while status is waiting'), which tells the agent how to consume the async result rather than just what it returns. It never states prerequisites or exclusions, but the sibling create_test is the only natural alternative and no when-not guidance is needed here.

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 readOnly/openWorld/destructive flags, so the credit-charging rule (0.5 credits, billed only on a successful match) is genuinely additive context an agent needs to avoid surprise spend. It does not, however, discuss rate limits, lookup latency, or what happens on a miss beyond the billing point.

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, zero filler: purpose first, return payload second, cost caveat last. Every sentence carries information the agent would otherwise lack.

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 tool with an output schema, the description needn't restate return fields, and the cost model is disclosed. The only shortfall is the absence of routing guidance against the other organizations_* siblings.

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?

Only one parameter and schema description coverage is 100% (the schema already gives the "stripe.com" example and minLength), so the baseline of 3 applies. The description adds no syntax or normalization guidance beyond what the schema supplies.

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 (enrich) applied to a specific resource (a company, keyed by domain) and even names the payload returned (firmographics, socials, website data). This clearly separates it from the sibling organizations_search, which retrieves rather than enriches.

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 usage is implied — you call it when you already hold a company domain and want enrichment — but there is no explicit when-to-use versus the sibling organizations_search or organizations_find_decision_maker, and no exclusions or prerequisites 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 only say readOnlyHint=false, openWorldHint=true, destructiveHint=false — enough to signal external lookup but nothing about cost or timing. The description supplies both: a conditional 2-credit charge that fires only on success, and a multi-minute latency window. These are exactly the behaviors an agent needs before committing to a call, and nothing contradicts the annotations (a credit-consuming finder is consistent with readOnlyHint=false).

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, each doing distinct work: what it returns, what it costs, how long it takes. The payoff statement is front-loaded and there is 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?

With an output schema present, return-shape explanation is unnecessary, and one fully documented parameter needs little prose. The description covers the two non-obvious facts an agent must weigh — cost and latency — but says nothing about the no-result case (e.g., whether credits are untouched and what the response looks like when no decision maker 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?

There is a single parameter at 100% schema description coverage ('Company ID returned by organization search or enrichment'), so the schema already carries the meaning. The description adds no format, sourcing, or validation detail for organizationId, which is the correct baseline 3 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 and resource plus a meaningful qualifier: finding the decision maker of an organization, with the email verified. That is far more specific than a generic 'look up organization', though it never names how it differs from near neighbors like organizations_enrich or persons_find_email.

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 scenario where this applies (you have an organizationId and want a decision-maker contact) is implied rather than stated, and no alternative tool is named as the wrong or right choice. The cost and latency hints ('charges 2 credits', 'a few minutes') do help an agent decide whether to invoke it, which lifts this above pure silence.

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 (unusual for a search tool) and the description supplies the missing context: the call consumes credits proportional to organizations returned. It also discloses the free count-only mode, which is real behavioral information not derivable from annotations or schema. It stops short of describing result ordering, pagination limits, or truncation behavior.

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 with zero filler; the capability statement comes first and the cost/count caveat follows immediately. Nothing is padded or 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?

An output schema exists and the schemas are fully documented, so the description needn't explain return values. For an 18-parameter search tool it is still thin: it never says how the filters combine (e.g. domains with query), nor whether pagination beyond offset 10000 is impossible. 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% and every parameter, including the limit=0 trick, is documented in the schema itself. The description adds no syntax or format detail beyond what the schema already provides, 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 (search/look up) and resource (organizations), and distinguishes two modes: text search versus domain lookup. It does not, however, name or contrast itself against obvious siblings such as organizations_enrich or organizations_find_decision_maker, so an agent must 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?

The cost model (0.5 credits per returned organization) and the 'limit 0 returns only totalCount, free' tip imply a cost-aware usage pattern, which is genuinely useful guidance. However, there is no explicit statement of when to use this tool instead of organizations_enrich, organizations_find_decision_maker, or businesses_search.

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 set readOnlyHint=false, destructiveHint=false, openWorldHint=false but say nothing about billing. The description adds a concrete and important behavioral fact: "Charges 1 credit only when an email is found." That conditional cost model is exactly the kind of detail annotations cannot convey. Auth requirements and rate limits are still unstated.

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, fully front-loaded: capability first, cost model second. No filler, no restated schema detail.

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 explained, and the billing note covers the main hidden behavior. What remains thin is any guidance on which input combination to prefer and what happens on a miss, which matters for a tool whose cost is conditional.

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 each parameter (name, domain, linkedin) is already documented with format examples. The description only restates the two combination modes, adding no syntax or constraint detail 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 and resource ("Find a person's work email") and names the two accepted input modes, which is more than a title restatement. It does not, however, distinguish itself from near-siblings like persons_lookup or persons_search, so an agent must still infer which lookup tool to pick.

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 the two valid input paths (LinkedIn URL, or name plus domain), which implies usage. It never states when to prefer this over persons_lookup, persons_find_phone, or organizations_find_decision_maker, and gives no exclusions or prerequisites.

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?

Discloses the billing rule ('charges 2 credits only when a phone number is found'), which is genuine behavioral context the annotations do not carry — readOnlyHint=false alone would not tell an agent about cost or conditional charging. It does not mention rate limits or auth requirements, but the credit policy is the material trait 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?

Three short sentences, front-loaded with the action and inputs, then the scope limit, then the cost. Every sentence carries information an agent needs; nothing is padded.

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 no explanation, and the description covers scope, inputs, and cost. The only minor omission is what a successful result implies for follow-up (e.g. coverage/likelihood limits), but nothing essential to correct invocation 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 all four parameters are already documented, including the constraint that name requires a domain. The description restates the accepted input combinations but adds no format or precedence detail 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 ('Find a person's phone number') and enumerates the three accepted lookup keys, which cleanly separates it from siblings like persons_find_email or persons_lookup. The scope qualifier ('professional contacts only') further pins down what the tool returns.

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 an explicit when-not boundary: professional/role-based contacts, not private individuals. It does not name the sibling alternative (persons_find_email) for when a phone is not the target, so the routing guidance is clear but not fully comparative.

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 genuinely useful behavior beyond the annotations: the credit model ('charges 1 credit only when the person is found with an email or phone') and the side effect that saveToContacts persists the person to contacts, which explains why readOnlyHint is false despite the read-like name. It stays silent on rate limits and result freshness, so not 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?

Four tight sentences with the purpose front-loaded, followed by return contents, scope constraint, and billing behavior. No sentence is redundant with the name/title and nothing is padded.

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, the brief return summary is sufficient, and the billing plus scope caveats cover the main decision-relevant facts. It could still specify which standalone identifiers (email alone, LinkedIn alone) are valid without a domain, but the core is 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?

Schema description coverage is 100%, so the schema already documents all five parameters including the 'needs domain' constraint on name. The description only echoes the identifier list and adds a note on saveToContacts, so baseline 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?

States a specific verb (look up), cardinality (one person), and the exact identifiers accepted (LinkedIn URL, email, name + company domain). This distinguishes it from plural siblings like persons_search and the narrower persons_find_email/persons_find_phone without the agent needing to open 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?

Provides a clear scope boundary — 'professional contacts only: people in their role at a company, not private individuals' — which tells the agent when this tool will fail. It does not, however, route the agent among alternatives such as persons_search for broader matching, leaving sibling 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?

Annotations already declare a non-read-only, non-open-world, non-destructive profile, so the bar is lower. The description nonetheless adds substantive context beyond them: 1 credit per returned person, refunds for already-stored contacts, a free count via limit 0, and the saveToContacts side effect on the contacts store.

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?

Six dense sentences, front-loaded with the core verb+resource+scope before cost and pagination details. Every sentence carries information, though the limit/offset and saveToContacts notes partly duplicate the schema and could 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?

With an output schema present (so return values need not be explained) and 100% schema coverage, the description still covers purpose, scope, cost, pagination, and the saveToContacts side effect. It omits auth/rate-limit context, but for a search tool of this complexity it is largely 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?

Schema description coverage is 100%, so the schema already documents all 26 parameters; this is the baseline 3. The description echoes a few of them (limit 0 free count, nextOffset pagination, saveToContacts storage) without adding syntax or format detail the schema lacks.

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 ('Search persons with their emails and phones') and adds a scope restriction ('professional contacts only ... not private individuals'). It distinguishes the domain from a likely private-individual lookup sibling, but does not name an alternative tool, so it stops short of full sibling differentiation.

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 usage condition and an implicit exclusion ('people in their role at a company, not private individuals'), plus cost-aware guidance ('limit 0 returns only totalCount, free'). It does not explicitly route the agent to an alternative sibling when the exclusion applies, so the guidance is clear but not complete.

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