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

Beyond the annotations (which already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true), the description adds genuinely useful economics: 5 credits reserved per contact with refunds for undelivered contacts, and confirmation that a repeated idempotencyKey returns the first result. However, for an explicitly destructive, open-world, asynchronously 'queued' operation, it omits the most important behavioural detail: that results arrive later and must be fetched via a separate request/readiness 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?

Three compact sentences, front-loaded with what the tool does, followed by cost and availability, then retry behaviour. Dense and mostly waste-free, though the credit-refund clause could be slightly tightened.

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?

The tool is a nested-body, destructive, open-world async request with no output schema and low schema coverage, so the description carries a heavy burden. It covers cost, readiness gating, and idempotency, but leaves the agent guessing how to retrieve the queued contacts and which of the title-selection fields to supply.

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 only 33% (only idempotencyKey is documented), so the description must compensate. It maps partially onto the body: '1-10 contacts' explains quantity, and 'role group or titles' explains role_group / exact_title / title_any_of, while the retry sentence explains idempotencyKey behaviour. It says nothing about the phone/email toggles (include_phone, require_email, require_phone), whether the title fields are mutually exclusive, or that params.id is the pipeline company UUID.

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 gives a specific verb and resource ('Queues research to find 1-10 contacts') plus scope constraints (role group or titles, at a pipeline company), which is far more informative than the title alone. It does not explicitly differentiate itself from plausible neighbours such as createRequest or createContactTask, so an agent must still infer which request-style 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?

It names a precondition check by pointing at getContactReadiness ('shows whether it is available for this account'), which gives the agent a concrete gating step before invoking. It also covers retry semantics via idempotencyKey. It stops short of stating when NOT to use it, or when a sibling like getContactRequest/RentRequest flow is the better choice.

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