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

Beyond the annotations, it discloses that the write is atomic, that invalid fields or media reject the whole batch, that timestamps are interpreted against the resulting program timeline, and that saving neither renders nor certifies output. Those are genuinely useful traits an agent cannot get from readOnlyHint/destructiveHint alone. The 'stable retry operation ID' phrasing sits in mild tension with idempotentHint=false but is not an outright contradiction, since retry deduplication is narrower than general idempotency.

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?

Four compact sentences with no filler, and the atomic-save claim plus base-version constraint are front-loaded. The middle sentence is dense but each clause maps to a real parameter or behavior. Slight compression ('Times refer to the resulting program timeline') costs a moment of parsing.

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 only coarse annotations, it covers atomicity, rejection behavior, param roles, and the post-save state boundary (no render, no certification). What remains unstated is the shape of a successful response (e.g., resulting version) and how conflicts on base_version surface, but nothing an agent needs to invoke it correctly is missing.

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 25%, so the description has to carry weight, and it does: base_version is framed as optimistic concurrency ('against the current base version'), operation_id as a stable retry key, and the operations array's action/value semantics are explained (complete layer value, item merged by ID, ordered insert IDs). project_id is left to the schema, which already documents it thoroughly.

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 uses a specific verb and resource ('Atomically saves a group of edit operations against the current base version') and spells out the four operation modes (set complete layers, upsert, remove, reorder). An agent can tell this is the batch-write path for layer edits. It never names a sibling such as apply_short_edit_batches or the individual set_* tools, so differentiation is left to inference.

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 explicit when-to-use or when-not-to-use guidance, and no comparison to the many single-purpose siblings (set_speed, set_frame, add_text, apply_short_edit_batches). The clause describing operation modes is mechanics, not routing advice. An agent must infer from the batch/atomicity wording that this is the multi-edit path.

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