update_automation_step

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

With no annotations, the description carries the full burden. It discloses that the update is in-place (graph key stays stable, connections keep pointing) and includes the crucial prerequisite of disabling the automation first. This exceeds the minimum and provides actionable operational guidance.

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?

Three short sentences, all meaningful. The purpose is immediately clear, and the operational warning is front-loaded. No filler or redundant content.

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 a relatively simple update operation with full schema coverage and no output schema, the description covers the essential context: what is updated, the stability guarantee, and the required pre-condition. Missing is information about return value or what happens on failure, but that is 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?

The schema covers all parameters, but the description adds meaning by clarifying that 'config' is a full replacement object and that 'step_id' is the identifier for the step being updated. The HTTP method and path are also given, which helps an agent understand the operation semantics.

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 action ('Update a step in place'), the resource (a specific step within an automation), and the HTTP verb/method (PATCH). It also distinguishes this from sibling operations like add_automation_step and delete_automation_step by focusing on in-place update.

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 context: it's for updating an existing step, and it provides a key usage warning ('Disable the automation first if it is enabled'). It doesn't explicitly mention when to use it versus other step-management tools, but the purpose is clear enough.

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