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

Annotations declare readOnlyHint=false, openWorldHint=true and idempotentHint=true, but the description goes well beyond them: credit accounting ('one lookup is spent only when Nameclick finds an email address on record'), caching ('once per person for good'), plan gating ('a personal address such as Gmail needs a paid plan'), withheld-result signaling ('the card says when one is held back'), and free failure modes ('a miss, a record with no email or an ambiguous identity costs nothing'). That is exactly the side-effect and cost disclosure an agent needs before spending a metered call.

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

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

The cost and plan-gating information is front-loaded and valuable, but the first sentence is a long run-on built from nested appositives ('...a name selected on a page with the text around it, a profile on X or a YouTube channel included') that is hard to parse at a glance. The dense semicolon-chained clause about credits, paid plans, held-back cards and free misses could be split without losing content.

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 seven-parameter open-world lookup with nested objects, the description covers purpose, input resolution strategy, metering and plan constraints, and failure costs, while an output schema already exists so return structure need not be specified (the brief note about roles, location, links and company data is a bonus). An agent has everything needed to call it correctly and predict what a call will cost.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds genuine meaning on top: it maps each narrative input form to a parameter family and clarifies that a page selection uses 'the text around it' and that an X or YouTube profile is included. It also repeats the paid-plan caveat for personal email addresses, reinforcing the schema note. Nothing is added about how company vs. domain interact when both are supplied.

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 opening sentence names a specific verb and resource — find a person's identity and email address — and enumerates the accepted input forms (LinkedIn URL, email, GitHub login, name+company/domain, page selection, X/YouTube profile). What's missing is differentiation from the siblings get_contact and get_services, which are never mentioned, so the agent must infer that 'find' produces a lookup while 'get' retrieves an existing record.

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 real usage constraints: 'Resolve the person first: use the profile or employer the user gave you, never a guess' and 'Look up the person the user asked about, never people in bulk.' These tell the agent what inputs to prefer and explicitly rule out bulk usage. It stops short of naming an alternative tool or stating when get_contact would be the better call instead.

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