move_arrangement_clip

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses that the move is implemented as copy-then-delete, that both steps are verified, and critically that a failed copy leaves the original in place (non-destructive failure mode). It also warns that indices shift after the move.

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?

Front-loads the core action, then layers side effects, a concrete example, and edge cases in clearly labeled segments. Every sentence earns its place and 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?

For a 3-param mutation tool with no annotations and no output schema, the description covers side effects, failure behavior, and post-move state well. It stops short of stating what a successful call returns (only 'both verified'), a minor gap.

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 0%, so the description must compensate, and it partially does: the example 'move_arrangement_clip(3, 2, 96.0)' fixes the positional order of the three required args, and 'new beat' establishes that time is in musical beats rather than seconds. track_index and clip_index remain only inferable from their names.

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 with scope: 'Move one Arrangement clip to a new beat.' It also implicitly distinguishes itself from sibling set_arrangement_clip_properties by noting the LOM exposes no setter for Clip.start_time, so this is the only way to reposition.

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?

Explains the condition under which this tool is required (no setter exists for start_time) and routes the agent to get_arrangement_clips for re-reading after index shifts. No explicit when-not guidance or named alternative for repositioning, but the context is clear.

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