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

Annotations only cover the generic safety profile (write, non-idempotent, open-world), while the description discloses non-obvious behavior: refusal listing steps in not_executed_before_gate, the acknowledge_not_executed gate, the 'reported_done' vs 'not_executed' bookkeeping, timeout behavior ('Pilot carries on — check get_workflow_status'), and the outcome='dispatch_required'/'pending_dispatch' return semantics.

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?

Content is valuable and mostly front-loaded, but the not_executed behavior is explained twice (once in the gate paragraph and again in the dispatch paragraph), and the CLI-style '--dispatch' framing adds noise to a JSON-parameter tool. Trimming the duplication would sharpen it without losing information.

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 carries the return burden and does reasonably well, stating 'Updated workflow state after resuming' and enumerating the dispatch_required outcome and pending_dispatch list. It is nearly complete for a complex stateful write; only the exact shape of the returned state is left unspecified.

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 baseline is 3, but the description adds real depth beyond the schema for acknowledge_not_executed ('set it only after you performed each of those steps yourself and showed the user their results') and explains the approver/auth interaction. It loses a point for repeatedly referencing a '--dispatch' flag that does not exist as a parameter in the schema, which could mislead an agent about the call signature.

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+resource and scope: '[WRITE] Approve a workflow that is waiting for human confirmation.' It also explicitly distinguishes itself from the sibling cancel_workflow and names the required precondition (state 'awaiting_approval'), so an agent can select it 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?

Explicit when-to-use ('only after showing the user the pending step and getting explicit human consent'), when-not ('use cancel_workflow instead when the approval is rejected'), and a hard state prerequisite ('Only works when workflow state is awaiting_approval'). It also gives conditional guidance for the dispatch and acknowledge_not_executed paths.

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

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

Annotations already declare destructive=true, but the description goes well beyond them: it discloses the preview/act gate, enumerates blast_radius fields (left_in_place, performed_outside_pilot, handed_out_to_caller, would_skip, unknown_effects), lists the exact refusal conditions, notes the acknowledge_unknown_effects escape hatch, and states the cancellation is written to the audit log.

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 well front-loaded: the write marker, verb, and terminal-state outcome come first, followed by when-to-use, then the preview contract, then refusals. It is longer than typical, and the blast_radius field enumeration is verbose, but each block carries distinct operational information.

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?

No output schema exists, and the description compensates by specifying both return shapes (preview with blast_radius/hint vs. acting with state/outcome/action) plus the refusal error case. Combined with the refusal list and the partial-application caveat, an agent has everything needed to call and interpret this 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that confirm=False is a preview-only mode whose purpose is user review, and that acknowledge_unknown_effects covers only the unknown_effects steps while every other refusal still applies. The reason parameter's audit-log role is also reinforced.

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 ('Cancel a workflow — move it to the terminal CANCELLED state') and immediately differentiates from the closest sibling by clarifying it does not undo completed steps ('use rollback() to reverse those'). An agent can distinguish this from run_workflow, approve, and rollback 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?

Gives explicit triggers (approval REJECTED, review flags unsafe, operator decision) and an explicit exclusion with the alternative named (cancelling does not undo completed steps — use rollback). It also prescribes the correct workflow for the preview step: show blast_radius to the user, do not set confirm=True unprompted.

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

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

Beyond the annotations, it discloses the DRAFT-to-PENDING state change, optional template persistence, and important refusal conditions for destructive or unclassifiable steps lacking require_approval gates. It also states that nothing is saved when confirmation is refused, which is genuinely useful behavioral context.

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 description is compact and front-loaded, covering action, usage, alternatives, refusal, and return value in a short space. It loses a point for the awkwardly worded 'Refused — ... while ...' sentence, which is grammatically tangled but still decipherable.

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 write operation with no output schema, it explains the return value ('Confirmed workflow summary'), the required next step, the alternative tool, and the failure/refusal semantics. The remaining details, such as built-in template conflict behavior, are covered by the schema.

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 schema already documents workflow_id and save_as_template well. The description adds small extra meaning by mentioning that the template is YAML and placing the save within the confirmation flow, which is slightly beyond 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?

The description opens with a specific verb and resource: 'Confirm a draft workflow — changes state from DRAFT to PENDING.' This clearly names the action, the object, and the state transition, and it is immediately distinguishable from siblings like update_draft and run_workflow.

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 explicitly states the trigger condition ('once the user has approved the draft's steps'), the alternative ('call update_draft instead if anything still needs changing'), and the next step ('run_workflow()'). This gives the agent concrete routing guidance.

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

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

Annotations only supply readOnlyHint=false and destructiveHint=false; the description goes well beyond that by disclosing the required step schema, the approval-gate mechanism (action='require_approval', skill 'pilot', tool 'approve'), and the refusal behavior that names the offending step when a destructive/confirm=True step lacks a gate. It also states the return value, the follow-up sequence, and that nothing is undone automatically on failure.

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 [WRITE] tag and one-line purpose, then usage routing, then mechanics. The refusal paragraph is dense but load-bearing; the Returns block is slightly more verbose than necessary, keeping it just short of maximum.

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 carries the return contract (workflow_id + plan summary) and the recommended next calls (review_workflow, then run_workflow), plus rollback expectations. For a mutation tool with a validation-refusal path, this is complete enough to drive correct use.

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 100%, so the baseline is 3, but the description adds real semantics the schema lacks: the exact step keys (action, skill, tool, params plus optional rollback_tool/rollback_params) and the special require_approval action values. It does not elaborate on save_as_template beyond what the schema already states.

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?

Opens with '[WRITE] Create a custom workflow dynamically from a step list,' naming a specific verb, resource, and input mode. It explicitly distinguishes itself from two siblings (create_workflow_from_template and design_workflow), so an agent can route without reading schemas.

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 explicit when-to-use ('you already know the steps and no built-in template matches'), names the two alternatives with the exact conditions that select them, and adds a prerequisite ('Call get_skill_catalog first for the skill and tool names'). Nothing is left to inference.

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

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

Annotations already cover the safety posture (write, non-idempotent, non-destructive), yet the description adds substantial context beyond them: the workflow persists in 'pending', it is explicitly not a dry run, and custom YAML templates with an unguarded destructive/unclassifiable/confirm=True step are refused with the step and file named. That refusal semantics and persistence detail go well past what the annotations 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?

Front-loaded with a [WRITE] marker and a one-sentence purpose, followed by usage, refusal conditions, type list, and returns in a logical order. The four-entry template list is the longest block but each entry carries distinct routing value, so little is wasted.

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?

There is no output schema, and the description compensates by describing the return (workflow_id, steps summary, plan details). With persistence state, refusal behavior, alternative routing, and template enumeration all covered, 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?

Schema coverage is 100%, so baseline would be 3, but the description adds genuine meaning: it explains that workflow_type is a template name and enumerates the four available built-in types with their step shapes, plus notes params are workflow-specific. That fills the gap left by the schema's vague 'One of the available workflow types.'

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 and save a workflow from a template') and immediately clarifies the output state ('pending', 'not a dry run'). It explicitly distinguishes itself from the sibling create_workflow, which saves a custom step list instead.

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 selection rule: 'Use this when the goal matches a template; use create_workflow instead to save your own step list when none of them fit.' It also names list_workflows as the discovery path for both built-in and custom templates, covering when-to-use, when-not, and alternatives.

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

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

The description discloses the key behavior: it creates a DRAFT workflow with state=DRAFT, returns a proposed-steps placeholder for review/edit, and pushes the agent toward update_draft and confirm_draft next. The annotations already indicate a non-read-only, non-destructive write, and the description adds lifecycle context without contradicting them.

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 description is well-structured and front-loaded with the action and trigger, followed by the flow and return contract. There is minor redundancy between 'Returns a DRAFT workflow...' and the later 'Returns:' block, but the latter is more precise about the output shape.

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 two-parameter tool with no output schema, the description is largely complete: it names the required input, the returned workflow state, the placeholder behavior, and the follow-up flow. It does not cover error conditions or constraints details, but the schema fills the constraints gap and the missing details are minor.

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%, with both `goal` and `constraints` already documented. The description adds little parameter-level detail beyond explaining that the input is a natural-language description; it does not go deeper on constraints, so the schema carries the semantic weight.

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 clear verb and resource ('Start designing a workflow') and explains that it converts a natural-language goal into a DRAFT workflow with proposed steps. It does not explicitly call out how it differs from similar siblings like plan_workflow or create_workflow, though the DRAFT/lifecycle wording provides some differentiation.

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 an explicit trigger: use this when the user describes a complex operation needing a multi-step workflow. It also provides a design flow and instructs the agent to call get_skill_catalog for candidate tools. However, it does not mention when not to use this tool or how it compares to sibling planning tools, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable context: the catalog is static and may lag actual skill tool lists, and that the calling agent cannot invoke these tools itself. It also specifies the return structure, going beyond the annotation coverage.

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 description is well-structured and concise: it starts with the purpose, then usage context, a caveat, and the return format. Each sentence earns its place, with no redundancy or fluff. The front-loading of the read nature and purpose is effective.

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 no-parameter read-only catalog tool, the description is complete. It explains what is returned (dict mapping), how to use the result, and a known limitation (static data, lag). It also clarifies an important behavioral constraint (pilot cannot call these tools). Nothing essential 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?

There are zero parameters, so schema coverage is effectively 100% and the description cannot add parameter-specific details. Per the baseline for no parameters, a score of 4 is appropriate; the description does not need to compensate for any missing parameter docs.

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 clearly states a specific verb ('Get') and resource ('complete catalog of available skills and tools for workflow design'). It distinguishes itself from sibling tools by explicitly positioning itself as the source for building blocks used in workflow creation, not as a tool that designs or executes workflows.

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 provides clear context for when to use it: when designing a custom workflow, to understand available building blocks, and then feed names into create_workflow or update_draft. It also notes it is not a live query, which implicitly advises against using it when real-time registry data is needed, though it doesn't explicitly name alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds non-obvious behavior: it is a point-in-time snapshot that 'does not advance the workflow', and it decodes status semantics into next actions. That is exactly the kind of polling/idempotency context annotations cannot express.

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 scoping '[READ]' marker and the primary action, then the guidance. The trailing 'Returns:' block largely restates the opening ('Full workflow state including steps, audit log, and diff report'), a small redundancy but not enough to hurt usability.

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?

There is no output schema, so the description must cover return shape, and it does: snapshot semantics plus steps, audit log, and diff report. Combined with status-to-action guidance, an agent has everything needed to call and act on this tool.

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?

Only one parameter and schema coverage is 100% ('The workflow ID to query'), so the schema carries the meaning. The description adds nothing about ID format or origin, which is the correct baseline when the schema already documents the parameter.

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?

Names a specific verb+resource ('Get current workflow state') and enumerates the payload (state, diff report, audit log). It is clearly distinguishable from siblings like run_workflow, cancel_workflow, and approve, which are the mutation/transition counterparts.

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 says when to use it ('poll a workflow after run_workflow', 'find out why one stopped') and routes the agent to alternatives based on observed state: 'not_executed' steps are the caller's job, 'awaiting_approval' means call approve. That is when/when-not plus alternative routing in two sentences.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description still adds real behavioral context the annotations cannot: that built-in templates are always present while customs come from ~/.vmware/workflows/*.yaml, which tells the agent why a template might be missing.

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 [READ] marker and the core purpose, then routing, then source behavior, then a Returns block. Every sentence carries a distinct piece of information with no 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?

There is no output schema, and the description compensates by enumerating the return shape: builtin and custom lists with name, description, step count, plus the active_workflows IDs to feed into get_workflow_status. That is everything an agent needs to consume the result 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?

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No misleading parameter hints are present.

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 ('List all available workflow templates') and immediately scopes it to built-in plus custom, which no sibling does. The [READ] tag and the named siblings (create_workflow_from_template, create_workflow) let an agent place this tool 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?

Explicit conditional routing: use this first, then pass a name to create_workflow_from_template, otherwise fall back to create_workflow. Both the when-to-use and the alternatives are named outright.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds substantial behavior beyond them: no cross-skill calls, tier-based classification, the deliberate decision not to gate medium-risk writes, the honest 'ungated_unclassified' fallback, and the force=True limitation for custom workflows. This is exactly the kind of non-obvious behavior an agent needs and cannot infer from structured fields.

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 purpose, then organized as a scannable bullet list of the exact error classes caught, followed by a returns contract. It is longer than most descriptions, but nearly every line carries decision-relevant content; only minor prose (e.g. the medium-risk write rationale) could be tightened.

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?

Despite having no output schema, the description fully specifies the return dict (verdict, findings kinds, summary counts) and explains which finding kinds cause run_workflow to refuse. Combined with the classification and gating rules, an agent has everything needed to call this and interpret its result.

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?

There is a single required parameter with 100% schema description coverage, so the schema already documents workflow_id (the ID returned by create_workflow_from_template). The description adds no format, provenance, or constraint detail beyond that, so the baseline 3 applies.

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?

Opens with a specific verb+resource and an explicit scope qualifier ('[READ] Sanity-check a planned workflow before execution') and immediately bounds what it is not ('structural validation only — does NOT call into other skills'). An agent can distinguish it from design_workflow, run_workflow, and get_workflow_status 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?

The timing condition is stated clearly ('before execution') and the description ties findings to run_workflow's refusal behavior plus the force=True escape hatch, which effectively tells the agent when a review is load-bearing. It stops short of naming sibling alternatives (e.g. design_workflow / create_workflow_from_template) as the things to do first, so it is strong context rather than a full when/when-not routing statement.

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

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

Annotations already flag destructive/openWorld/non-idempotent, but the description goes well beyond: secrets are redacted, some steps stay applied (left_in_place), some are not_reversible or partial, a failed undo does not halt the rest, and the workflow is left in 'failed'. It also enumerates the exact refusal set and the acknowledge_unknown_effects escape hatch.

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 preview/act distinction and the user-decision warning are front-loaded, and nearly every sentence carries operational weight. It is nevertheless a dense wall of parenthetical clauses that could be tightened without losing meaning.

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?

Despite no output schema, the description documents both return shapes (preview vs acting, including rollback_incomplete and rollback_results), the terminal state, and the follow-up step of checking get_workflow_status. Nothing an agent needs to call this destructive tool 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 adds real meaning: confirm=True is framed as the user's explicit decision (not a re-confirmation of an earlier request), and acknowledge_unknown_effects is scoped to only the unknown_effects steps and only after the user has checked the target system.

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?

Opens with a specific verb+resource+scope: '[WRITE] Abort a workflow and rollback completed steps in reverse order,' and defines itself as the 'explicit, best-effort undo' distinct from an automatic abort. It never names a sibling (e.g. cancel_workflow) or contrasts itself against one, so the reader must infer the boundary rather than being told it.

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 states the when-not: without confirm=True it only previews, the agent must show blast_radius to the user and get an explicit decision, and must not set confirm=True on its own. It also names the alternative path for pending_dispatch steps (call each step's own rollback_tool, last step first) and lists every refusal condition.

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

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

Annotations only declare the safety profile (not read-only, not idempotent, not destructive, open-world); the description goes far beyond by disclosing refusal conditions, the structural review gate, audit logging of forced runs, the distinction between dispatch_required and completed, and the 'NEVER perform the steps yourself' constraint. This is exactly the kind of context annotations cannot carry.

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 [WRITE] tag and lead sentence front-load the operation, and the dispatch branches and safety rules are clearly delineated. It is long, but nearly every sentence carries decision-relevant information; the Returns section is slightly redundant given the outcome values are already stated.

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 complex, stateful tool with no output schema and only two parameters, the description supplies the missing return semantics ('outcome' values and 'pending_dispatch'), the caller obligations, and the failure/refusal model. An agent has everything needed to invoke and interpret this 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 coverage is 100%, so the baseline is 3, but the description adds real semantic depth to force: it overrides review findings only on built-in templates, requires human consent, is audited, and has no effect on a custom workflow's missing gate. It does not extend workflow_id beyond the schema, which is already documented.

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 ('[WRITE] Advance a planned workflow') plus a behavioral trait ('Pauses at approval gates'). It distinguishes itself from siblings by naming approve() for continuation and get_workflow_status for outcomes, so the agent can separate it from cancel/rollback/status tools without opening schemas.

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 covers the two dispatch modes, states what happens on timeout, when force=True is permitted (and when it is not), and when to call approve(). It effectively tells the agent whether it must perform steps itself or whether Pilot will, which is the key selection/usage question.

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

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

Annotations already establish this is a write (readOnlyHint=false) and non-idempotent. The description adds useful behavioral detail beyond those markers: steps are replaced wholesale, approval gates are tracked, and the result lists steps still needing approval while confirm_draft will refuse until none remain. It also discloses the return value. It doesn't mention potential errors or side effects in depth, but the added lifecycle and validation context earns a solid 4.

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 description is compact and front-loaded: the first sentence states the core purpose, then usage context, then step format, then behavioral detail. Every sentence adds necessary information for correct invocation, with no filler or redundancy. It is slightly longer than minimal but the additional context is all operational, so it earns a 4.

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 mutation tool with 4 parameters and no output schema, the description is thorough: it covers when to call, when not to call, the step data structure, approval validation behavior, and the return format. It doesn't explain default parameter behavior or error cases, but the schema already covers parameter descriptions and the draft lifecycle constraint is fully addressed. Overall, an agent has enough context to invoke 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by specifying the exact step dict shape ({action, skill, tool, params, rollback_tool?, rollback_params?}) and the special action value 'require_approval' for approval gates. It also explains the consequence of omitting approval gates during design, clarifying semantics of the steps parameter beyond the schema's 'replaces all existing steps.'

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 'Update a DRAFT workflow's name, description, or steps,' which names a specific action, resource, and the fields it affects. It further distinguishes itself from siblings by explicitly restricting usage to the DRAFT state and pointing to create_workflow for post-confirmation workflows, so an agent can clearly tell it apart without opening schemas.

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 explicit when-to-use guidance: 'Call this after design_workflow() to fill in the actual steps, or to modify steps based on user feedback.' It also states a hard when-not-to-use rule: after confirm_draft the steps are frozen and one must create_workflow a new one instead. This covers both the appropriate trigger and the exclusion condition, leaving no ambiguity.

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