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

Annotations already disclose that this is a non-readonly, non-idempotent, non-destructive mutation. The description adds material context beyond that: credit consumption per person and the hard dependency on a prior confirm_action call, which an agent cannot infer from annotations alone.

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 compact sentences with no filler, and the primary action is front-loaded before the cost/prerequisite caveats. Slight awkwardness in 'Prepare enriching prospects' but nothing wasteful.

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 and a two-parameter surface, the description covers modes, cost, and the confirm_action dependency, which is most of what an agent needs. It omits what the call returns or how the prepared result is later committed, leaving the confirm_action handoff only half-explained.

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 0%, so the description must carry the load. It does explain the ambiguous 'mode' enum values, which is the most valuable addition, but leaves 'prospect_ids' unexplained (format, source, limits) and says nothing about whether both modes accept the same ID list.

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+resource ('enrich prospects') and names the two operating modes with their enum values, so the agent knows exactly what this tool produces. It is distinguishable from siblings like research_prospects and enroll_prospects, though the 'prepare' framing leaves the two-step flow slightly ambiguous without reading the confirm_action sibling.

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?

Gives the mode-selection condition implicitly (enrich_only vs personalized_line) and an ordering prerequisite ('runs only after confirm_action'), which is genuinely useful. However, it never says when to prefer this over research_prospects or enroll_prospects, nor when to pick each mode.

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