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

Annotations establish a non-readonly, non-idempotent, non-destructive write; the description usefully adds that copying existing shots/steps/settings happens and that no credits are charged or brief mutated, which is real cost/side-effect context beyond the hints. The gap is that idempotentHint=false is never explained — nothing says whether repeated calls with the same brief create duplicate Automations or how a revision mismatch is handled.

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 tight sentences: the positive action first, then the exclusions. Every clause carries information an agent needs; no filler or restated title.

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 five-parameter required, non-idempotent mutation with no output schema, the description covers what is produced and what is not touched, but silent on return value, duplicate-call behavior, and revision-conflict semantics. Adequate as a minimum, with clear gaps for a state-changing tool.

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 60%: brief_id and expected_brief_revision carry no schema description at all, and the description adds nothing about them — notably no hint that expected_brief_revision enforces an optimistic-concurrency check. The phrase 'from a reviewed brief' loosely points at brief_id, but none of the five required parameters gain meaning from the description.

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 pairs a specific verb ('Save') with a precisely scoped resource ('one flow from a reviewed brief as a new reusable library Automation'), plus what gets carried over (current shots, dependent steps, settings). The word 'new' implicitly separates it from update_automation and get_automation without needing to name them.

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 origin condition is explicit ('from a reviewed brief'), which tells an agent the brief must already be reviewed before calling. The exclusion sentence ('does not modify the brief, generate media or charge credits') rules out expectations in adjacent domains, but no sibling tool is named as an alternative for non-reusable or in-place edits.

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