Skip to main content
Glama

get_recording_frame

Read-only

Copy one recorded frame to a new PNG in mcp_output/captures/, and return its path and, once the recording has stopped, the frame's simulation time.

Instructions

Copy one recorded frame to a new PNG in mcp_output/captures/, and return its path and, once the recording has stopped, the frame's simulation time.

Frames come from start_recording, which Kit writes itself as frame_00000.png and on in the session folder: with Kit on this machine you can also open them there, and with Kit on another this brings one here. Without session_dir it reads the last recording started since the Kit extension started, the running one included. A relative session_dir is read from this server's working folder, as start_recording and stop_recording give it. A frame Kit failed to capture comes back as an empty file; a frame number past the last is an error. For a picture of the scene now, use capture_viewport.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_recording_frame"
  }
}

Input Schema

NameRequiredDescriptionDefault
frame_indexNoThe frame's number, from 0
session_dirNoThe session folder as start_recording and stop_recording give it, relative to this server's working folder, or an absolute path on Kit's machine; the last recording when empty

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.4.1
    • changedInput schema / properties / session_dir / description
      Previous value: -"The session folder on Kit's machine, absolute or relative to Kit's working folder; the last recording when empty"New value: +"The session folder as start_recording and stop_recording give it, relative to this server's working folder, or an absolute path on Kit's machine; the last recording when empty"
  2. Changed1 schema field changedv0.2.3
    • changedInput schema / properties / session_dir / description
      Previous value: -"The session's folder; the last recording when empty"New value: +"The session folder on Kit's machine, absolute or relative to Kit's working folder; the last recording when empty"
  3. First observedv0.2.2

TDQS

A4.8/5.0
Behavior5/5

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

Annotations give readOnlyHint=true and openWorldHint=false, but the description adds substantive behavior the annotations cannot convey: the tool writes a new PNG into mcp_output/captures/, simulation time is only returned once recording has stopped, and a missed frame yields an empty file rather than an error. The relative-path resolution rule (read from this server's working folder, matching start_recording/stop_recording) is also disclosed.

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?

The core action and return values are front-loaded in sentence one, and later sentences are organized around frame provenance, path resolution, error cases, and the alternative tool. The middle sentence ("with Kit on this machine you can also open them there, and with Kit on another this brings one here") is slightly convoluted and could be tightened, but no sentence is filler.

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 a two-parameter tool with an output schema and annotations that already pin down safety, the description covers everything else an agent needs: source of frames, default session selection, path semantics, return values, and failure modes. Nothing material is left to inference.

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 baseline is 3, but the description goes beyond the schema by explaining the meaning of the empty session_dir default (the last recording started since the Kit extension started, including the running one) and how relative paths resolve on this machine versus Kit on another. That is real added semantics rather than a restatement of the parameter titles.

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 sentence gives a precise verb, resource and destination: "Copy one recorded frame to a new PNG in mcp_output/captures/, and return its path and, once the recording has stopped, the frame's simulation time." It also explicitly separates itself from the sibling capture_viewport ("For a picture of the scene now, use capture_viewport"), so an agent can choose between them without opening either 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?

It states when to use this tool versus the alternative (capture_viewport for live scenes), where frames originate (start_recording, frame_00000.png onward in the session folder), and what happens when session_dir is omitted. It also names two failure conditions — an empty file for a frame Kit failed to capture, and an error past the last frame — which is exactly the routing information an agent needs.

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