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

Annotations already cover the safety profile (destructiveHint=true, idempotentHint=true), so the bar is lower, yet the description adds real context: revision checking via expectedRevision and the fact that dryRun is on by default, so an agent knows calls are non-mutating unless it flips the flag. It still doesn't say what is destroyed or how layer conflicts are resolved.

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 short sentences, action first, zero filler. Every clause (target semantics, revision check, dryRun default) carries distinct information.

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?

Output schema exists so return values aren't needed, and annotations cover the destructive/idempotent profile. However, for a 6-required-param destructive batch move at 17% schema coverage, the description omits the idempotencyKey requirement, the 1-500 item batch limit, and any note on layer conflict behavior.

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 17% (just projectId as 'UUID string'), so the description is expected to compensate. It partially does: 'explicit times and layers' maps to startSeconds/layerIndex, 'revision checked' maps to expectedRevision, and dryRun is explained. But idempotencyKey and workspaceId remain completely undocumented in both places.

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 (move) and resource (selected timeline items) plus the target semantics (explicit times and layers), which cleanly separates it from siblings like editor_items_remove or update_timeline_clip. It stops short of naming an alternative tool or contrasting scope, so sibling differentiation is left implicit.

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 when-to-use guidance and no routing to alternatives such as timeline_edit_preview or batch_update_timeline_clips, which operate on overlapping concepts. The 'dryRun previews by default' phrase hints at a preview-then-commit flow but never states the conditions under which this tool should be chosen.

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