PeopleSearch.im

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the description doesn't need to restate safety. It adds value by disclosing that the call is free and that the balance is tied to the requesting API key, which are behavioral facts not present in annotations. It doesn't describe the response format, but the behavior is simple enough that this is a minor gap.

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

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

The description is two sentences with no filler. The core purpose is front-loaded, followed by cost/safety context and a practical usage tip. Every sentence earns its place.

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

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

For a zero-parameter, read-only tool with strong annotations, the description fully covers what the tool does, what it costs, and when to use it. No output schema exists, but the return value is self-evident from the tool name and description, so nothing critical is missing.

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

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

With zero parameters and 100% schema coverage, there is nothing for the description to clarify. The baseline of 4 applies because the tool requires no parameters and the description correctly implies that no arguments are needed.

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 ('Return'), a clear resource ('current credit balance'), and the auth scope ('for the API key making the request'). This clearly distinguishes it from all sibling tools, which deal with searches, lookups, and email verification rather than account credits.

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 explicitly says when to use this tool: before a large find_people call, to confirm sufficient credits. It also names the specific sibling tool (find_people) and frames the check as a prerequisite, giving the agent concrete decision guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful behavioral context beyond annotations by noting that searching is free and spends no credits, and by stating what the results contain. 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?

Two sentences with no filler: the first states the core purpose and gives a query example, the second delivers the cost-relevant behavior. The most important information is front-loaded.

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

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

For a simple one-parameter search tool, the description covers what the query should look like, what results are returned, and the credit behavior. It does not specify result limits or pagination, but the annotations and minimal schema keep that gap minor.

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

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

The schema has one parameter with 100% description coverage, so the schema already explains the query. The tool description adds a concrete example of valid query phrasing, which helps an agent construct a better natural-language query. This is above the schema-only baseline but not extensive.

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'), a resource ('global company database'), and the natural-language query style, plus the returned fields (industry, size, location, website). It is clearly distinguishable from siblings like lookup_company by emphasizing free-form searching rather than entity lookup.

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

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

The description implies when to use it: when the user has flexible, plain-English criteria, which is reinforced with a concrete example. However, it does not explicitly name sibling alternatives or state when not to use it, such as when looking up a specific known company.

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, the description discloses meaningful behavior: it spends 1 credit, refunds if no email is found, can return a transient 'searching' status requiring a no-charge retry, and never returns personal addresses. This gives the agent essential operational expectations for a live lookup.

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 concise but information-dense, front-loading the core purpose and then covering credit cost, retry semantics, result type, and limitations. Every sentence contributes operational value 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?

For a single-parameter tool with no output schema, the description sufficiently covers input expectations, return semantics, retry behavior, and edge cases. It could be slightly more explicit about output fields beyond emailStatus, but it is complete enough for an agent to invoke and interpret the result 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 100%, but the description adds practical meaning by clarifying the parameter is the person id from find_people or reveal_profile, and that the same id can be reused for the retry. This supplements the schema's simple description without being redundant.

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

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

The description clearly states the tool looks up a verified professional work email for an already-unlocked person, with a specific resource (person id) in scope. It is distinct from sibling tools like verify_email or company search because it targets a person's work email specifically.

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

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

The description gives clear context: use it for a person already unlocked via find_people or reveal_profile, and pass their id. It also explains the retry flow when emailStatus is 'searching'. It does not explicitly name alternatives or exclusions relative to siblings, so it stops 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?

The description discloses the credit cost and refund behavior, which is not captured in the annotations. It also clarifies the output includes confidence levels. It does not contradict the annotations, and while readOnlyHint is false, the description sufficiently explains the resource-affecting aspect via credit spend.

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 compact and front-loaded with the core behavior, followed by usage routing and cost transparency. Every sentence earns its place with no redundancy or 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 single-parameter tool with no output schema, the description fully covers input, output content, confidence levels, use cases, exclusions, alternatives, and credit implications. Nothing essential is missing for an agent 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?

The schema already documents the single parameter at 100% coverage, but the description adds practical meaning: domain is preferred, company name is also accepted, and it provides an example format. This goes beyond the schema's basic 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?

The description clearly identifies the tool's function: given a company domain or name, return role-based email addresses with confidence levels. It explicitly distinguishes itself from named-person lookups by naming find_people and find_linkedin_profile, so an agent can immediately tell what this tool is for.

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 states when to use the tool ('Use this for reaching a company inbox') and when not to ('not a specific named person'), and names the exact alternative tools. It also notes the preferred input format (domain preferred), giving clear operational 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?

The description adds valuable behavioral context beyond the annotations by disclosing the credit cost and refund policy for unmatched results. No contradiction with annotations; readOnlyHint=false is consistent with spending credits.

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 three tightly written sentences: purpose first, then input guidance, then cost/refund behavior. Every sentence earns its place with no repetition or 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 simple lookup tool with no output schema, the description covers inputs, expected output, and cost/refund behavior. It does not detail the exact URL format or what happens on a non-confident match, but it is sufficient for correct invocation.

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 schema already documents each parameter. The description adds extra value by emphasizing that company_or_domain sharply improves match success, which helps agents decide whether to populate an optional field.

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

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

The description clearly states the tool's purpose: finding the LinkedIn profile URL for a named person. It specifies a concrete verb, resource, and input requirement, but it does not explicitly differentiate itself from siblings like lookup_linkedin_profile or reveal_profile.

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: provide first and last name, and use company_or_domain to improve match quality. It does not explicitly state when to prefer this tool over alternative lookup tools, but the intended use case is reasonably clear.

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

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

The description discloses critical behavioral traits: atomic charging (1 credit per newly unlocked person, free for already-owned), automatic broadening reported in broadenedBy, and an out-of-credits error instead of overspending. These go beyond the annotations (readOnlyHint=false, idempotentHint=true) by explaining the financial implications and error handling, giving the agent full transparency for safe autonomous use.

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 well-structured and front-loaded: it starts with the core purpose, then explains the credit model, the email distinction, the warning, and the error behavior. Every sentence adds necessary context with no redundancy, making it concise yet comprehensive.

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

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

Given the tool's complexity (credit spending, two-step workflow with fetch_email, and the absence of an output schema), the description is complete. It explains the return fields (name, title, company, location, LinkedIn URL, id), the credit cost, the broadening behavior, and the error condition, ensuring 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 coverage is 100%, so both parameters are already documented. The description adds value by clarifying that 'count' spends up to that many credits and that 'query' uses the same grammar as people_search, providing semantic context beyond the schema's field descriptions.

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

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

The description clearly states the tool's purpose: 'The list-building tool' that re-runs a people search and unlocks profiles. It explicitly distinguishes itself from people_search by noting it unlocks profiles rather than just searching, making its unique value obvious.

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 explicit when-to-use guidance: it is for unlocking profiles, and explicitly says emails are NOT fetched here, directing the agent to call fetch_email with each id. It also warns about credit spending and advises confirming with the user for large batches, providing clear usage boundaries and 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?

Discloses the 1-credit cost and the refund-on-failure behavior, which is useful operational context beyond the annotations. The wording implies a non-destructive lookup-style call, and nothing contradicts the supplied annotations.

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

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

Two tight sentences: the first covers purpose and output, the second covers cost and failure behavior. No redundant phrasing or 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 one-parameter tool with no output schema, the description fully covers input, output fields, and credit/refund behavior. An agent has enough information to call it correctly and interpret the result.

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 already fully documents the single required parameter with a format and example, so the description adds little beyond what the schema provides. This matches the baseline for high schema coverage.

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?

Uses a specific verb ('turn') and a clear resource ('LinkedIn company URL'), then names the exact output fields: industry, size, location, and website. The company-focused phrasing distinguishes it from profile/email siblings like lookup_linkedin_profile and fetch_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 trigger condition is clear: use this when you have a LinkedIn company URL and need firmographic data. It does not explicitly compare against company_search or state when not to use it, but the intended usage context is unambiguous.

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, the description discloses that the tool spends 2 credits and refunds them if the profile cannot be retrieved, which is important cost-related behavior. It also communicates the return shape. Annotations already indicate readOnlyHint=false and idempotentHint=false, so the description adds meaningful context without contradicting them.

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

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

Two sentences deliver all key information: input, output, and credit cost/refund behavior. There is no filler or redundancy, and the most useful content is front-loaded.

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

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

For a simple one-parameter tool with no output schema, the description is complete: it defines the input, the output fields, and the credit cost/refund behavior. No critical information for calling the tool 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 schema already fully documents the single linkedin_url parameter. The description adds no new parameter-level syntax or constraints beyond what the schema provides, which aligns with the baseline score of 3.

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

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

The description clearly states the verb ('Turn'), the resource ('a LinkedIn profile URL'), and the specific output fields (name, current role/company, location). It does not explicitly distinguish itself from sibling tools like find_linkedin_profile or reveal_profile, which keeps it from 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?

The description implies the right usage context: use this when you already have a LinkedIn profile URL and want structured profile data. It does not state when not to use it or name alternatives, so it stops short of full 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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description goes well beyond them: it reveals that results are masked, each item carries an opaque token, automatic broadening occurs with the broadenedBy field naming dropped filters, and that the true total count is reported. This gives an agent an accurate mental model of the tool's behavior without opening schema or calling it.

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 paragraph but every sentence earns its place: core action, output shape, masked/token behavior, cost/free validation use case, automatic broadening with broadenedBy, and next-step routing to reveal_profile/find_people. It is front-loaded with the main purpose and then layers details in a logical order.

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 takes on the burden of explaining return values and does so thoroughly: sample matching people, true total count, masked preview fields, the opaque token, and the broadenedBy indicator. It also covers cost semantics and downstream tool integration. Nothing an agent needs to decide whether and how to call this tool is missing.

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

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

The schema already provides 100% coverage for both parameters, so the baseline is a 3. The description adds meaningful value by giving a concrete plain-English example ('Heads of Marketing at Series B SaaS in New York') and reminding agents what attributes to include in the query (role, seniority, industry, company stage/size, location). The limit parameter is already well-explained in the schema, so the description doesn't need to repeat it.

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 ('Search'), a clear resource ('global professional database'), and defines the output: a sample of matching people plus total match count, presented as masked previews with tokens. It also distinguishes itself from sibling tools by naming reveal_profile and find_people as the routes to get real identities, so agents can separate this search-and-validate step from the unlock step.

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 explicitly states when to use this tool ('use it to validate that the right people exist before you pay') and provides alternatives: reveal_profile for a single real name via token, and find_people for batch unlocking. It also flags that searching is free and spends no credits, which gives agents a clear decision criterion for choosing this over paid or revealing tools.

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

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

The description goes well beyond annotations by disclosing credit costs, the refund policy for email lookups, idempotent re-reveal behavior, live email latency, and the emailStatus 'searching' retry protocol. This is rich, actionable behavioral context with no contradiction to 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?

Four sentences, front-loaded with the core purpose, and every sentence adds necessary operational detail. There is no redundant restatement of the schema or annotations.

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

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

Even without an output schema, the description lists the returned profile fields, covers the optional email path, credit impact, idempotency, and retry behavior. Given the two-parameter schema and the people_search provenance, nothing critical is missing for correct invocation.

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%, but the description adds essential semantics: where the token comes from, that include_email is processed in the same call, the extra refundable credit, and how to handle the 'searching' email status. These details are not inferable from the schema alone.

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 ('Unlock') and resource ('ONE person') while explicitly tying the input to a people_search result pool. This clearly distinguishes it from sibling tools like people_search, find_people, or fetch_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?

Clear context is given: use it after a people_search returns a token, and set include_email when a verified email is also wanted. It does not explicitly name alternatives or say when not to use this tool, but the prerequisite is unambiguous enough for 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?

The description adds significant behavioral detail beyond annotations: 'Spends 13 credits (this is the single most expensive lookup), refunded automatically if no match is found.' This cost and refund behavior is valuable context not visible in the annotations, and it is consistent with idempotentHint=false and 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 tightly written sentences with no filler. The main purpose is front-loaded, followed by usage qualification and the cost/refund detail. Every sentence earns its place.

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

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

For a one-parameter tool with no output schema, the description is complete: it states what the tool returns ('real person behind it and their LinkedIn profile'), when it works, and what happens on failure (automatic refund). An agent has enough context 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?

The schema already covers the email parameter fully with an example. The description adds extra semantics by calling it a 'professional email address' and explaining the work-email/free-mailbox distinction, which helps the agent choose valid inputs and set expectations.

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 ('Turn') and states the resource ('professional email address') and the result ('real person behind it and their LinkedIn profile'), making the tool's purpose concrete. However, it does not explicitly distinguish itself from overlapping siblings like find_linkedin_profile or reveal_profile.

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 provides clear usage context: 'Best for work emails' and warns that 'free-mailbox addresses often have no public profile to match,' which serves as a when-to-use and when-not-to-use signal. It does not name sibling alternatives for routing, but the work-email versus free-mailbox guidance is actionable.

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 annotations, the description reveals important behaviors: it spends 1 credit, refunds if no verdict can be reached, and sends nothing. This adds value beyond readOnlyHint being false and clarifies side effects and cost, which are essential for an agent to use the tool correctly.

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 three concise sentences, each earning its place: purpose, outcome, and side effect. It is front-loaded with the core question and avoids unnecessary 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 single-parameter tool with no output schema, the description is complete. It explains the verdict values, the credit cost, the refund behavior, and the fact that nothing is sent. An agent has enough information to decide whether and how to invoke this tool.

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

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

The only parameter is already fully described in the schema with a clear example. The tool description does not add extra meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Check') and resource ('whether an email address exists and is safe to send to'), and clarifies its unique role with 'before it bounces' and 'without sending anything.' This distinguishes it clearly from sibling tools like reverse_email_lookup, which do not focus on deliverability.

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

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

The description provides clear context for when to use the tool: before sending an email to avoid bounces. It does not explicitly name alternatives or exclusion criteria, but the context is strong enough for an agent to infer the appropriate use case.

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