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

Goes beyond annotations by disclosing that approval does not automatically execute next steps on this server; instead, it marks them as 'not_executed' and returns outcome='dispatch_required' with a 'pending_dispatch' list. This is critical behavioral context not implied by readOnlyHint=false or destructiveHint=false.

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 clear purpose, usage guidance, args, note, and returns section. Every sentence adds value, especially the dispatcher note which is essential for correct agent behavior. No fluff.

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 tool mutates workflow state and has no output schema; the description covers prerequisites, side effects, return value, and the special dispatch requirement. It references run_workflow for further context, making it complete for an agent to use 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 schema lacks parameter descriptions, but the description compensates fully by explaining workflow_id as 'The workflow ID to approve' and approver as 'Name of the person approving (for audit trail)', adding meaningful semantics beyond the bare 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 clearly states the tool's function: 'Approve a workflow that is waiting for human confirmation.' It uses a specific verb and resource, and distinguishes itself from siblings by explicitly mentioning cancel_workflow for rejections and the awaiting_approval state requirement.

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 usage instructions: 'Use this only after showing the user the pending step and getting explicit human consent' and directs to cancel_workflow when approval is rejected. Also specifies the precondition that the workflow must be in 'awaiting_approval' state.

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?

Discloses side effects: moves to terminal CANCELLED state, stops future steps, does not undo completed, writes to audit log, returns error if already terminal. Annotations are readOnlyHint=false and destructiveHint=false, which are consistent; description adds far more detail.

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?

Description is thorough but not overly verbose; includes clear sections (Args, Returns). Some repetition could be trimmed, but it's well-organized and front-loaded with the most critical 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?

Given no output schema, description provides return format (updated workflow state or error). Also includes necessary context about the tool's effect on workflow lifecycle, making it fully self-contained for an agent.

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 0%, so description must compensate. It fully describes both parameters: workflow_id (the ID to cancel) and reason (optional human-readable reason with example and that it's recorded in audit log). This is excellent guidance.

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?

Description starts with '[WRITE] Cancel a workflow — move it to the terminal CANCELLED state.' Clearly states the verb and resource. Distinguishes from siblings like rollback, run_workflow, and approve by explaining when to use 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 when to use: approval rejected, review flags unsafe, operator decision. Also states when not to use and alternatives: 'Cancel only stops FUTURE steps. It does NOT undo already-completed steps — use rollback() to reverse those.' Also indicates valid only from non-terminal state.

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 that this is a write operation ([WRITE]) that changes state, consistent with readOnlyHint=false. It also reveals a side effect: optionally saving a YAML template to ~/.vmware/workflows/, which goes beyond the annotations. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and efficient, with clear structure (overview, usage, args, returns). Some redundancy (repeating run_workflow call) but overall every sentence earns its place.

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, usage, parameters, and return value, and there is no output schema to rely on. It could mention the precondition that the workflow must be in DRAFT state, but the rest is sufficiently complete.

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?

With schema description coverage at 0%, the description compensates by explaining each parameter: workflow_id is 'The draft workflow ID to confirm' and save_as_template is 'If True, save to ~/.vmware/workflows/'. This adds functionality beyond the bare 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 clearly states the tool's function: confirming a draft workflow and transitioning it from DRAFT to PENDING. It distinguishes from sibling tools like update_draft and run_workflow by specifying the exact state change and subsequent execution.

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 when to use ('once the user has approved') and when to use update_draft instead ('if anything still needs changing'). Also provides sequencing guidance by mentioning that run_workflow() should be called after confirmation.

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 key behavioral traits beyond annotations: the [WRITE] prefix, dynamic creation from steps, the requirement for approval for destructive steps, and the side effect of saving a YAML file when save_as_template is true. Annotations are consistent (readOnlyHint=false), so no contradiction.

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 primary purpose. It uses clear sections for usage, step requirements, args, and returns, with each sentence earning its place. No filler or 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?

The description is complete for a complex tool with no output schema and low schema coverage. It covers prerequisites (get_skill_catalog), step structure, approval gates, side effects, and the full follow-up flow (review_workflow, run_workflow, rollback). No gaps remain.

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?

Despite 0% schema description coverage, the description fully documents each parameter: name (used as workflow_type), description, steps (with required sub-fields action/skill/tool/params and optional rollback fields), and save_as_template (with file path). This adds critical meaning beyond the bare 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 immediately states a specific verb+resource: 'Create a custom workflow dynamically from a step list.' It clearly distinguishes this from siblings by naming plan_workflow and design_workflow as alternatives with different applicability criteria.

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 usage guidance is provided: use when you already know the steps and no built-in template matches; prefer plan_workflow when a template matches; prefer design_workflow when the user gave a goal. It also instructs calling get_skill_catalog first for skill and tool names.

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 goes beyond annotations by clarifying that the tool creates a DRAFT workflow with 'proposed steps placeholder,' meaning the output is incomplete and requires further updates via update_draft. It also states the workflow state is DRAFT. This adds valuable behavioral context that the annotations (readOnlyHint=false, openWorldHint=true) do not convey. No contradictions.

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 clear opening, usage context, flow, prerequisites, args, and returns. Each section adds necessary information; nothing seems redundant.

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 explains return values (workflow_id, state=DRAFT, placeholder, instructions) despite no output schema. It also outlines the full design flow and prerequisites, making it complete for the tool's complexity.

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 input schema provides no parameter descriptions (0% coverage), but the description fills the gap with clear definitions for both 'goal' and 'constraints,' including examples for constraints. This fully compensates for the schema gap.

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's function: 'Start designing a workflow from a natural language description.' It specifies the resource (workflow) and the action (design), and distinguishes it from siblings by positioning it as the initial entry point in the design flow (design_workflow → update_draft → confirm_draft → 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?

Provides explicit when-to-use: 'Call this when the user describes a complex operation and you need to design a multi-step workflow.' It also instructs to use get_skill_catalog() first. However, it does not explicitly mention when not to use it or alternative tools like create_workflow, so a 4.

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 provide readOnlyHint and idempotentHint, the description adds unique behavioral context: the catalog is static and may lag the actual registry, and that the calling agent (not the pilot) must invoke the listed tools. It also discloses the return structure, giving the agent a clear expectation of the output.

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 bold READ tag, early statement of purpose, then usage guidance and a note on limitations, followed by a compact return format. Every sentence adds necessary value, and the most critical information 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?

Despite having no output schema, the description fully documents the return type ('dict mapping skill name → {description, tools: {tool_name: {risk, desc}}}'). It also explains the tool's role in the workflow design process, making it complete for an agent to select and 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 schema trivially covers 100%. The description does not need to explain parameters. Baseline for zero params is 4, and no additional parameter semantics are required.

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 begins with '[READ] Get the complete catalog of available skills and tools for workflow design,' which names a specific verb, resource, and context. This clearly distinguishes it from sibling tools like create_workflow and run_workflow that perform actions rather than provide an inventory.

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 when to use the tool ('when designing a custom workflow') and how to use the result ('feed the skill and tool names into create_workflow or update_draft steps'). It also clarifies limitations (static catalog may lag, pilot cannot call tools) which prevents misuse, going beyond generic 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 already declare readOnlyHint/idempotentHint/destructiveHint=false, but the description adds valuable behavioral context beyond that: it 'Returns a point-in-time snapshot and does not advance the workflow,' and it explains the semantic meaning of specific outcome values. This goes above and beyond the structured 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 moderately long but well-structured with a [READ] tag, usage context, outcome explanations, args, and returns. Every sentence earns its place, and the critical information is front-loaded. It is concise relative to the amount of behavioral nuance it conveys.

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?

Given there is no output schema, the description fully explains the return value: 'Full workflow state including steps, audit log, and diff report.' It also covers side effects (no advancement), outcome semantics, and references to related tools (run_workflow, approve), making it complete for the tool's complexity.

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 has zero parameter descriptions, so the description must compensate. It says 'workflow_id: The workflow ID to query,' which is clear but essentially restates the schema title. For a single simple ID parameter, this is adequate but adds no extra depth like formats or examples.

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 '[READ] Get current workflow state, diff report, and audit log,' which is a specific verb+resource that clearly states what the tool does. It also distinguishes itself from siblings by framing this as the polling/status tool after run_workflow, not a workflow creation or mutation tool.

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 'Use this to poll a workflow after run_workflow and to find out why one stopped,' giving direct when-to-use guidance. It also provides conditional alternatives: 'awaiting_approval' means call approve, and 'dispatch_required' means perform pending steps yourself, clarifying when not to rely solely on this tool.

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=true, idempotentHint=true, and destructiveHint=false. The description complements this by adding context about the source of custom templates (~/.vmware/workflows/*.yaml) and the exact return structure, including active_workflows for passing to get_workflow_status. No contradictions with annotations. The behavior is transparent for a read-only listing tool.

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 a bracketed '[READ]' and a one-line purpose statement. It then provides just enough context: usage flow, custom template path, and return structure. Every sentence earns its place; there is no filler or repetition. The three short paragraphs are well-structured and scannable.

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 explains the returned dict's keys (builtin, custom, active_workflows) and how to use the active_workflows IDs. It also includes enough sibling context (plan_workflow, create_workflow, get_workflow_status) to make the tool's place in the workflow clear. For a zero-parameter, read-only listing tool, this is complete.

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 the baseline for this dimension is 4 per the rubric. The description adds no parameter semantics because none exist, but it compensates by thoroughly detailing the return value, which is the only meaningful information an agent needs for invocation.

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, specific verb+resource: 'List all available workflow templates (built-in + custom).' It distinguishes itself from siblings by explicitly positioning this as the first step and directing to plan_workflow or create_workflow based on the result, making its purpose unambiguous relative to other workflow tools.

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?

Usage guidance is explicit: 'Use this first to see whether a template already covers the goal, then pass its name to plan_workflow; if none fit, use create_workflow instead.' It also explains the custom template file path, which informs when custom templates might appear, giving the agent clear decision-making 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?

Annotations indicate a non-read-only, non-idempotent operation. The description adds context beyond that by marking the tool as '[WRITE]' and explaining approval gates for some workflow types while noting compliance_scan is read-only with no approval. It does not fully describe side effects or state changes, but the added context is valuable.

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: it opens with the main action, then usage guidance, then a clear list of workflow types, then parameter details, and finally return value. Every section earns its place, and while lengthy, it is organized with lists and headers that make 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?

Given there is no output schema, the description correctly explains the return value (dict with workflow_id, steps summary, and plan details). It covers all workflow-specific parameter schemas and explicitly mentions the approval gates. This makes the tool complete even for a complex multi-mode operation.

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 input schema has no descriptions for parameters (0% coverage), so the description carries the full burden. It thoroughly explains workflow_type and then details per-type params for each of the four workflow types with types and field names. This goes well beyond the schema and makes the parameters self-explanatory.

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 clear verb+resource: 'Create an execution plan for a multi-step workflow.' It also lists four specific workflow types and explicitly contrasts with the sibling tool create_workflow, making the tool's purpose distinct 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?

The description explicitly tells the agent when to use this tool ('Use this when the goal matches one of the built-in types below') and when to use an alternative ('use create_workflow instead when none of them fit'). It also gives a brief scenario for each workflow type, providing strong usage 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 already declare readOnlyHint=true and destructiveHint=false. The description adds 'Performs structural validation only — does NOT call into other skills,' clarifying the read-only nature and constraints. No contradictions.

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?

Description is front-loaded with purpose and key constraint, uses bullet points for error checks, and has well-structured Args/Returns sections. 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?

For a simple one-parameter tool, the description fully specifies inputs, outputs (verdict, findings, summary), and behavioral constraints. Annotations cover safety hints. No gaps given the tool's validation-only role.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description documents 'workflow_id: The workflow ID returned by plan_workflow,' adding provenance constraints beyond the schema's bare type/required annotation.

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 'Sanity-check a planned workflow before execution' and specifies it performs structural validation only, distinguishing it from sibling tools like run_workflow or plan_workflow. It lists specific error types caught, making the purpose precise.

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 when to use ('before execution') and what it does NOT do (does not call into other skills). It lists common errors it catches, guiding usage context. Lacks explicit exclusions or alternative tool mentions, but the context is clear.

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 and write behavior; the description adds concrete behavioral details: irreversible steps are skipped, workflow state becomes 'failed', and it works in any state except 'completed'. It also notes the return value and advises checking get_workflow_status afterward, transparently setting expectations.

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 moderately concise, starting with a clear verb phrase and including alternative guidance. The Args/Returns sections add useful context, though the Args section is somewhat redundant with the schema.

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?

All essential aspects are covered: purpose, alternatives, state constraints, behavior on irreversible steps, and post-rollback verification. Given the tool's simplicity and the annotation coverage, this is complete.

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 declares workflow_id as a required string, and the description merely restates 'The workflow ID to rollback.' With 0% schema coverage, the description does not provide additional semantic info such as format, source, or constraints beyond the obvious, but it at least lists the parameter clearly.

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 uses the specific verb 'abort' and 'rollback' with the resource 'workflow', clearly stating it undoes completed steps. It explicitly distinguishes itself from cancel_workflow by specifying when to use each, making the purpose 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 states when to use this tool versus cancel_workflow: use rollback for already-run steps, and cancel_workflow for not-yet-started or rejected workflows. It also specifies the allowed states ('any state except completed') and the resulting state ('failed'), providing clear usage conditions.

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 (readOnlyHint=false, destructiveHint=false), the description discloses critical behaviors: no dispatcher, outcome states, safety review refusal, audit logging of forced runs, and return format. This adds value over 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?

The description is well-organized into clear sections (overview, important note, safety, args, returns). Each sentence is informative and non-redundant, achieving conciseness without sacrificing completeness.

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?

Given the tool's complexity (workflow execution, approval gates, dispatcher limitation, safety checks), the description covers all necessary aspects, including return values and state outcomes, despite no output 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 0%, but the description fully explains both parameters: 'workflow_id' (from plan_workflow) and 'force' (bypasses review with explicit human consent, audited). This compensates for lack of schema 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 description starts with '[WRITE] Advance a planned workflow. Pauses at approval gates.' It specifies the action ('advance') and resource ('planned workflow'), clearly distinguishing from sibling tools like 'approve' or 'cancel_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 provides detailed usage context: the server has no dispatcher, steps are recorded as 'not_executed', and the calling agent must perform the pending steps. It explains when to use 'force' and conditions for refusal, differentiating from 'approve' for gates.

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 important behaviors beyond annotations: that steps are replaced as a whole ('replaces all existing steps'), that it's only valid pre-confirmation, and the [WRITE] flag. This adds context to the annotations' readOnlyHint=false and destructiveHint=false, clarifying the actual mutation scope without contradiction.

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 usage guidance, step format, Args, and Returns. Every sentence adds value—no fluff, yet it covers all necessary details without excessive length.

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?

Given no output schema, the description covers the return value ('Updated workflow summary for user review'') and explains the workflow lifecycle context. Combined with sibling references and precise parameters, it is fully complete for an agent to select and invoke 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 schema provides only names/types with no descriptions (0% coverage). The description compensates fully by explaining each parameter's purpose, optionality, and the step dict structure, including approved actions. This is essential for correct invocation.

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 'Update a DRAFT workflow's name, description, or steps' with a specific verb and resource. It differentiates from siblings by emphasizing the DRAFT state and pointing to create_workflow for after confirmation.

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 says when to use it ('after design_workflow() to fill in the actual steps, or to modify steps based on user feedback') and when not to ('only while the workflow is still DRAFT — after confirm_draft... create_workflow a new one instead'), with an alternative named.

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