Skip to main content
Glama

Trim a Playground clip

playground_video_trim
Idempotent

Cut a finished video node to [startSeconds, endSeconds] on the server. Creates a "Clip" (video-result) node wired from the source, as the in-app Clip tool does, and queues the existing FFmpeg film worker, which cuts the stored clip (re-encoded, frame accurate) and attaches the MP4 to that node. The range must be at least 0.2 s and inside the clip; the worker re-checks it against the probed duration. The source must be a finished clip in this project's storage. Free: no credits are spent. Revision checked and idempotent. Returns immediately; poll playground_run_delivery with the returned runId (every ≥30 s) until verified, or read the Clip node's generated URL with playground_node_get.

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": {
      "projectId": "<projectId>",
      "videoNodeId": "<videoNodeId>",
      "expectedRevision": "<expectedRevision>",
      "idempotencyKey": "<idempotencyKey>",
      "startSeconds": "<startSeconds>",
      "endSeconds": "<endSeconds>"
    },
    "name": "playground_video_trim"
  }
}

Input Schema

NameRequiredDescriptionDefault
titleNoHuman-readable label to display for this item in Playground.
projectIdYesID of the Playground project chosen for this task; obtain it from project creation, an explicit project link or current context.
endSecondsYesEnd of the retained clip in seconds; must be later than startSeconds.
videoNodeIdYesExisting canvas video node ID containing the source video.
startSecondsYesStart of the retained clip in seconds from the source video’s beginning.
idempotencyKeyYesUnique key for this request; reuse only when retrying the identical request after a lost response. Use a new key after quoting or changing inputs.
expectedRevisionYesCurrent canvas revision from canvas_read; on revision_conflict, read again and rebuild the change.

Output Schema

NameRequiredDescriptionDefault
pollYes
errorNo
runIdYes
statusYes
replayedYes
revisionYes
canvasUrlYes
onFailureYes
clipNodeIdYes
endSecondsYes
sourceNodeIdYes
startSecondsYes
conversationIdYes
sourceVideoUrlYes
retry_after_secondsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations, which only mark it as non-read-only, idempotent, closed-world and non-destructive. The description discloses the side effects (creates a new node, queues the FFmpeg film worker, re-encodes frame-accurately, attaches MP4 to the new node), validation behavior (minimum 0.2 s, range must be inside the clip, worker re-checks against probed duration), revision/idempotency handling, and the asynchronous return-then-poll contract.

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

Conciseness4/5

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

Front-loads the action, then mechanism, constraints, cost, and post-call workflow in a tight sequence with no filler paragraphs. A few clauses ('as the in-app Clip tool does', 're-encoded, frame accurate') are explanatory color rather than strictly operational, but nothing is redundant enough to warrant trimming.

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

Completeness5/5

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

For an async mutation with an output schema, the definition supplies everything an agent needs to call it correctly: source validity, numeric bounds, revision-conflict guidance, cost, and the exact polling path and cadence (≥30 s) plus an alternative read route via playground_node_get. Return-value shape is covered by the output schema, so its absence from the description is not a gap.

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 coverage is 100%, so the schema already documents all seven parameters and the baseline is 3. The description adds meaning the schema does not: the minimum 0.2 s span, the requirement that the range lie inside the clip, that the range is re-validated server-side against the probed duration, and that expectedRevision drives a revision check — raising it above baseline.

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 concrete verb and resource ('Cut a finished video node to [startSeconds, endSeconds] on the server') and immediately contrasts with alternatives by describing the output artifact: a new 'Clip' (video-result) node wired from the source. An agent can distinguish this from analyze/extract-frames/quote siblings without opening any schema.

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?

Gives clear preconditions ('The source must be a finished clip in this project's storage') and follow-up routing ('poll playground_run_delivery ... or read the Clip node's generated URL with playground_node_get'), plus a cost signal ('Free: no credits are spent') that implicitly steers away from paid quote tools. It stops short of explicitly naming a sibling alternative or an exclusion case, so it is strong context rather than a full when/when-not matrix.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.