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

Annotations already mark the operation destructive, and the description adds valuable nuance: the published funnel remains live until the user publishes, replacing is all-or-nothing at the draft level, optimistic concurrency yields 409 on stale draft_version, and the response reports affected blocks and a check. No contradiction with annotations.

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 dense sentences cover the action, the concurrency model, the recovery path, and the response contents with no filler. The core verb and object are front-loaded before details.

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 destructive mutation with no output schema, it includes a response hint and a 409 retry path, which is good. But the definition does not describe how to build the graph object or where to obtain its shape, and it leaves the optional name parameter unexplained, so the agent is not fully equipped to call the tool 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?

Schema description coverage is 0%, so the prose must carry parameter meaning. It explains draft_version's role and 409 behavior, and 'replace entirely' implies graph is the full replacement object. However, funnel_id is only implicit, optional name is not mentioned, and the internal structure of graph is left undefined.

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 opens with 'Заменить черновик воронки целиком', a specific verb + resource statement: replace the entire funnel draft. It even clarifies the live-funnel scenario, which distinguishes this update/replace operation from sibling create_funnel_draft.

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 gives a concrete workflow: take draft_version from get_funnel, call this tool, and on a 409 re-read the funnel. It also explains the draft-vs-published semantics so an agent knows editing here won't affect live users. It does not explicitly say when to prefer create_funnel_draft over this tool, so alternatives are not fully spelled out.

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