update_workflow

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

Annotations only declare non-read-only, non-destructive; the description goes further by disclosing partial-update semantics, the optimistic-locking requirement on version, and the 412 conflict outcome. The '(admin)' marker additionally signals an elevated permission requirement. This is meaningful behavior beyond the annotations, though it omits what happens to omitted fields on failure and any rate/permission errors beyond 412.

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?

Two short sentences, front-loaded with the action and followed immediately by the operational constraints. 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?

For a mutation tool with no output schema and seven largely undocumented parameters, the description covers concurrency and partial-update behavior but leaves most field semantics and the expected response unspecified. It is adequate for a safe call but incomplete for confident use of the nested step/action structures.

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 only 14% across 7 parameters, so the description must compensate and largely does not. It explains version (already documented in the schema) and the partial-update rule, but name, type, workflowId, initialAction, and issueTypeResolutions are left undefined in both places.

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 ('Update a workflow') and adds the '(admin)' qualifier, so the agent knows the operation and its privilege level. It is not confused with update_workflow_action or delete_workflow, though it never names those siblings to sharpen the boundary.

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?

'Pass only the fields to change' tells the agent how to call it (partial update) and 'version is required for optimistic locking' gives a precondition, which is real usage guidance. However, it says nothing about when to choose this over update_workflow_action or create_workflow/delete_workflow.

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