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

Annotations already declare readOnlyHint=false with destructiveHint=false, so the agent knows this is a non-destructive mutation. The description adds genuinely useful behavioral context by naming exactly what is preserved (slot position and clip length) versus what changes (source in-point), which is more than the annotations convey. It does not state whether the edit is undoable, whether negative delta is allowed, or what happens when the in-point would run past the source bounds — notable gaps for an edit operation.

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?

A single sentence, front-loaded with the effect ('Show a different part of the source in the same slot') and followed by the constraint and the parameter choice. Every clause carries information; there is no filler or restatement of the tool name.

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?

No output schema exists, so the description should stand on its own, and for a 4-parameter edit tool it covers the core semantics: what changes, what stays, and both ways to specify the new in-point. The remaining gaps — source-bound clamping, whether delta and in are mutually exclusive, and whether the operation is undoable — are the only things an agent would still be guessing at.

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 25% (just projectId is documented), so the description carries most of the burden and does it well: 'delta source seconds' clarifies that delta is measured in source time, not timeline time, and '(or to `in`)' clarifies that `in` is a target in-point and an alternative to delta. clipId is self-evident from the name. What is left unstated is whether both `in` and `delta` can be supplied at once or what happens if they conflict.

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 concrete verb+resource ('slip_clip': show a different part of the source in the same slot) and spells out the invariant (place and length kept) and the variable (in-point moves by delta or to `in`). That is a precise mechanical definition an agent can act on. It stops short of naming the confusable siblings (trim_clip, move_clip, nudge_clips, split_clip), so the differentiation is inferential rather than explicit.

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?

The mechanics (position and duration preserved, only the source in-point changes) implicitly tell an agent this is the right tool when the slot must stay fixed, which distinguishes it in principle from trimming and moving. However, no sibling is named and there is no explicit when-to-use / when-not-to-use statement despite a sibling list dense with near-neighbors. Usage guidance is derivable but not stated.

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