update_workflow

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

The description is highly transparent about the REPLACE-and-delete semantics, warning that existing items left out are DELETED. This directly contradicts the annotation destructiveHint=false, which claims no destructive behavior. Per the rubric, a description that contradicts an annotation receives a score of 1.

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 three sentences long, front-loaded with the purpose and the critical replacement warning, followed by actionable guidance. Every sentence earns its place, and the warning emoji draws appropriate attention to the destructive behavior.

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 tool with no output schema and a large input schema, the description provides the essential behavioral context: PATCH semantics, which fields are partial, how triggers/actions are replaced, and the safe workflow for editing one action. The agent has what it needs to call the tool correctly, aside from the annotation contradiction noted above.

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% at the top level, so the description must compensate. It does by explaining the partial-update semantics of name/order/enabled and the replace/update/create/delete semantics of actions and triggers. The nested schema descriptions already cover detailed subfields, so the description adds useful high-level meaning without repeating them.

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 ONE workflow (PATCH)', which clearly identifies the verb and resource. It distinguishes itself from siblings like create_workflow, delete_workflow, update_workflow_action, and update_workflow_trigger by focusing on the whole workflow object and its partial-update behavior.

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 clear context: name/order/enabled change only when passed, and triggers/actions replace the entire list. It explicitly instructs calling get_workflow first when editing one action. It does not explicitly name alternative tools like update_workflow_action or state when not to use this tool, so it falls short of a 5.

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