Skip to main content
Glama

Render a video still

video_still

Renders one frame of a scene at t seconds as a PNG at the scene's size: the way to look at a moment (just after a transition, mid-reveal, the last frame) before rendering the whole video. Costs 1 unit, plus a shot's price when the scene has shots (3 plus 1 for each 1.6 megapixels). It runs as a queued job: the answer is 202 with a job id at once, and GET /api/agents/jobs/ (or the MCP tool job) says when it is done and signs its files. A queued call is refused on the free plan with 402: its units buy only calls that answer at once, and queued jobs need the subscription. Returns still.png.

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": {
      "scene": "<scene>",
      "t": "<t>"
    },
    "name": "video_still"
  }
}

Input Schema

NameRequiredDescriptionDefault
tYesThe moment to draw, in seconds from the scene's start.
sceneYesA scene document written inline: output (size, frame rate, length), tracks of clips, optional cast and lines, audio and subtitles. Start from video_examples and read video_schema for every key.

Output Schema

NameRequiredDescriptionDefault
msNoMilliseconds the run took.
jobYesThe job id; the job tool reads it.
verbNoThe tool that made it.
filesNoFiles made, each with a name, type, size and a signed URL.
unitsNoUnits this call cost.
resultNoThe engine's own answer, a JSON document.
statusNoqueued when the job runs in the background.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": true,
      +  "properties": {
      +    "files": {
      +      "description": "Files made, each with a name, type, size and a signed URL.",
      +      "items": {
      +        "additionalProperties": {},
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "job": {
      +      "description": "The job id; the job tool reads it.",
      +      "type": "string"
      +    },
      +    "ms": {
      +      "description": "Milliseconds the run took.",
      +      "type": "number"
      +    },
      +    "result": {
      +      "description": "The engine's own answer, a JSON document."
      +    },
      +    "status": {
      +      "description": "queued when the job runs in the background.",
      +      "type": "string"
      +    },
      +    "units": {
      +      "description": "Units this call cost.",
      +      "type": "number"
      +    },
      +    "verb": {
      +      "description": "The tool that made it.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "job"
      +  ],
      +  "type": "object"
      +}
  2. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Adds a lot beyond the annotations: unit cost with the shot-price formula, asynchronous 202-plus-job-id behaviour, the 402 refusal on free plans, and the returned filename. The one thing not disclosed is whether a still is cached or re-rendered on repeat calls, which matters since idempotentHint=false. That is a real but narrow gap, so a 4 rather than a 5.

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-loaded with the purpose, then cost, then the async flow and the plan restriction — a sensible order with little waste. The cost sentence ('1 unit, plus a shot's price when the scene has shots (3 plus 1 for each 1.6 megapixels)') is dense enough to need a second read.

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?

Covers cost, latency model, polling path, a specific failure mode, and the return artifact, and an output schema exists to handle return shape. The single missing piece for a non-idempotent, billed render is whether repeating an identical call costs again or returns a cached still.

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

Parameters3/5

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

Schema coverage is 100%, so both parameters are already documented. The description reinforces t ('at t seconds') and the scene's role ('at the scene's size') but adds no format or construction guidance beyond what the schema says, so the baseline 3 applies.

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 ('Renders one frame of a scene at t seconds as a PNG at the scene's size') and positions itself against the whole-video path ('before rendering the whole video'), so an agent can separate it from video_render without opening a 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 a clear when-to-use rule: inspect a moment — just after a transition, mid-reveal, last frame — before committing to a full render. It also routes post-call polling to the job tool/endpoint and flags the free-plan case. It stops short of an explicit 'use video_render instead when you want the whole video' exclusion, but the implicit contrast is strong.

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.

Resources