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

Annotations only give destructiveHint/readOnlyHint/idempotentHint; the description adds far more: the dry-run generate path returns graph + readback + diff and saves nothing, saving always requires acknowledgeChanges so a human reviews the diff, a missing acknowledgement produces a refusal carrying the readback, unresolved references (e.g. an approver not in the workspace) block saving until chosen, and the trigger/name are never altered. This is exactly the behavioral detail annotations cannot convey.

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?

The generate-vs-save distinction is front-loaded and nearly every clause carries non-redundant information (guardrails, refusal behavior, trigger immutability). It is a dense single block of prose rather than a structured list, which makes the mode-switching and guardrail clauses slightly harder to scan, but there is little padding.

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 names the return payloads (proposed graph, plain-language readback, diff), the save/refusal outcomes, and the blocking failure mode (unresolved references). For a mutable, dual-mode tool with a nested graph object, nothing an agent needs to call it safely is missing.

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 meaningfully reinforces semantics: 'graph' is a save payload from a previous reply (omit when generating), 'prompt' drives generation (omit when saving), and acknowledgeChanges is mandatory for saves that remove a step or reach outside Onplana. It adds the mutual-exclusion and the review prerequisite beyond the schema's per-parameter text.

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 ('Design a workflow graph with AI for an existing workflow') plus scope constraints, and contrasts itself with adjacent concepts by declaring it edits an existing workflow and cannot create or activate one. An agent can distinguish it from get_workflow, duplicate_workflow, list_workflows and test_run_workflow without opening any 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?

Explicitly routes the two usage modes: called with 'prompt' it generates a preview (writes nothing), called with 'graph' from a previous reply it saves. It also states the when-not conditions (cannot create a workflow, cannot activate one, saved draft stays in whatever state the workflow was already in), so the agent knows the boundaries before calling.

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