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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add beyond that, and it does: it discloses the full status lifecycle, that needs_input means the search stopped finding new prospects and is asking whether to widen, the ordering convention ('named people first'), and the cost signal ('Free'). It does not mention pagination behavior, which is the notable remaining 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?

It is front-loaded with the resource and every clause carries information — no filler. But it is a single run-on sentence built from stacked colons and appositives, which makes the status definitions and the return-field list harder to scan than a two- or three-sentence structure would.

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 must describe the return shape and it does so thoroughly, including per-prospect fields and the CRM-saved flag. What is missing is pagination semantics for limit/offset and any statement about whether the prospect list is truncated, which matters for a polling tool that can return large result sets.

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%: search_id is documented in the schema, but limit (default 25, max 100) and offset (default 0) carry no description anywhere. The description adds no meaning for these two parameters and never signals that results are paged, so an agent must guess whether the returned prospect list is complete or a first page.

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 resource and retrieval mode ('A prospect search by id') and enumerates exactly what comes back: status, progress, question plus brief, and the prospects found with their company/person/title/email verification/phone/CRM-save flag. That is enough to distinguish it from prospects_list (list all) and prospects_find (start a search), though it never names a sibling, so the differentiation is inferred from content rather than stated.

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?

Usage is implied rather than stated: the status vocabulary (running, needs_input, completed, stopped, failed) and the 'question and the brief as it stands when it asks one' hints this is the polling/inspection tool for a search, and the schema's search_id text ties it to prospects_find. There is no explicit when-to-use/when-not and no mention of prospects_list or prospects_answer as alternatives when input is needed.

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