AskEditor

Add media clip

add_timeline_clip

[write] Add a media clip from ONE of assetId or src, on the first free lane at startMs. items places a whole cut list in one save. Use to lay down footage, b-roll, images or music. Not for text, shapes or captions (use add_text, add_shape, add_caption_line), or to push later clips along (use insert_clip_ripple). Returns the changed clips' rows (with handles) and counts. The new clip's handle is in changed. Related: list_media, list_assets, trim_clip, set_clip_transform.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project_id": "<project_id>"
    },
    "name": "add_timeline_clip"
  }
}

Input Schema

Name	Required	Description
`src`	No	Media URL, instead of assetId; stock URLs are imported.
`kind`	No	Default the file's; video for a src.
`items`	No	Several clips; each takes the fields above.
`title`	No	Label (default the file name).
`track`	No	Lane, 0 = bottom (default); bumped up if occupied.
`width`	No	Source px (default the file's).
`height`	No	Source px (default the file's).
`assetId`	No	File id (list_media) or motion graphic id (list_assets).
`startMs`	No	Start, ms (default the timeline's end).
`durationMs`	No	Length, ms (default the file's; src 3000, image 4000).
`project_id`	Yes	The AskEditor project this acts on (from list_projects).
`srcDurationMs`	No	Source length, ms (default the file's).

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 2, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare write, open-world, non-idempotent and non-destructive behavior. The description adds useful operational detail: placement on the first free lane, bulk saving via items, and the return shape including changed clips, counts and the new clip handle. It does not clarify atomicity or partial-failure behavior for bulk items.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the write operation and core behavior, then covers usage, exclusions, return values and related tools. It is dense but every sentence contributes useful routing or invocation context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter nested write tool with no output schema, it supplies return-value information and relevant related tools. It leaves some ambiguity about how top-level clip fields behave when items is supplied, and about partial failure for bulk items.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: exactly one of assetId or src is needed, and items represents a whole cut list saved together. It still does not clarify how items interacts with the top-level clip fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Add a media clip.' It also defines scope with 'from ONE of assetId or src' and distinguishes what it is not for, so an agent can identify it as the timeline media-placement tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it ('lay down footage, b-roll, images or music') and when not to use it, with named alternatives for text, shapes, captions and ripple insertion. However, several named alternatives (add_shape, add_caption_line, insert_clip_ripple) are not present in the provided sibling-tool list, so parts of the routing guidance may be unreliable.

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

All AskEditor tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?