CueFrame

Get Composition

get_composition

Read-onlyIdempotent

Read a compact structural composition view by default, preserving observed ETag, authority metadata, clip timing, token values and source pins without large HTML bodies. Ordinary exact-ETag reads can omit includeDependencies. With includeDependencies=true, compact returns a dependency key/size index, not executable tokens; these tokens can contain full sources. Request explicit dependencyKeys for exact selected tokens, or response:"full" for all tokens. Selection does not establish a sufficient operation basis. Use clipIds:[id] with response:"full" for complete exact selected sources; unknown IDs are refused. Use response:"full" without clipIds for the original full backend JSON. Local response/clipIds/dependencyKeys arguments never reach the backend. READ BACK a composition as JSON — the edit itself: tracks, clips, card HTML, reframe segments, captions, markers, format. This is what create_render encodes, so it is also what you hand to validate_composition (which needs a full inline composition body), what you diff after an edit, and what you archive/share so someone else can re-render the SAME video. Read-only and free. Authoring stays op-based (apply_composition) — do not round-trip this object back as a write. A composition too large for routine model context can be read selectively with clipIds and response:"full"; the compact view explicitly identifies omitted source bodies. Defaults to the project's ACTIVE composition; pass compositionId to read a specific one (the same id apply_composition takes as composition_id, and preview_frame / create_render take as compositionId) so an A/B variant can be read back, not just written. The result includes the exact HTTP etag string; copy it to apply_composition.body.if_match (the numeric revision is not an ETag). In a compose session this reads the session's scratch, the composition its edits, previews and renders target. Pass includeDependencies="true" on a v1 guarded endpoint to read composition_id, revision and dependency tokens. With componentExecutionVersions=["3","4"], this envelope also returns expectedBrandIdentity from the persisted project authority; carry it unchanged into the matching negotiated write. Preserve those observed tokens when authoring; never refresh the basis to hide a conflict. BOTH shapes carry needsUpgrade when clips are stored in a retired form (unpinned or TSX component placements, removed primitives): each entry names the clipId, the kind and, when one exists, the native successor pin — move those with repin_component and rebuild the rest with create_component; such a composition will not save or render as-is. Absent when nothing needs upgrading.

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>"
    },
    "name": "get_composition"
  }
}

Input Schema

Name	Required	Description
`clipIds`	No	Read only these exact clip IDs. With response full their complete sources are returned. Unknown and duplicate IDs are refused. Omit for all clips.
`response`	No	MCP response view. Default compact omits repeated source bodies. Full returns the complete backend receipt or requested sources. This does not change the saved composition.
`projectId`	Yes	projectId (path).
`session_id`	No	Compose-session id: read that session's SCRATCH composition (what the session has been editing) instead of the active one. Mutually exclusive with `compositionId`. An unknown, foreign or scratch-less session is a 404, never the active composition.
`compositionId`	No	Read a SPECIFIC composition instead of the project's active one. Omit it and the active composition is returned. Pairs with `composition_id` on the apply op: an edit you can make to a second composition is one you can read back.
`dependencyKeys`	No	Select these exact existing dependency keys from includeDependencies=true. Tokens are returned byte-for-byte; unknown or duplicate keys are refused. This selection does not establish that the basis is sufficient for an operation.
`includeDependencies`	No	Return the immutable composition identity, project revision and shared v1 dependency expectations alongside the composition.
`componentExecutionVersions`	No	The component execution versions this reader accepts, one parameter per version: 3, or 3 and 4 (native placements). Absent readers accept only the historical protocol.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedOct 28, 2026

addedInput schema / $defs

Added value: +{
+  "__schema0": {
+    "anyOf": [
+      {
+        "const": "3",
+        "type": "string"
+      },
+      {
+        "items": false,
+        "maxItems": 2,
+        "minItems": 2,
+        "prefixItems": [
+          {
+            "$ref": "#/$defs/__schema1"
+          },
+          {
+            "$ref": "#/$defs/__schema2"
+          }
+        ],
+        "type": "array"
+      }
+    ]
+  },
+  "__schema1": {
+    "const": "3",
+    "type": "string"
+  },
+  "__schema2": {
+    "const": "4",
+    "type": "string"
+  },
+  "__schema3": {
+    "items": {
+      "$ref": "#/$defs/__schema4"
+    },
+    "minItems": 1,
+    "type": "array"
+  },
+  "__schema4": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "__schema5": {
+    "enum": [
+      "compact",
+      "full"
+    ],
+    "type": "string"
+  },
+  "__schema6": {
+    "items": {
+      "$ref": "#/$defs/__schema7"
+    },
+    "maxItems": 2048,
+    "minItems": 1,
+    "type": "array"
+  },
+  "__schema7": {
+    "maxLength": 256,
+    "minLength": 1,
+    "type": "string"
+  }
+}

addedInput schema / properties / clipIds

Added value: +{
+  "$ref": "#/$defs/__schema3",
+  "description": "Read only these exact clip IDs. With response full their complete sources are returned. Unknown and duplicate IDs are refused. Omit for all clips."
+}

addedInput schema / properties / componentExecutionVersions / $ref
```
Added value: +"#/$defs/__schema0"
```

removedInput schema / properties / componentExecutionVersions / anyOf

Removed value: -[
-  {
-    "const": "3",
-    "type": "string"
-  },
-  {
-    "items": false,
-    "maxItems": 2,
-    "minItems": 2,
-    "prefixItems": [
-      {
-        "const": "3",
-        "type": "string"
-      },
-      {
-        "const": "4",
-        "type": "string"
-      }
-    ],
-    "type": "array"
-  }
-]

addedInput schema / properties / componentExecutionVersions / default
```
Added value: +[
+  "3",
+  "4"
+]
```

addedInput schema / properties / dependencyKeys

Added value: +{
+  "$ref": "#/$defs/__schema6",
+  "description": "Select these exact existing dependency keys from includeDependencies=true. Tokens are returned byte-for-byte; unknown or duplicate keys are refused. This selection does not establish that the basis is sufficient for an operation."
+}

addedInput schema / properties / response

Added value: +{
+  "$ref": "#/$defs/__schema5",
+  "description": "MCP response view. Default compact omits repeated source bodies. Full returns the complete backend receipt or requested sources. This does not change the saved composition."
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "anyOf": [
+    {
+      "additionalProperties": {},
+      "properties": {
+        "response": {
+          "const": "compact",
+          "type": "string"
+        }
+      },
+      "required": [
+        "response"
+      ],
+      "type": "object"
+    },
+    {
+      "additionalProperties": {},
+      "description": "Verbatim backend JSON object, or an explicitly identified full selected-clip view.",
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    }
+  ],
+  "type": "object"
+}

Changed1 schema field changedOct 22, 2026

addedInput schema / properties / session_id

Added value: +{
+  "description": "Compose-session id: read that session's SCRATCH composition (what the session has been editing) instead of the active one. Mutually exclusive with `compositionId`. An unknown, foreign or scratch-less session is a 404, never the active composition.",
+  "type": "string"
+}

Changed4 schema fields changedOct 15, 2026

addedInput schema / properties / componentExecutionVersions / anyOf

Added value: +[
+  {
+    "const": "3",
+    "type": "string"
+  },
+  {
+    "items": false,
+    "maxItems": 2,
+    "minItems": 2,
+    "prefixItems": [
+      {
+        "const": "3",
+        "type": "string"
+      },
+      {
+        "const": "4",
+        "type": "string"
+      }
+    ],
+    "type": "array"
+  }
+]

removedInput schema / properties / componentExecutionVersions / const
```
Removed value: -"3"
```

changedInput schema / properties / componentExecutionVersions / description

Previous value: -"Explicit accepted saved component execution protocol. Absent readers accept only the historical protocol."New value: +"The component execution versions this reader accepts, one parameter per version: 3, or 3 and 4 (native placements). Absent readers accept only the historical protocol."

removedInput schema / properties / componentExecutionVersions / type
```
Removed value: -"string"
```

First observedOct 10, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Far exceeds the annotations: it discloses that local response/clipIds/dependencyKeys never reach the backend, that unknown/duplicate IDs are refused, that an unknown or foreign session is a 404 rather than a fallback to active, that compact explicitly marks omitted source bodies, and that needsUpgrade blocks save/render with a named successor pin. It also states the cost profile ('read-only and free') and the ETag→if_match carry rule, which the annotations do not cover.

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?

Front-loaded with the core behavior, but it is a wall of text with real redundancy: the clipIds+response:"full" recipe appears three times and the 'selection does not establish a sufficient operation basis' caveat is stated twice. Splitting the ETag/if_match and needsUpgrade rules into their own sentences would make it scannable; as written, some sentences do not earn their place.

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?

Given 8 params, an output schema, and full read-only annotations, the definition covers everything an agent needs: defaulting behavior, session-scratch semantics, refusal modes, the ETag contract, and the upgrade-blocking condition. Return-shape detail is rightly deferred to the output schema.

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 baseline is 3; the description still adds real meaning — compositionId defaults to the ACTIVE composition and maps to apply_composition's composition_id / preview_frame / create_render's compositionId, includeDependencies returns identity+revision+expectedBrandIdentity, and dependencyKeys selection 'does not establish a sufficient operation basis'. Slightly dense phrasing keeps it off a 5, but the cross-tool id mapping is genuinely beyond the schema.

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+resource ('Read a compact structural composition view') and enumerates the exact content it returns (tracks, clips, card HTML, reframe segments, captions, markers, format, ETag, source pins). It explicitly separates itself from the write path ('do not round-trip this object back as a write → apply_composition'), so an agent can distinguish read from mutate 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?

Gives concrete when-to-use routing: omit includeDependencies for ordinary exact-ETag reads, use clipIds+response:"full" for large compositions or complete selected sources, response:"full" without clipIds for the original backend JSON, includeDependencies="true" on v1 guarded endpoints, componentExecutionVersions with expectedBrandIdentity for negotiated writes. It also names the consumers (validate_composition, create_render, diff-after-edit, archive/share) so the agent knows the downstream step.

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.