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

This description directly contradicts the annotations. The description says 'Update an existing automation,' a mutation, which is consistent with the mutation. However, the annotations include destructiveHint=true, and the description fails to disclose any destructive behaviors — e.g., whether changing template_id from a saved template to 'custom' would replace the content, or whether recipients will be overwritten wholesale. There is a contradiction: the description implies a straightforward partial update ('only include the fields you want to change') while the annotation marks it destructive. The description does not warn about irreversible or drastic side effects, and it does not articulate any behavioral ripple effects, so the safety profile in structured data is not echoed.

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 very short (one sentence), which is efficient for a tool with a rich schema. The sentence brings one useful behavioral fact. It is rear-loaded. It doesn't over-explain. Given the breadth of the schema, a bit more could be added, but structurally it's clean.

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 a rich object (13 params, nested object), has destructiveHint=true, and an output schema exists. The description completely ignores the output and does not warn about which fields, if omitted, will be reset versus preserved. It also doesn't explain the interplay with pending-email-templates for the recipients or the sender, or the condition for the nested custom object being required. On a complex mutating tool like this, the description is insufficient.

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 100% and many parameters have meaningful enum descriptions (frequency, date_text, time_format). The nested custom object is well documented (required fields, meaning of button_top, button_text), and the notion of template_id === 'custom' is explained in the schema. The description adds no new parameter meaning, but it does clarify the partial-update semantics. Given the schema is rich, the description doesn't need to restate parameter meanings, but it could have warned about how missing optional fields behave when not provided (whether they are reset to defaults or left untouched).

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 'Update an existing automation' has a generic verb ('update') that matches the risk of sibling tools like update_client, update_report, update_theme, etc. It does identify the resource (automation) and adds a small operational note about partial updates, but it doesn't distinguish it from the many other update_* tools that share the same verb. The subtle hint about only including fields to change is useful but the purpose is under-specified.

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?

There is no guidance on when to use this tool versus alternatives. It doesn't mention how it relates to create_automation, pause_automation, unpause_automation, or test_automation, nor when a partial-update call is preferred over an update. It states partial updates are possible but doesn't suggest a workflow (e.g., first list_automations, then update the specific automation).

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