Skip to main content
Glama

run_timeline_batch

Idempotent

Run MULTIPLE timeline-tool calls in ONE request, where a LATER step can reference a value produced by an EARLIER step in the SAME batch — the fix for 'split this clip, then move just the second half': you don't know the new second-half clip's id until AFTER the split has actually run, so normally that needs two separate turns. In a batch, give the split step a step_id (e.g. "step1"), and reference its result in a later step's args as a string like "$step1.timeline.tracks.0.clips.-1.id" (dotted path into that step's own JSON result; a numeric segment like -1 indexes into a list, -1 = the last item — the newest clip on a track after a split/add is always last). tracks.N here is ordered by (video/overlay tracks first, then audio; ascending index within each) — NOT by when the track was created — so tracks.0 reliably means 'the lowest-index video track' even if an empty leftover track exists elsewhere. Every step's result also carries new_clip_ids and removed_clip_ids (what that step created or removed), so "$step1.new_clip_ids.0" names the clip a split/add/duplicate made without any positional path. Still, prefer referencing a clip/track by its literal id once you have one (e.g. from an earlier step's own new_clip_ids, clip_ids or a job/<job_id>/timeline.txt call) over a tracks.N/clips.N positional path when you're not certain which position you mean — positional indexing is a convenience for the common 'the track/clip I just touched' case, not a stable general-purpose address. Every step's tool must be a real timeline tool name (job/<job_id>/timeline.txt first if you need to see a tool's exact result shape before referencing it). All-or-nothing: the first step that fails stops the whole batch immediately and later steps never run — check each entry in the response's step_results for where it stopped. Use this whenever a plan has TRUE ordering dependencies (step 2 needs data step 1 just created); for independent clips with no cross-references, add_clips_to_timeline is simpler.

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": {
      "job_id": "<job_id>",
      "steps": "<steps>"
    },
    "name": "run_timeline_batch"
  }
}

Input Schema

NameRequiredDescriptionDefault
stepsYes
fieldsNo
job_idYes
response_detailNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, but the description adds genuinely non-obvious execution semantics: all-or-nothing failure ('the first step that fails stops the whole batch immediately and later steps never run') and where to look for the stopping point ('step_results'). It also discloses that steps can remove clips via removed_clip_ids, which tempers the flat destructiveHint=false. It does not spell out whether re-running an identical batch is safe, so the idempotency claim is left unverified.

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

Conciseness3/5

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

Key information is front-loaded: the batch premise, the motivating example, and the reference syntax all come before caveats. However, the body is a dense single block with heavy parenthetical nesting (track ordering, positional-index warnings, new_clip_ids short-circuit) that could be split into short labeled points; the positional-path caveat is restated at length rather than stated once.

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 complex multi-step orchestration tool with no output schema and zero schema description coverage, the description covers the essentials: step shape, cross-step referencing, failure semantics, and where results appear. Gaps remain around the `fields` and `response_detail` controls and the shape of the batch response beyond `step_results`, but nothing an agent needs to make a correct first call is missing.

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 0% and `steps` is an untyped array of empty objects, so the description carries the full burden for the hardest parameter — and does so well, explaining `tool`, `step_id`, and the dotted `$step1.timeline.tracks.0.clips.-1.id` reference syntax including what a numeric segment means. The trade-off is that `fields` and `response_detail` are never mentioned, leaving two of four parameters opaque in both schema and prose.

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?

The first clause names a specific verb and resource ('Run MULTIPLE timeline-tool calls in ONE request') and immediately states the distinguishing capability: later steps can reference values produced by earlier steps in the same batch. It also names the simpler alternative (add_clips_to_timeline) for the non-dependent case, so an agent can tell it apart from ordinary single-tool calls 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 Guidelines5/5

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

Explicit when-to-use: 'whenever a plan has TRUE ordering dependencies (step 2 needs data step 1 just created)'. Explicit when-not: 'for independent clips with no cross-references, add_clips_to_timeline is simpler.' It also gives a prerequisite step ('job/<job_id>/timeline.txt first if you need to see a tool's exact result shape'). The conditions are concrete, not inferred.

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.