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

Goes well beyond the annotations by disclosing the exact mutation scope ('Only the step status changes. Labels, links, and positions stay the same.'), the reversibility mechanism ('A version is saved first, so restore_version can undo it'), and the cost ('Uses one AI build or edit from the plan'). These are the details an agent needs before a non-readOnly, non-idempotent call.

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-loads the action and its two modes, then uses a compact examples list and short declarative sentences about side effects. No sentence is filler.

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, the description still explains what changes, what is preserved, and how to reverse it, which covers the essential call-time unknowns. Minor gap: it doesn't say what the call returns (e.g., a new version id) or how to review the applied marks.

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 100%, so the baseline is 3, but the description adds real meaning about the 'rule' parameter by showing three example rule phrasings, clarifying its expressive range. The 'flow_id' parameter is left to the schema.

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 ('Mark steps of a flow yellow (warning) or red (error) from a plain-language rule, or clear the marks'), including the clearing variant. An agent can distinguish this from edit_flow or update_nodes without opening either 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?

Concrete example rules ('flag every step that waits more than a day', 'mark steps with no owner red', 'clear all highlights') make the usage context vivid, and it points to restore_version for undo. It does not, however, explicitly say when to prefer this over edit_flow or update_nodes, so there's no exclusion guidance.

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