CueFrame

Prepare Media

prepare_media

Idempotent

Prepare the perception artifact an authored edit needs BEFORE sighted review. Pass body.kind="subjectTrack" for face/active-speaker reframing, or body.kind="matte" for a true zPlane:"behind-subject" graphic. Pass body.intent {startSec,endSec} using SOURCE time (the media trim, not timeline time); it is required for mattes and strongly recommended for subject tracks so the prepared fact exactly matches the clip and quote. This is the supported product path — never accept a preview that silently flattens depth or ignores speaker tracking. Returns a fact receipt; with intent, poll get_media_facts using the same kind/window until exact.state is ready; without intent, omit all three filters and find the whole-source subjectTrack in facts until status is ready (failed is terminal). Existing pending/ready facts are reused without another charge.

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": {
      "mediaItemId": "<mediaItemId>",
      "body": "<body>"
    },
    "name": "prepare_media"
  }
}

Input Schema

Name	Required	Description
`body`	Yes	POST /media/:id/facts body.
`commandId`	No	Retry identity. A call repeated with the same commandId returns the first result instead of acting twice.
`mediaItemId`	Yes	mediaItemId (path).

Output Schema

Name	Required	Description
`factId`	No
`status`	No
`quotedUsd`	No
`alreadyExisted`	No	True when this exact fact was already pending or ready. Nothing was dispatched and nothing will be charged.

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedOct 28, 2026

addedInput schema / $defs

Added value: +{
+  "__schema0": {
+    "description": "Which enhancement to buy. `transcript` is NOT purchasable here — it is delivered by the transcription pipeline.",
+    "enum": [
+      "subjectTrack",
+      "matte"
+    ],
+    "type": "string"
+  },
+  "__schema1": {
+    "additionalProperties": false,
+    "description": "The SOURCE window. REQUIRED for `matte` (its cost scales with duration). OPTIONAL for `subjectTrack`: give a clip's source window to buy the track the render looks up for THAT clip, and pay only for its duration; omit it to detect the whole source.",
+    "properties": {
+      "endSec": {
+        "$ref": "#/$defs/__schema3"
+      },
+      "startSec": {
+        "$ref": "#/$defs/__schema2"
+      }
+    },
+    "required": [
+      "startSec",
+      "endSec"
+    ],
+    "type": "object"
+  },
+  "__schema2": {
+    "minimum": 0,
+    "type": "number"
+  },
+  "__schema3": {
+    "exclusiveMinimum": 0,
+    "type": "number"
+  },
+  "__schema4": {
+    "maxLength": 128,
+    "minLength": 1,
+    "type": "string"
+  }
+}

addedInput schema / properties / body / properties / intent / $ref
```
Added value: +"#/$defs/__schema1"
```
removedInput schema / properties / body / properties / intent / additionalProperties
```
Removed value: -false
```

removedInput schema / properties / body / properties / intent / description

Removed value: -"The SOURCE window. REQUIRED for `matte` (its cost scales with duration). OPTIONAL for `subjectTrack`: give a clip's source window to buy the track the render looks up for THAT clip, and pay only for its duration; omit it to detect the whole source."

removedInput schema / properties / body / properties / intent / properties

Removed value: -{
-  "endSec": {
-    "exclusiveMinimum": 0,
-    "type": "number"
-  },
-  "startSec": {
-    "minimum": 0,
-    "type": "number"
-  }
-}

removedInput schema / properties / body / properties / intent / required
```
Removed value: -[
-  "startSec",
-  "endSec"
-]
```
removedInput schema / properties / body / properties / intent / type
```
Removed value: -"object"
```
addedInput schema / properties / body / properties / kind / $ref
```
Added value: +"#/$defs/__schema0"
```

removedInput schema / properties / body / properties / kind / description

Removed value: -"Which enhancement to buy. `transcript` is NOT purchasable here — it is delivered by the transcription pipeline."

removedInput schema / properties / body / properties / kind / enum
```
Removed value: -[
-  "subjectTrack",
-  "matte"
-]
```
removedInput schema / properties / body / properties / kind / type
```
Removed value: -"string"
```
addedInput schema / properties / commandId / $ref
```
Added value: +"#/$defs/__schema4"
```
removedInput schema / properties / commandId / maxLength
```
Removed value: -128
```
removedInput schema / properties / commandId / minLength
```
Removed value: -1
```
removedInput schema / properties / commandId / type
```
Removed value: -"string"
```

Changed1 schema field changedOct 22, 2026

addedInput schema / properties / commandId

Added value: +{
+  "description": "Retry identity. A call repeated with the same commandId returns the first result instead of acting twice.",
+  "maxLength": 128,
+  "minLength": 1,
+  "type": "string"
+}

First observedOct 10, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Goes well beyond annotations by disclosing billing behavior ('pay only for its duration', 'reused without another charge'), a terminal failure state ('failed is terminal'), and the async receipt-and-poll contract. Annotations only declare idempotency and non-destructiveness; the cost/reuse/terminal-state semantics are the operationally critical details and are all surfaced here.

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 action and the kind branching, then intent, then the follow-up polling steps. Some sentences are overloaded (the kind/intent sentence packs three constraints) and the polling instructions add length, but nearly every clause carries actionable information, so little is wasted.

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 3-parameter async operation with an output schema, the description covers the decision (which kind), the required inputs and their time basis, the async completion path via get_media_facts, cost/reuse behavior, and terminal failure. Nothing an agent needs to call it and correctly follow up 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 coverage is 100%, so the schema already documents kind and intent, but the description adds real meaning: intent must be in SOURCE time (the trim, not timeline time) and why (so the prepared fact matches the clip and quote), plus the cost/required distinction between kinds. It does not clarify commandId (left to the schema) but that is a minor omission.

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

Purpose4/5

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

States a specific verb ('prepare') and resource ('perception artifact') and enumerates the two purchasable kinds, subjectTrack and matte, so the agent can tell it apart from get_media_facts (which is described as the polling companion). The framing is dense with domain jargon ('perception artifact', 'fact receipt', 'zPlane'), which slightly obscures what is actually being created.

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?

Explicitly states when to use each kind (subjectTrack for face/active-speaker reframing, matte for a behind-subject graphic), the timing constraint ('BEFORE sighted review'), and the follow-up path via get_media_facts with the same kind/window including the no-intent variant. It also names an anti-pattern to reject ('never accept a preview that silently flattens depth'), which is exactly the routing guidance an agent needs.

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

All CueFrame 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.