CueFrame

Compose

compose

Start an async Director compose job: it authors an ensemble of full composition candidates, verifies each, and saves the winner to the project. Body must set EXACTLY ONE source (mutually exclusive): briefId — author FROM a persisted Brief (the PLANNED path: create_brief first; every Brief field is honored or the compose is refused loudly naming the field); fromComposition: true — author from the project's CURRENT composition (the GENERAL path: seed it with apply_composition first — your media clips are the intent, and any graphics you authored are CARRIED VERBATIM as locked clips the Director authors around, never re-authors or drops); or suggestionId — author from an AI clip suggestion (the CLIPPING path, paired with suggest_briefs). Returns { composeJobId, status, streamUrl }. Then call wait_job(kind="compose", id=composeJobId, projectId=...) to block until the winner is selected.

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

Input Schema

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

Output Schema

Name	Required	Description
`status`	No	queued = normal; failed = startup failed and the job is already terminal (the SSE stream will emit a single `job_failed` frame and close).
`projectId`	No
`streamUrl`	No	Relative SSE endpoint to stream this job's events (per compose-api-contract.md).
`composeJobId`	No	Opaque compose job id; pass to the SSE stream URL.
`reconciliationRequired`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed58 schema fields changedOct 28, 2026

addedInput schema / $defs

Added value: +{
+  "__schema0": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "__schema1": {
+    "description": "Reuse the project's current composition as the compose starting point (critique-retry path). The Director RE-AUTHORS graphics: if the current composition is client-authored and contains graphic clips (overlay/component/card), the request is refused (validation_error naming the clips) — render it verbatim with create_render instead. The director's own output (critique-retry) is exempt.",
+    "type": "boolean"
+  },
+  "__schema10": {
+    "description": "Structured critique block (per compose-api-contract.md decision #11). Capped at 2KB total; per-criterion blocks capped at 500 chars.",
+    "maxLength": 2000,
+    "type": "string"
+  },
+  "__schema11": {
+    "description": "Pointer to the prior compose job this run iterates on. Surfaced on the resulting compose job as baselineComposeJobId.",
+    "type": "string"
+  },
+  "__schema12": {
+    "description": "Ensemble size, 1–5. Defaults to one; explicit multi-candidate runs divide the job budget across candidates and admit at most two concurrently. A held editorial checkpoint always uses one candidate.",
+    "maximum": 5,
+    "minimum": 1,
+    "type": "integer"
+  },
+  "__schema13": {
+    "description": "Per-job budget cap (USD). Clamped at the route against the org's composeMaxBudgetUsdPerJob setting.",
+    "exclusiveMinimum": 0,
+    "type": "number"
+  },
+  "__schema14": {
+    "description": "Composite-score accept threshold. Server default per contract.",
+    "maximum": 10,
+    "minimum": 0,
+    "type": "number"
+  },
+  "__schema15": {
+    "description": "Deterministic seed for replay.",
+    "maximum": 9007199254740991,
+    "minimum": -9007199254740991,
+    "type": "integer"
+  },
+  "__schema16": {
+    "description": "Opaque caller token that disambiguates intentional same-critique retries. Without it, identical (project, sug, seed, critique) tuples deduplicate; with it, retries create a fresh execution.",
+    "maxLength": 64,
+    "type": "string"
+  },
+  "__schema17": {
+    "description": "Opt-in checkpoint gates. Each named stage pauses the compose at its boundary (status → awaiting_input) for client review via resume. Absent/empty ⇒ fully autonomous. Non-empty ⇒ the run is a single spine.",
+    "items": {
+      "$ref": "#/$defs/__schema18"
+    },
+    "maxItems": 3,
+    "type": "array"
+  },
+  "__schema18": {
+    "enum": [
+      "content",
+      "layout",
+      "motion"
+    ],
+    "type": "string"
+  },
+  "__schema19": {
+    "maxLength": 128,
+    "minLength": 1,
+    "type": "string"
+  },
+  "__schema2": {
+    "description": "Compose from a persisted Brief (create_brief) — the intent-first door: every Brief field is HONORED or the request is refused loudly naming the field (window from beat moment-pinning; seeded graphics carried VERBATIM as locked clips; exclusions enforced; locale + caption emphasis threaded to the Director). Exactly ONE of suggestionId | fromComposition | briefId.",
+    "minLength": 1,
+    "type": "string"
+  },
+  "__schema3": {
+    "additionalProperties": {
+      "$ref": "#/$defs/__schema8"
+    },
+    "description": "Optional format override. Phase 2 ignores this — format precedence is project.compositionFormat → 9:16 fhd 30fps default.",
+    "properties": {
+      "aspectRatio": {
+        "$ref": "#/$defs/__schema4"
+      },
+      "fps": {
+        "$ref": "#/$defs/__schema5"
+      },
+      "platform": {
+        "$ref": "#/$defs/__schema7"
+      },
+      "resolution": {
+        "$ref": "#/$defs/__schema6"
+      }
+    },
+    "required": [
+      "aspectRatio"
+    ],
+    "type": "object"
+  },
+  "__schema4": {
+    "enum": [
+      "16:9",
+      "9:16",
+      "1:1",
+      "4:5"
+    ],
+    "type": "string"
+  },
+  "__schema5": {
+    "anyOf": [
+      {
+        "const": 24,
+        "type": "number"
+      },
+      {
+        "const": 25,
+        "type": "number"
+      },
+      {
+        "const": 30,
+        "type": "number"
+      },
+      {
+        "const": 60,
+        "type": "number"
+      }
+    ]
+  },
+  "__schema6": {
+    "enum": [
+      "hd",
+      "fhd",
+      "4k"
+    ],
+    "type": "string"
+  },
+  "__schema7": {
+    "type": "string"
+  },
+  "__schema8": {},
+  "__schema9": {
+    "description": "RequestScope discriminated union (per compose-api-contract.md). Editor-only scopes (captions/overlay-track/broll/overlay-instance/segment) require an editor-session token; API tokens get 403 on those."
+  }
+}

addedInput schema / properties / body / properties / briefId / $ref
```
Added value: +"#/$defs/__schema2"
```

removedInput schema / properties / body / properties / briefId / description

Removed value: -"Compose from a persisted Brief (create_brief) — the intent-first door: every Brief field is HONORED or the request is refused loudly naming the field (window from beat moment-pinning; seeded graphics carried VERBATIM as locked clips; exclusions enforced; locale + caption emphasis threaded to the Director). Exactly ONE of suggestionId | fromComposition | briefId."

removedInput schema / properties / body / properties / briefId / minLength
```
Removed value: -1
```
removedInput schema / properties / body / properties / briefId / type
```
Removed value: -"string"
```
addedInput schema / properties / body / properties / budgetUsd / $ref
```
Added value: +"#/$defs/__schema13"
```

removedInput schema / properties / body / properties / budgetUsd / description

Removed value: -"Per-job budget cap (USD). Clamped at the route against the org's composeMaxBudgetUsdPerJob setting."

removedInput schema / properties / body / properties / budgetUsd / exclusiveMinimum
```
Removed value: -0
```
removedInput schema / properties / body / properties / budgetUsd / type
```
Removed value: -"number"
```
addedInput schema / properties / body / properties / clientNonce / $ref
```
Added value: +"#/$defs/__schema16"
```

removedInput schema / properties / body / properties / clientNonce / description

Removed value: -"Opaque caller token that disambiguates intentional same-critique retries. Without it, identical (project, sug, seed, critique) tuples deduplicate; with it, retries create a fresh execution."

removedInput schema / properties / body / properties / clientNonce / maxLength
```
Removed value: -64
```
removedInput schema / properties / body / properties / clientNonce / type
```
Removed value: -"string"
```
addedInput schema / properties / body / properties / critique / $ref
```
Added value: +"#/$defs/__schema10"
```

removedInput schema / properties / body / properties / critique / description

Removed value: -"Structured critique block (per compose-api-contract.md decision #11). Capped at 2KB total; per-criterion blocks capped at 500 chars."

removedInput schema / properties / body / properties / critique / maxLength
```
Removed value: -2000
```
removedInput schema / properties / body / properties / critique / type
```
Removed value: -"string"
```
addedInput schema / properties / body / properties / format / $ref
```
Added value: +"#/$defs/__schema3"
```
removedInput schema / properties / body / properties / format / additionalProperties
```
Removed value: -{}
```

removedInput schema / properties / body / properties / format / description

Removed value: -"Optional format override. Phase 2 ignores this — format precedence is project.compositionFormat → 9:16 fhd 30fps default."

removedInput schema / properties / body / properties / format / properties

Removed value: -{
-  "aspectRatio": {
-    "enum": [
-      "16:9",
-      "9:16",
-      "1:1",
-      "4:5"
-    ],
-    "type": "string"
-  },
-  "fps": {
-    "anyOf": [
-      {
-        "const": 24,
-        "type": "number"
-      },
-      {
-        "const": 25,
-        "type": "number"
-      },
-      {
-        "const": 30,
-        "type": "number"
-      },
-      {
-        "const": 60,
-        "type": "number"
-      }
-    ]
-  },
-  "platform": {
-    "type": "string"
-  },
-  "resolution": {
-    "enum": [
-      "hd",
-      "fhd",
-      "4k"
-    ],
-    "type": "string"
-  }
-}

removedInput schema / properties / body / properties / format / required
```
Removed value: -[
-  "aspectRatio"
-]
```
removedInput schema / properties / body / properties / format / type
```
Removed value: -"object"
```
addedInput schema / properties / body / properties / fromComposition / $ref
```
Added value: +"#/$defs/__schema1"
```

removedInput schema / properties / body / properties / fromComposition / description

Removed value: -"Reuse the project's current composition as the compose starting point (critique-retry path). The Director RE-AUTHORS graphics: if the current composition is client-authored and contains graphic clips (overlay/component/card), the request is refused (validation_error naming the clips) — render it verbatim with create_render instead. The director's own output (critique-retry) is exempt."

removedInput schema / properties / body / properties / fromComposition / type
```
Removed value: -"boolean"
```
addedInput schema / properties / body / properties / holdAt / $ref
```
Added value: +"#/$defs/__schema17"
```

removedInput schema / properties / body / properties / holdAt / description

Removed value: -"Opt-in checkpoint gates. Each named stage pauses the compose at its boundary (status → awaiting_input) for client review via resume. Absent/empty ⇒ fully autonomous. Non-empty ⇒ the run is a single spine."

removedInput schema / properties / body / properties / holdAt / items

Removed value: -{
-  "enum": [
-    "content",
-    "layout",
-    "motion"
-  ],
-  "type": "string"
-}

removedInput schema / properties / body / properties / holdAt / maxItems
```
Removed value: -3
```
removedInput schema / properties / body / properties / holdAt / type
```
Removed value: -"array"
```
addedInput schema / properties / body / properties / maxCandidates / $ref
```
Added value: +"#/$defs/__schema12"
```

removedInput schema / properties / body / properties / maxCandidates / description

Removed value: -"Ensemble size, 1–5. Defaults to one; explicit multi-candidate runs divide the job budget across candidates and admit at most two concurrently. A held editorial checkpoint always uses one candidate."

removedInput schema / properties / body / properties / maxCandidates / maximum
```
Removed value: -5
```
removedInput schema / properties / body / properties / maxCandidates / minimum
```
Removed value: -1
```
removedInput schema / properties / body / properties / maxCandidates / type
```
Removed value: -"integer"
```
addedInput schema / properties / body / properties / parentJobId / $ref
```
Added value: +"#/$defs/__schema11"
```

removedInput schema / properties / body / properties / parentJobId / description

Removed value: -"Pointer to the prior compose job this run iterates on. Surfaced on the resulting compose job as baselineComposeJobId."

removedInput schema / properties / body / properties / parentJobId / type
```
Removed value: -"string"
```
addedInput schema / properties / body / properties / qualityThreshold / $ref
```
Added value: +"#/$defs/__schema14"
```
removedInput schema / properties / body / properties / qualityThreshold / description
```
Removed value: -"Composite-score accept threshold. Server default per contract."
```
removedInput schema / properties / body / properties / qualityThreshold / maximum
```
Removed value: -10
```
removedInput schema / properties / body / properties / qualityThreshold / minimum
```
Removed value: -0
```
removedInput schema / properties / body / properties / qualityThreshold / type
```
Removed value: -"number"
```
addedInput schema / properties / body / properties / scope / $ref
```
Added value: +"#/$defs/__schema9"
```

removedInput schema / properties / body / properties / scope / description

Removed value: -"RequestScope discriminated union (per compose-api-contract.md). Editor-only scopes (captions/overlay-track/broll/overlay-instance/segment) require an editor-session token; API tokens get 403 on those."

addedInput schema / properties / body / properties / seed / $ref
```
Added value: +"#/$defs/__schema15"
```
removedInput schema / properties / body / properties / seed / description
```
Removed value: -"Deterministic seed for replay."
```
removedInput schema / properties / body / properties / seed / maximum
```
Removed value: -9007199254740991
```
removedInput schema / properties / body / properties / seed / minimum
```
Removed value: --9007199254740991
```
removedInput schema / properties / body / properties / seed / type
```
Removed value: -"integer"
```
addedInput schema / properties / body / properties / suggestionId / $ref
```
Added value: +"#/$defs/__schema0"
```
removedInput schema / properties / body / properties / suggestionId / minLength
```
Removed value: -1
```
removedInput schema / properties / body / properties / suggestionId / type
```
Removed value: -"string"
```
addedInput schema / properties / commandId / $ref
```
Added value: +"#/$defs/__schema19"
```
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"
+}

Changed3 schema fields changedOct 18, 2026

changedInput schema / properties / body / properties / format / additionalProperties
```
Previous value: -falseNew value: +{}
```

changedInput schema / properties / body / properties / maxCandidates / description

Previous value: -"Ensemble size. Currently pinned to 1 — the multi-candidate ensemble is disabled pending a capacity bound, so any value >1 is ignored and every compose runs a single candidate. Still accepted for forward-compat; will honor [1, 5] again once re-enabled."New value: +"Ensemble size, 1–5. Defaults to one; explicit multi-candidate runs divide the job budget across candidates and admit at most two concurrently. A held editorial checkpoint always uses one candidate."

addedOutput schema / properties / reconciliationRequired
```
Added value: +{
+  "type": "boolean"
+}
```

Changed1 schema field changedOct 15, 2026
- addedInput schema / properties / body / properties / format / properties / platform
```
Added value: +{
+  "type": "string"
+}
```
First observedOct 10, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations only declare readOnly=false, destructive=false, idempotent=false, openWorld=false; the description adds the async-job model, ensemble verification, the refusal-loudly behavior, and the returned { composeJobId, status, streamUrl }. However, its claim that fromComposition carries authored graphics 'VERBATIM as locked clips ... never re-authors or drops' conflicts with the schema's statement that client-authored graphic clips cause a validation_error refusal (only the Director's own critique-retry output is exempt), which could lead an agent into a guaranteed failure.

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 core action and the return/follow-up contract, with no filler sentences. It is dense and heavily parenthesized — the three source paths in one long sentence with backticked labels — which is efficient but slightly harder to scan than a bulleted breakdown would be.

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?

An output schema exists, yet the description still names the returned fields and the blocking follow-up, and annotations plus schema cover the remaining safety/budget/hold semantics. The one substantive hole is the missing caveat that fromComposition is refused for client-authored graphic clips, which is exactly the kind of failure mode a caller needs pre-warned.

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; the description earns above that by giving the source-selection semantics and the exact mutual-exclusivity rule ('EXACTLY ONE source'), which is the highest-risk parameter decision. Other body fields (maxCandidates, holdAt, critique, budgetUsd, qualityThreshold, seed, clientNonce) are left entirely to the schema, so it is not exhaustive.

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 ('Start an async Director compose job') and immediately explains the pipeline: authors an ensemble of candidates, verifies each, saves the winner. It also distinguishes itself from siblings by naming apply_composition, create_brief, suggest_briefs and wait_job as the surrounding steps.

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 enumerates the three mutually exclusive entry paths and their prerequisites: briefId requires create_brief first (PLANNED), fromComposition requires apply_composition first (GENERAL), suggestionId pairs with suggest_briefs (CLIPPING). It also gives the mandatory follow-up (wait_job with kind="compose"), so an agent knows both when to call it and what to do next.

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.