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

The annotations declare readOnlyHint=false and destructiveHint=false, but the description goes further by disclosing that push shifts later clips and that insert reorders shots and closes gaps, which is important side effect information that the annotations do not convey. It still omits what happens on partial failure and whether the operation is undoable, so it falls short of a 5.

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 front-loaded with the core action, then enumerates the overlap modes in a compact inline list. The insert explanation is a long run-on clause, which is somewhat hard to parse, but no sentence 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?

For a mutation tool with six parameters, rich side-effect behavior, and no output schema, the description covers the risky overlap semantics well. However, it leaves the clipId versus clipIds relationship, default handling for start, and the response or failure behavior unexplained.

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 only 17%, so the description must compensate, and it does so for the highest-risk parameter: every overlap enum value is defined with concrete behavior. It also clarifies that with insert, clipIds moves multiple clips as one block in timeline order, with start anchoring the first; but clipId, trackId, and the clipId-vs-clipIds precedence still lack explanation, which keeps it at a 4.

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 opens with a specific verb and resource: 'Move a clip in time and/or to another track,' which tells an agent exactly what the operation does. It does not explicitly distinguish itself from adjacent siblings such as nudge_clips or slip_clip, so it falls short of a 5.

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 explains the semantics of each overlap mode in detail, which implies when each mode is appropriate, but it never states when to call move_clip instead of nudge_clips, slip_clip, or duplicate_clip. The date-less guidance is implied rather than explicit, and no prerequisites or exclusions are given.

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