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

Annotations already declare destructiveHint=true and non-idempotent, but the description adds real behavioral context beyond them: the batch is all-or-nothing, writes are refused on a stale revision so user edits aren't overwritten, dryRun returns the summary without saving, and transcribe_captions is the one paid op (1 credit/file) gated by a quoteToken confirmation. It is fully consistent with the annotations.

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?

Front-loaded with the atomicity guarantee and op list, then the revision, dry-run, and cost/quote rules in the order an agent needs them. It is dense as a single block and would read better as a short list, but no sentence is filler.

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 destructive, atomic batch-write tool with a rich 22-variant op schema, the description covers atomicity, concurrency control, preview mode, cost confirmation, and even the return values (new revision and editorUrl) despite an output schema existing. Nothing an agent needs to invoke it safely 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 coverage is 83%, so the baseline is 3, and the description adds meaning on top: expectedRevision's role and conflict semantics, dryRun's preview behavior, quoteToken's origin, and an actual explanation of set_framing's focusX/focusY/zoom plus 'the source's pixel size'. It does not document per-op field ranges, but that is the schema's job here.

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 ('Apply a batch of timeline ops to a project') and then enumerates the exact op vocabulary the tool accepts, so an agent can tell instantly whether this is the write-side counterpart to video_project_get. It is clearly distinguished from sibling reads/exports.

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?

Gives concrete operational rules: pass expectedRevision from your last read, and on revision_conflict re-read the summary and rebuild the ops; use dryRun:true to validate without saving; for transcribe_captions show the quote before re-calling with quoteToken. It stops short of naming sibling alternatives to route between, but the when/when-not context is explicit.

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