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

With no annotations, the description takes on the burden of behavioral disclosure, and it does so well: it reveals that the layer is only drawn inside the window, keyframes are sampled relative to the block start, and moving/trimming re-anchors the intro. It also clarifies the frame coordinate space. It doesn't cover side effects like reversibility or permissions, but the core mutation behavior is transparent.

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 and front-loaded: it defines the block, explains the behavioral consequence, gives an intuitive analogy, scopes where it applies, and ends with a routing pointer. Every sentence carries information; none is redundant.

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?

Given that all four params are fully documented in the schema and there is no output schema, the description supplies the missing conceptual model needed to call the tool correctly. It covers frame timing, parent timeline context, applicability to leaf/group layers, and the embedded-reel alternative. The agent has everything needed to select and invoke this 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 coverage is 100%, so the baseline is 3. The description adds useful semantics beyond the schema by explaining that start/duration define the only visible window and that keyframes are relative to the block start. This clarifies the conceptual meaning of the parameters beyond their literal types.

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 states a specific verb-resource pair ('Set (or replace) a layer's timeline BLOCK') and defines the block as a [start, start+duration) window. It clearly differentiates from sibling tools, especially by explicitly directing users to move_band for embedded reels.

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?

It clearly explains when to use the tool: to make a layer 'start' at a point like an iMovie clip rather than existing for the whole composition. It also names the alternative (move_band) for embedded reels, though it doesn't contrast with other timeline-related siblings like set_duration or set_group_window.

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