timeline_add_clip

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

With no annotations, the description carries the behavioral burden. It explains trim-in/trim-out semantics and the out_point default, which adds value. However, it does not disclose potential side effects such as overlapping behavior, whether existing clips are overwritten, track validity requirements, or failure modes.

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 main statement is one concise sentence, followed by a compact argument list. Every line adds information and there is no filler or redundant repetition of schema titles.

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?

The description covers all parameters, the source of clip_id, and follow-up tool usage. It lacks explicit constraints around track existence, overlap policy, or timeline boundaries, but the presence of an output schema and the clear parameter explanations make it mostly complete for correct invocation.

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 Args section fully compensates. Every parameter is explained with units and meaning, clip_id sourcing is noted, and out_point's default to full bin duration is explicitly stated.

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 action: 'Place a bin clip onto a specific track at a given time position.' This clearly identifies the resource (bin clip, track, timeline), the operation (placement), and distinguishes it from sibling tools like timeline_move_clip or timeline_add_track.

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 description provides useful routing context by stating clip_id comes from bin_list_clips and explicitly recommends timeline_trim_clip for post-placement adjustments. It does not enumerate when not to use this tool versus other timeline editing tools, but the intended use case is clear.

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