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

With no annotations, the description carries the full burden and does well: it discloses the ripple side effect ('pushing whatever else is later on that track to the right'), the precise failure condition, and that placeholders get an independent prompt copy. It omits whether the operation is undoable and how expectedVersion conflicts surface, which an agent calling a mutating timeline tool would benefit from knowing.

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?

Dense but front-loaded, with the default behavior stated before the override options and the failure condition parenthetically scoped. The single long run-on sentence is slightly harder to parse than it needs to be, 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 mutating timeline tool with no annotations and no output schema, the description covers the essential behaviors: placement default, ripple effect, failure mode, and placeholder copy semantics. Remaining gaps are the meaning of expectedVersion and whether the new clip's identifier is returned, which matters since there is no output schema.

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 0%, so the description must compensate, and it only partially does: trackId and startMs get clear meaning ('different track of the same type', 'place it elsewhere'). The three required parameters — itemId, projectId, and especially expectedVersion (apparently optimistic concurrency) — receive no explanation anywhere, leaving a real gap.

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 ('Duplicate a timeline clip') and immediately scopes the resource set ('media or placeholder, not a transition'), which cleanly separates it from siblings like timeline.split_item, timeline.move_item, and timeline.add_transition.

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?

Explicitly describes the default behavior (same track, immediately after itself) and tells the agent exactly which parameters to use to deviate from it ('Pass trackId to duplicate onto a different track of the same type, and/or startMs to place it elsewhere'). It does not name alternate tools for related intents (e.g., split_item vs duplicate, or add_placeholder for creating new items), so routing guidance is strong but not complete.

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