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

Annotations only say readOnly=false/destructive=true; the description goes well beyond by explaining that stages are replaced as a WHOLE list, that leads on dropped stages must be remapped, that a diff of stages added/removed/changed and leads moved comes back, and that dry_run previews it. The full confirmation protocol (status='confirmation_required', action_id, plan_token, write only after confirm_action) is spelled out, which is exactly the evil the destructiveHint flag warns about.

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?

Front-loaded with the core action, then keyed parameter notes, then the confirmation rule placed last where it matters most. It is dense and slightly restates schema shape inline, but almost every clause carries semantics an agent needs for a destructive whole-list replacement.

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 9-parameter nested destructive tool with no output schema, it supplies the return shape (the diff), the default behavior when transitions are omitted, the remap obligation, and the deferred-write flow. Only the secondary flags archived and is_default lack any explanation, a minor gap against this complexity.

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?

With 0% schema description coverage the description carries the burden and mostly succeeds: it documents pipeline/name/stages subfields, goal_per_month, remap, dry_run, and decodes the transition sentinels ('*' = any, 'previous' = the stage held before) plus the default transition set when omitted. It leaves sla_days, archived, and is_default entirely unexplained, so it does not quite close the gap.

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 — 'Create or redefine one of the workspace's lead pipelines' — and immediately bounds the scope with the 'inbound' pipeline exclusion and the whole-list replacement semantics. An agent can tell this apart from the read-side pipeline tooling without opening the schema.

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 clear conditions: use remap when the new stage list drops a stage that still holds leads (otherwise remap_required), use dry_run=true to preview, and expect the call to route through confirm_action. It names an explicit exclusion ('inbound' cannot be redefined) but never points at crm_pipeline_get for inspecting the current definition before redefining.

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