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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses validation-before-write behavior, that error-severity findings result in valid=false and created=false, and that successful writes return advisory findings. This adds significant context about the tool's execution and side effects, fully compensating for the absence of such detail 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?

The description is a single paragraph but efficiently front-loads the core purpose and then adds essential details on validation, publishing, and alternatives. Every sentence adds value, though it is slightly long; it avoids redundancy and remains well-structured.

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 complexity (nested objects, output schema exists, three parameters), the description is complete. It covers the primary use case, validation semantics, publish behavior, and points to the definition schema. The return structure is covered by the output schema, so nothing critical 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?

The schema already covers all parameters with 100% coverage, so the baseline is 3. The description adds valuable guidance for the 'definition' parameter: 'Fetch the exact JSON Schema it must satisfy with get_workflow_definition_schema and author against it (or copy an existing one with the get_*_version tool).' This goes beyond the schema's bare description and helps the agent use the 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?

The description clearly states the tool's purpose: 'add a new version to an EXISTING workflow (by workflow_id) to evolve a workflow you already created.' It uses a specific verb and resource, and explicitly distinguishes itself from create_workflow for brand-new workflows, making its scope 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?

It provides explicit usage context: author against the schema from get_workflow_definition_schema, use for existing workflows, and explicitly says 'For a brand-new workflow, use create_workflow.' It also explains the publish option and how to publish later with publish_workflow, offering clear alternatives and conditions.

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