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

Despite annotations covering mutation/idempotency, the description adds substantial context: workspace-wide sharing, source attribution defaults (automated vs human), dedup behavior returning already: true, stage side effects (shortlisted also shortlists, contacted sets contacted date), and the fact that replaces removes the old outcome but keeps it in history. The last point usefully qualifies destructiveHint=false by explaining what is actually lost.

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?

Dense but front-loaded: what to record first, then guardrails, then effects, then corrections, then defaults. Every sentence carries a distinct fact and none repeat structured fields verbatim.

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?

Even without an output schema, the description covers the important return behavior (already: true on repeats), mutation side effects, attribution, and correction flow. An agent has everything needed to call it correctly.

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?

At 71% schema coverage, the description still adds meaning beyond the schema: the side effects of specific stage values, the semantics of replaces (an active outcome of theirs in this role, sourced from get_outcomes), the default for happened_at, and the human-vs-automated distinction for source.

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 and resource ('Record what happened with someone in a role') and enumerates the exact value space of outcomes. It is clearly distinguishable from siblings like decide (which it names as an equivalent for the shortlist side effect), remove_outcome, and get_outcomes.

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 an explicit usage constraint ('Only record what the user tells you happened, never a guess'), names the alternative tool for corrections ('pass its id as replaces (from get_outcomes)'), and tells the agent that shortlisted is equivalent to decide for that sub-action.

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