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

With no annotations, the description carries the full burden and does well: it discloses the data source (addresses on record for current staff), the returned evidence fields, privacy behavior ('No address is returned'), and billing nuances. It does not discuss authentication, rate limits, or error behavior, but the key behavioral traits are present.

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 front-loaded with purpose, then output fields, then usage, then pricing. Every sentence adds useful information, and the compact list of returned evidence fields is efficient.

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 needs to explain return values; it does so by naming pattern, confirmations, agreement, coverage, other patterns, and masked samples. It also covers privacy and pricing, though it could say more about response shape or partial-cap 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 description coverage is 100%, so all three parameters are already documented in the schema. The description adds some cost context tied to domains and confirmed patterns, but it does not explain sampleLimit or the maxChargeUsd stopping behavior beyond what the schema already provides.

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 and resource: inferring how a company writes work email addresses from staff addresses on record. It also distinguishes the output from an actual email lookup by saying 'No address is returned' and gives example patterns, so an agent can tell what this tool is for without opening the 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?

It gives a clear usage cue: 'Use before guessing an address from a name.' It also explains charging behavior for confirmed versus weak/unknown/shared-hosting domains, but it does not name sibling alternatives such as find_email_by_linkedin_url or state when not to use 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?

No annotations exist, so the description carries the full burden, and it does real work: pricing ($3.20 per 1,000 people), the free no-match case, and the crucial limitation that emails are not included. It still omits rate limits, auth requirements, and whether the LinkedIn URL field is always populated.

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 sentences, no filler. Scope and returned fields come first, then the sequencing cue, then cost and the email hand-off – each sentence adds information an agent needs before calling.

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 annotations and no output schema, the description compensates by listing returned fields, disclosing cost and the spend cap concept, and flagging the email gap. Minor omissions remain: no mention of result volume/pagination behavior or what happens when a domain is invalid.

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 real semantics beyond the schema by explaining the pricing model that gives maxChargeUsd its purpose and by naming the linkedinUrl output that feeds the email tool. It does not clarify roles/titleKeywords interplay or default role behavior beyond what the schema 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?

States a specific verb and resource ('Founders, C-level, VPs and directors at the given companies') and enumerates the returned fields (name, title, seniority, LinkedIn URL, email-on-record flag), so the agent knows exactly what comes back. The role scope distinguishes it from broad people-search siblings such as search_people and find_new_hires.

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 explicit sequencing ('Use after you have target domains') and routes the follow-up step: pass linkedinUrl values to find_email_by_linkedin_url. It does not explicitly say when to prefer this over search_people or find_new_hires, so it stops short of full sibling differentiation.

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 no annotations, the description carries the burden and does real work: it discloses data provenance ("read from a database, not guessed and not scraped"), the cost model ($8 per 1,000 matched profiles, unmatched free), and implicitly that rows can come back without an address. It does not explicitly state read-only/no-side-effects, auth requirements, or rate/throughput limits, so not a full 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?

Three tight sentences: capability and returned fields first, provenance and cost next, disambiguation last. No redundancy with the title, and nothing that could be cut without losing 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?

There is no output schema, so the description compensates by enumerating the returned attributes, and it covers provenance, cost, and the sibling alternative for a 3-parameter batch lookup. An agent has everything needed to choose and call 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 all three parameters (profileUrls, maxChargeUsd, includePersonalEmails) are already documented, including the default and the charge-cap behavior. The description adds context about what addresses are returned but does not clarify includePersonalEmails' effect on the output beyond the schema text; 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 first sentence names a specific verb+resource (retrieve the email address on record per LinkedIn profile URL or handle) and enumerates the returned fields (best address, type, all work addresses, name, title, employer). It is clearly distinguishable from search_people and the other siblings, which are lookups by criteria or firmographic pivots.

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?

"Use for a list the user already has; for people search by criteria use search_people" gives an explicit when-to-use plus the alternative and the condition that selects it. The pricing sentence (charged only for profiles with an address) further signals the batch-lookup use case.

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 no annotations, the description carries the burden and does so well: it discloses the per-company price, that seeds, duplicates and unresolved seeds are free, and that this is a paid enrichment call. It stops short of stating latency, whether results are ordered/deduplicated across seeds, or what a failed seed returns, so it is strong but not exhaustive.

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 what the tool returns, then use case, then cost model, then the exclusion, in four tight sentences. No filler, and the pricing detail is placed where an agent weighing spend will read it.

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?

No output schema exists, and the description compensates by enumerating the returned fields, including the explicit matchedOn string that explains why each row matched. A minor gap remains around cross-seed deduplication and result ordering for a 6-parameter batch call, but nothing required to invoke 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 coverage is 100%, so every parameter is already documented, including defaults and caps. The description only restates the default matching behavior (same industry, same country, similar headcount) and adds no syntax or format guidance beyond the schema — the baseline 3 for fully-covered schemas.

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

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

States a specific verb+resource (find lookalike companies for seed domains) plus the default matching dimensions (industry, country, headcount) and the exact fields returned. The closing exclusion sentence separates it from a filter-based company search, which no sibling here offers, so an agent can route it confidently.

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 use case ("expand best customers into target accounts") and an explicit non-use case ("Not for company search by filters without a seed"). Neither the when nor the when-not is left to inference.

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

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

With no annotations, the description carries the full burden and does disclose the most consequential trait: per-result billing ($3.20 per 1,000) with free companies when no new hires are found. It doesn't cover auth requirements, rate limits, or pagination behavior, which keeps it below 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?

Three tight sentences with zero filler: output fields first, use case second, cost and exclusions last. Nothing is redundant with the name or title.

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 9-parameter tool with no annotations and no output schema, the description compensates well by listing returned fields and explaining the billing model. It leaves default behaviors (default 6-month window, default 200 rows) to the schema, so it is very good but not exhaustive.

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 (since vs sinceMonths precedence, country codes, title matching, maxChargeUsd cap behavior, per-company caps) is already documented in the schema. The description adds no parameter-level detail beyond reinforcing the concept of a company list, 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?

Specific verb+resource ('who recently joined the given companies') plus an explicit enumeration of the returned fields (name, new title, start month, seniority, LinkedIn URL, previous employer/title). This clearly separates it from siblings like search_people and find_decision_makers, which don't speak to recency of joining.

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?

States the intended use case ('job-change and hiring signals on an account list') and gives two explicit exclusions: not for people who left (route to former employees) and not for job postings. When-to-use and when-not-to-use are both present.

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 no annotations, the description carries the full behavioural burden and does well: it discloses free versus paid modes, per-row pricing, the required user confirmation before paid results, and that no live LinkedIn pages are read. It leaves out some operational details such as rate limits or auth requirements.

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

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

The description is front-loaded with purpose, then immediately clarifies the three modes and the safe workflow. Every sentence earns its place, including the pricing caveat and the LinkedIn data-source note.

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 13-parameter search tool with no output schema, the description explains the key mode outputs, pricing, and usage workflow, which is substantial. It is not fully complete because several filter parameters are left to the schema, and some of those are themselves undocumented.

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 77%, so the schema already documents most parameters. The description adds useful meaning for the mode parameter and the return fields, but it does not compensate for undescribed filter parameters such as maxPerCompany or employee count bounds.

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: finding people matching an ideal customer profile, with modes that clarify the operation. It is clear on its own, but it does not explicitly distinguish itself from overlapping siblings such as find_decision_makers or find_new_hires.

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 strong mode-level guidance: count first, market for a free breakdown, and ask the user before switching to paid people mode. It does not, however, explain when to choose this tool over sibling tools like find_decision_makers.

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