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

Beyond the annotations it discloses the credit cost model (1 on confident match, 0 on no match or already-licensed record), which independently corroborates idempotentHint, plus the confirmation/approval-token requirement, the required enrich:write scope, and the exact error names returned (confirmation-required, agent-budget-exceeded). It also surfaces the PECR audience restriction and lawful basis, which materially affect what comes back.

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 cost are front-loaded and virtually every clause carries new information. It is a dense single block, though, with the compliance/PECR sentence appended at the end, so scanning is harder than it needs to be.

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

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

For a credit-spending, confirmation-gated enrichment call the description covers prerequisites (auth scope, approval token or agent key), cost and no-charge conditions, failure responses, and compliance constraints on the returned audience. With an output schema available it correctly does not waste space describing return shape beyond naming credits_charged and balance.

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

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

Schema coverage is only 29%, but the description compensates by explaining the anyOf matching contract in prose — email alone, or first_name + last_name plus exactly one of company_name/company_number/domain — and by explaining what the confirmation_token is and where it comes from. It still leaves some parameter behavior (e.g. the corporate-subscriber toggle mentioned in prose but absent from the schema) ambiguous.

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 gives a concrete verb and resource ("Returns the full record for one known person") plus the exact matching keys (email, or name with company name/number/domain). It also scopes the tool to a single named person, which separates it from bulk/audience siblings such as compile_audience or preview_records.

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 the use case plainly ("use it for a single named person") and names create_order as the analogous approval-flow tool, plus a concrete alternative path (agent key with allowed_tools) and the failure modes that route the caller away. It does not explicitly contrast against lookup_company or preview_records, so the when-not is left partly implicit.

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