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

Goes beyond annotations by disclosing the dispatcher absence, the 'not_executed' recording for remaining steps, and the 'dispatch_required' outcome with 'pending_dispatch' list. This is critical behavioral context not present in 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?

Well-structured: opens with a clear purpose, follows with usage guidance and a critical note about the dispatcher, then states the return value. Every sentence adds value without redundancy.

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?

Since there is no output schema, the description must explain return behavior, which it does (updated state and the dispatch_required case). It also covers prerequisites and side effects, making the tool fully understandable for correct invocation.

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%, and both parameters have clear descriptions. The description adds no extra parameter semantics beyond what the schema already provides, so 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?

States a specific verb ('Approve') and resource ('a workflow') and explicitly differentiates from cancel_workflow. The '[WRITE]' prefix clarifies the operation type. Clear and unambiguous.

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?

Provides explicit when-to-use conditions: after showing the user and obtaining consent. Also names the alternative (cancel_workflow) for the rejection case and the state requirement ('awaiting_approval'). No inference needed.

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 destructive/write annotations, the description reveals preview-vs-acting behavior, refusal conditions, audit-log writes, left_in_place and unknown_effects semantics, and that cancelled workflows are dead to run_workflow and approve. No annotation contradiction exists.

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?

Longer than usual, but every section carries necessary safety information for a destructive operation with no output schema. The purpose and the critical 'don't confirm on your own' caution appear early, and the Returns section is clearly separated.

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 4-parameter destructive workflow cancellation tool with no output schema, the description is complete: it explains return values, expected side effects, refusal cases, and the rollback alternative. Nothing an agent needs to select or invoke it correctly 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 complete, but the description layers on critical extra meaning: confirm=false previews, acknowledge_unknown_effects covers only those steps, and reason is recorded in the audit log. This materially improves an agent's ability to set these parameters correctly.

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.' It also distinguishes itself from siblings by saying it only stops future steps and explicitly routes completed-step reversal to rollback(). An agent can tell this apart from run_workflow, approve, and rollback.

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 conditions (approval REJECTED, unsafe plan, operator decision), the not-to-use case (undoing completed steps), and the safe preview-then-confirm workflow. It even warns not to set confirm=True merely because the user asked earlier. This is exactly the when/when-not/alternative guidance required.

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?

Beyond the annotations, the description discloses critical behavioral rules: steps without approval gates for destructive/confirm=True operations are refused with nothing saved, the error names the step and gate, and failures are not automatically rolled back. This adds real operational context that the sparse annotations do not capture.

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 long but every section earns its place: purpose, usage routing, step contract, refusal behavior, return value, and next actions. It is front-loaded with the core purpose and usage guidance, and the later paragraphs organize constraints and follow-up steps logically.

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 tool with no output schema and complex nested step objects, the description covers why, when, how, what can fail, what the return looks like, and which sibling to call next. The edge-case behavior around approval gates and rollback is exactly the kind of contextual detail an agent needs to invoke this tool safely.

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 substantial meaning for the steps parameter: required and optional keys, the require_approval action convention, and the confirm=True refusal condition. It does not need to explain every schema field, but it enriches the most complex parameter well 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 states a specific action ('Create a custom workflow dynamically from a step list') and distinguishes this tool from siblings by clarifying it is for known steps with no matching built-in template. It names plan_workflow and design_workflow as alternatives, making the tool's niche unambiguous.

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 this tool ('when you already know the steps and no built-in template matches') and when to prefer alternatives with concrete conditions ('prefer plan_workflow when one does, and design_workflow when the user gave a goal rather than steps'). It also instructs the agent to call get_skill_catalog first, which is actionable and specific.

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?

Even though annotations already mark this as readOnly and idempotent, the description adds critical behavioral detail: 'Returns a point-in-time snapshot and does not advance the workflow.' It also explains the meaning of outcome values ('dispatch_required', 'awaiting_approval'), giving the agent a concrete understanding of what the tool actually provides and what side effects it lacks. This goes well beyond the annotation hints.

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 highly information-dense: an opening READ marker, purpose statement, usage guidance, behavioral disclaimer, and return summary. Not a word is wasted, and the key usage condition (polling after run_workflow) is front-loaded.

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 simple read-only tool with one parameter and no output schema, the description fully covers what an agent needs: what it returns (steps, audit log, diff report), why to call it (polling, diagnosing stops), and the relevant outcome semantics. It complements the annotation-heavy safety profile and gives actionable dispatch guidance without omitting anything necessary.

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 schema itself already documents the sole parameter workflow_id with 'The workflow ID to query.' The description does not add extra meaning about the parameter beyond that; it references workflow_id indirectly through context but doesn't elaborate on its format, provenance, or constraints. Since schema coverage is 100%, this is exactly the baseline 3 case where no description compensation is needed.

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 'Get current workflow state, diff report, and audit log,' which names a specific verb ('get'), the resource ('workflow status'), and the constituent parts (state, diff, audit log). It further distinguishes itself from siblings by framing the tool as a read-only polling action after run_workflow, clearly separating it from the many mutation tools like approve or cancel.

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 description explicitly tells when to use this tool: 'poll a workflow after run_workflow' and to 'find out why one stopped.' It also provides conditional next actions based on outcome values (e.g., 'dispatch_required' means perform pending steps, 'awaiting_approval' means call approve), which implicitly names the alternative tools and routes the agent appropriately.

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 readOnly, idempotent, and non-destructive traits. The description adds value by detailing the return structure (dict with builtin, custom, active_workflows) and the source of custom templates (~/.vmware/workflows/*.yaml), which goes beyond annotations and helps the agent understand behavior.

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 with a [READ] marker, clear usage guidance, and a Returns section. It is slightly longer than necessary but each sentence earns its place by providing actionable context. The front-loaded purpose makes it easy to scan.

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 parameters and no output schema, the description compensates by explaining the return structure and linking to related tools (plan_workflow, create_workflow, get_workflow_status). It also explains where custom workflows live, which is essential for an agent to use 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?

The tool has zero parameters, so the baseline is 4. The description correctly implies no inputs are needed and does not need to explain parameters. It focuses on output and usage, which is appropriate.

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 the tool lists all available workflow templates (built-in + custom). It uses a specific verb-resource pair and distinguishes itself from siblings by explaining its role as the initial discovery step, routing to plan_workflow or create_workflow as needed.

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 description explicitly states when to use this tool ('Use this first to see whether a template already covers the goal') and provides clear alternatives (plan_workflow, create_workflow). It also instructs how to add custom workflows via YAML files, offering concrete usage context.

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 annotations, the description discloses a specific refusal behavior: custom YAML templates with a destructive/unclassifiable step or confirm=True without require_approval are refused with a message naming the step and file. It also distinguishes read-only compliance_scan from approval-required flows. Annotations are not contradicted.

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 operation and usage guidance; the workflow-type list is compact and the refusal/return notes are each relevant. It is slightly dense but not bloated.

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?

The description covers purpose, when-to-use, alternatives, all built-in types, refusal behavior, and return value. The only minor gap is per-type parameter shape, but given params is an open object this is not fatal.

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 schema gives only 'One of the available workflow types' for workflow_type; the description supplies the actual enum values and summarizes each. For params, it stays generic, but with additionalProperties allowed and 100% schema coverage, this is acceptable.

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 first sentence states a clear action on a distinct resource: 'Create an execution plan for a multi-step workflow.' It also names the exact sibling alternative (create_workflow) in the same sentence, allowing an agent to distinguish it immediately.

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 ('when the goal matches one of the built-in types below') and when to use a different tool ('use create_workflow instead when none of them fit'). It also provides the list of built-in types and their purpose, plus a refusal condition for unsafe custom templates.

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, the description discloses that this is a pure read/review operation that cannot inspect sibling skill annotations, explains why unclassified steps are reported as 'ungated_unclassified' rather than assumed safe, details the classification order (get_skill_catalog first, then name patterns), and clarifies force=True only applies to built-in templates. This is substantial behavioral nuance the annotations do not provide.

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 front-loaded with purpose and scoping, and uses clear bullet lists and a return-key breakdown. It is long, and there is some redundancy between 'does NOT call into other skills' and the later 'pilot dispatches nothing itself' passage, but the detail is mostly justified given the absence of an output schema and the nuanced validation policy.

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 fully documents the return structure (verdict, findings, summary), the finding kinds that cause run_workflow to refuse, the force=True caveat, and the classification rules. An agent has all necessary information to invoke the tool correctly and interpret its results.

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 schema already fully describes workflow_id as 'The workflow ID returned by plan_workflow' with 100% coverage. The description adds only contextual framing like 'planned workflow' and 'before execution' but no additional parameter-specific semantics, so the baseline of 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?

The description opens with a specific verb and resource: 'Sanity-check a planned workflow before execution.' It clearly differentiates from siblings by stating 'structural validation only' and 'does NOT call into other skills', so it cannot be confused with run_workflow, plan_workflow, or design_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?

The description explicitly says to use it 'before execution' and 'before they hit production', and states when-not: 'structural validation only' and 'does NOT call into other skills'. It also references run_workflow's refusal behavior, force=True semantics, and the gating relationship with require_approval, giving clear contextual 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?

It discloses critical behavior beyond annotations: confirm changes effect, nothing rolls back automatically, only 'success' steps are undone, failed undo doesn't stop the rest, state is set to 'failed', refusal conditions, and redaction of secrets. This is exactly the contextual depth an agent needs for a destructive, non-idempotent operation.

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 long but tightly organized: primary action, preview behavior, execution semantics, refusals, return shape. Each paragraph adds distinct operational guidance and the opening sentence front-loads the purpose.

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 tool with no output schema, it fully covers return shapes, error/refusal cases, side effects on workflow state, and follow-up verification via get_workflow_status. No critical operational gap remains.

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?

Though schema coverage is 100%, the description adds substantial meaning: confirm=False is a preview, confirm=True applies rollback and is the actual decision to run rollback_tool calls, and acknowledge_unknown_effects only covers listed unknown steps. This goes well beyond the schema's terse field descriptions.

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 first sentence names a specific verb and resource ('Abort a workflow and rollback completed steps in reverse order') and the rest clarifies that it is a best-effort undo for Pilot-recorded successes, which sets it apart from sibling cancellation and workflow-status tools. An agent can identify what action this performs without inspecting 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?

The description gives explicit usage rules: preview first with confirm=False, show the user, require explicit decision, and never self-confirm just because the user asked earlier. It also specifies alternatives for steps the tool will not reverse (call each rollback_tool with rollback_params yourself) and notes the dispatcher variant.

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 provide readOnly/idempotence/destructive/open-world hints, so the description carries the behavioral burden. It adds the important no-dispatcher execution model, recording of 'not_executed' steps, audit logging of forced runs, refusal conditions, and the fact that 'completed' only happens with a real dispatcher. This is far more than the annotations alone could 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?

Longer than minimal, but the tool is complex and every paragraph serves a distinct purpose: execution model, safety review, approvals, and return values. The critical no-dispatcher caveat is front-loaded, and the use of bolded terms helps structure the content without redundancy.

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?

Even without an output schema, the description fully documents the possible outcome values, the pending_dispatch list, refusal conditions, and the agent's subsequent responsibilities. For a mutation tool with security-relevant behavior and a dispatcher gap, this is complete enough for an agent to invoke it correctly and know what to do next.

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 valuable meaning beyond the schema by explaining that force bypasses review findings only on built-in templates, is audited, and has no effect on custom workflows. This extra nuance helps the agent use the force parameter correctly.

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 ('Advance') and resource ('a planned workflow'), and specifies the pause-at-approval behavior. It also differentiates itself from siblings by telling the agent to call approve() to continue after an approval gate, making it clear this tool is the execution step, not the approval step.

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 and when-not-to-use guidance: runs are refused for ungated destructive steps, force only applies to built-in templates, custom workflows require an added require_approval step, and approval gates require approve(). It also tells the agent it must perform the pending skill/tool calls itself when dispatch_required is returned, which is a critical routing instruction.

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.