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

Annotations are sparse (readOnlyHint=false, etc.), so the description carries the disclosure burden. It is explicit about atomicity, no render wait, rejection of the entire batch on errors, and that it saves but does not certify quality. This goes well beyond the annotations and gives the agent accurate expectations.

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 dense but efficient, front-loading the critical project-scoped and atomic nature. Every sentence adds value (retry, timeline semantics, rejection, quality disclaimer). It is longer than minimal, but the complexity of the tool justifies the length. No fluff, but slightly verbose compared to a two-sentence ideal.

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 batch-write tool with no output schema, the description is complete: it covers preconditions (get_edl, base_version), retry semantics, operation syntax, validation behavior, and the result (saves edit, does not certify quality). An agent has everything needed to call it correctly without guessing, even with only 25% schema coverage.

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% (only project_id). The description compensates fully: it explains operation_id format and constraints, base_version currency, the structure of each operation (action, layer, value?, id?), the meaning of each action (set replaces, upsert patches, reorder accepts ids), and the available layers. It also references get_edl for exact shapes, adding crucial meaning the schema lacks.

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 tool applies a complete group of ordinary edits atomically, scoped to an explicit project, and distinguishes itself from siblings like apply_short_edit_batches and individual add/set tools. It specifies the exact operations (set, upsert, remove, reorder) and their targets, leaving no ambiguity about what the tool does.

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?

Provides explicit prerequisites ('Read get_edl first; base_version must be current'), explains operation_id retry semantics, and states that times describe the resulting timeline. It also warns about atomic rejection on invalid fields/media, giving clear when-to-use guidance. While it doesn't explicitly contrast with siblings, the batch vs. single-edit distinction is implicit in the detailed operation list.

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