View as Markdown

Default model tools

clip_create

Create a clip

Creates a short derived Clip from one current Program range. Typed input:{type:clip|episode,id:comp_...} plus a stable variant_id creates an explicitly requested fresh alternative. Range uses that input production's local Program time; Rails maps its current source occurrences. Ordinary shortening edits the existing Clip with episode_edit. It creates one single-range Clip; several moments combined into one video are one episode_create rather than several Clips. A simultaneous Picture layout on the Clip is a later camera_program_set scene, which requires distinct-camera coverage of its whole range. The Clip keeps what the parent plays over that range (a pinned or replaced microphone, silence) and program_audio names it; audio that cannot be carried refuses with program_audio_not_preservable and the exact span to avoid. This persists the Clip only; it does not open or render. The rendered MP4 is a separate render_create with target_type:"clip", the returned clip_id as target_id, and the returned revision; render_status reports it. Publishing is separate. Optional aspect_ratio sets the draft/render default, not a finished Export.

Surface: Default model and app

Product release 185ad8f4adfa21ae055b5bd6f97968d9044480d1
Public contract commit d2ab41fab4088c07c0f6b924fa4f3c63481b936a
Public contract SHA-256 2365c73c2aef7b9f85e8434d8e29ea29f40824bc3a46a72a356155ea328757fc
Captured 2026-10-29T03:35:56.855Z. Review or improve this contract on GitHub.

These blocks show the complete MCP descriptors captured from serving Rails. Security schemes and resource URIs can differ by connected host.

Default model descriptor

{
  "name": "clip_create",
  "title": "Create a clip",
  "description": "Creates a short derived Clip from one current Program range. Typed input:{type:clip|episode,id:comp_...} plus a stable variant_id creates an explicitly requested fresh alternative. Range uses that input production's local Program time; Rails maps its current source occurrences. Ordinary shortening edits the existing Clip with episode_edit. It creates one single-range Clip; several moments combined into one video are one episode_create rather than several Clips. A simultaneous Picture layout on the Clip is a later camera_program_set scene, which requires distinct-camera coverage of its whole range. The Clip keeps what the parent plays over that range (a pinned or replaced microphone, silence) and program_audio names it; audio that cannot be carried refuses with program_audio_not_preservable and the exact span to avoid. This persists the Clip only; it does not open or render. The rendered MP4 is a separate render_create with target_type:\"clip\", the returned clip_id as target_id, and the returned revision; render_status reports it. Publishing is separate. Optional aspect_ratio sets the draft/render default, not a finished Export.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Compatibility top-level Episode input. Mutually exclusive with input."
      },
      "input": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "episode",
              "clip"
            ]
          },
          "id": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "id"
        ],
        "additionalProperties": false
      },
      "variant_id": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200,
        "description": "Required with typed input. Stable identity of the explicitly requested alternative, unchanged across retries. A separate requested alternative has a new variant_id and idempotency_key."
      },
      "range": {
        "type": "array",
        "items": {
          "type": "number"
        },
        "minItems": 2,
        "maxItems": 2,
        "description": "[start_seconds, end_seconds] in the selected input production's current local Program time."
      },
      "expected_revision": {
        "type": "integer",
        "description": "Required input production Program revision captured with the selected range. A new-key call refuses if the parent changed; an exact same-key replay still returns its existing Clip."
      },
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200,
        "description": "Clip title: 1-200 characters with no surrounding whitespace."
      },
      "description": {
        "type": "string",
        "description": "Optional clip description."
      },
      "aspect_ratio": {
        "type": "string",
        "enum": [
          "9:16",
          "16:9",
          "1:1"
        ],
        "description": "Output shape, set only for a shape the user asked for or a named vertical destination. When omitted, a typed variant preserves its input shape and legacy Episode input follows the footage. Setting 9:16 on landscape footage crops the sides away. render_create still materializes media."
      },
      "idempotency_key": {
        "type": "string",
        "description": "Caller-stable key for safe retry, scoped to the ask (conversation + attempt). A key derived from the media range changes when the cut is refined, so it never replays. A near-duplicate this same session already created comes back with near_duplicate:true instead of a second clip."
      }
    },
    "required": [
      "range",
      "expected_revision",
      "idempotency_key"
    ],
    "additionalProperties": false,
    "oneOf": [
      {
        "required": [
          "episode_id"
        ],
        "not": {
          "anyOf": [
            {
              "required": [
                "input"
              ]
            },
            {
              "required": [
                "variant_id"
              ]
            }
          ]
        }
      },
      {
        "required": [
          "input",
          "variant_id"
        ],
        "not": {
          "required": [
            "episode_id"
          ]
        }
      }
    ]
  },
  "annotations": {
    "title": "Create a clip",
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ],
    "ui": {
      "visibility": [
        "model",
        "app"
      ]
    },
    "openai/widgetAccessible": true
  }
}

App descriptor

{
  "name": "clip_create",
  "title": "Create a clip",
  "description": "Creates a short derived Clip from one current Program range. Typed input:{type:clip|episode,id:comp_...} plus a stable variant_id creates an explicitly requested fresh alternative. Range uses that input production's local Program time; Rails maps its current source occurrences. Ordinary shortening edits the existing Clip with episode_edit. It creates one single-range Clip; several moments combined into one video are one episode_create rather than several Clips. A simultaneous Picture layout on the Clip is a later camera_program_set scene, which requires distinct-camera coverage of its whole range. The Clip keeps what the parent plays over that range (a pinned or replaced microphone, silence) and program_audio names it; audio that cannot be carried refuses with program_audio_not_preservable and the exact span to avoid. This persists the Clip only; it does not open or render. The rendered MP4 is a separate render_create with target_type:\"clip\", the returned clip_id as target_id, and the returned revision; render_status reports it. Publishing is separate. Optional aspect_ratio sets the draft/render default, not a finished Export.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Compatibility top-level Episode input. Mutually exclusive with input."
      },
      "input": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "episode",
              "clip"
            ]
          },
          "id": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "id"
        ],
        "additionalProperties": false
      },
      "variant_id": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200,
        "description": "Required with typed input. Stable identity of the explicitly requested alternative, unchanged across retries. A separate requested alternative has a new variant_id and idempotency_key."
      },
      "range": {
        "type": "array",
        "items": {
          "type": "number"
        },
        "minItems": 2,
        "maxItems": 2,
        "description": "[start_seconds, end_seconds] in the selected input production's current local Program time."
      },
      "expected_revision": {
        "type": "integer",
        "description": "Required input production Program revision captured with the selected range. A new-key call refuses if the parent changed; an exact same-key replay still returns its existing Clip."
      },
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200,
        "description": "Clip title: 1-200 characters with no surrounding whitespace."
      },
      "description": {
        "type": "string",
        "description": "Optional clip description."
      },
      "aspect_ratio": {
        "type": "string",
        "enum": [
          "9:16",
          "16:9",
          "1:1"
        ],
        "description": "Output shape, set only for a shape the user asked for or a named vertical destination. When omitted, a typed variant preserves its input shape and legacy Episode input follows the footage. Setting 9:16 on landscape footage crops the sides away. render_create still materializes media."
      },
      "idempotency_key": {
        "type": "string",
        "description": "Caller-stable key for safe retry, scoped to the ask (conversation + attempt). A key derived from the media range changes when the cut is refined, so it never replays. A near-duplicate this same session already created comes back with near_duplicate:true instead of a second clip."
      }
    },
    "required": [
      "range",
      "expected_revision",
      "idempotency_key"
    ],
    "additionalProperties": false,
    "oneOf": [
      {
        "required": [
          "episode_id"
        ],
        "not": {
          "anyOf": [
            {
              "required": [
                "input"
              ]
            },
            {
              "required": [
                "variant_id"
              ]
            }
          ]
        }
      },
      {
        "required": [
          "input",
          "variant_id"
        ],
        "not": {
          "required": [
            "episode_id"
          ]
        }
      }
    ]
  },
  "annotations": {
    "title": "Create a clip",
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ],
    "ui": {
      "visibility": [
        "model",
        "app"
      ]
    },
    "openai/widgetAccessible": true
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "clip_id": {
        "type": "string"
      },
      "title": {
        "type": "string",
        "description": "The persisted Clip title, reread from the created or converged Clip."
      },
      "range": {
        "type": "array",
        "items": {
          "type": "number"
        },
        "minItems": 2,
        "maxItems": 2,
        "description": "The exact persisted parent-Episode [start_seconds, end_seconds] range represented by this Clip."
      },
      "episode_id": {
        "type": "string"
      },
      "episode_title": {
        "type": "string"
      },
      "project_id": {
        "type": "string"
      },
      "project_title": {
        "type": "string"
      },
      "status": {
        "type": "string"
      },
      "duration_seconds": {
        "type": "number"
      },
      "revision": {
        "type": "integer"
      },
      "edge_warnings": {
        "type": "array",
        "items": {
          "type": "object"
        },
        "description": "Recording boundary evidence requiring review before delivery."
      },
      "tool_outcome": {
        "type": "object",
        "description": "Persisted production receipt with the exact target, revision, and next Open action."
      },
      "near_duplicate": {
        "type": "boolean",
        "description": "True when nothing was created: this session already made a near-identical clip of this episode and the returned handles are that clip's. That Clip is refined with episode_edit; repeating the create returns it again."
      },
      "already_applied": {
        "type": "boolean",
        "description": "True when the returned persisted Clip was already in place: either an exact same-key replay, or (with near_duplicate:true) same-session range convergence."
      },
      "program_audio": {
        "type": "object",
        "description": "Present on a fresh create cut from existing Episodes/Clips: preserved is true because each selected range was proven to play the same Recording and source second (or silence) as its parent. settled says how: none (plain occurrence audio), pin, intervals or pin_and_intervals.",
        "properties": {
          "preserved": {
            "type": "boolean"
          },
          "settled": {
            "type": "string",
            "enum": [
              "none",
              "pin",
              "intervals",
              "pin_and_intervals"
            ]
          },
          "pinned_camera_group_key": {
            "type": "string",
            "description": "The camera group the new target's Program audio is pinned to, when settled includes pin."
          },
          "authorities": {
            "type": "array",
            "description": "Seconds of the new target played by each authority and Recording.",
            "items": {
              "type": "object",
              "properties": {
                "authority": {
                  "type": "string",
                  "enum": [
                    "occurrence_base",
                    "pinned_primary",
                    "explicit_replace",
                    "explicit_silence",
                    "silence"
                  ]
                },
                "recording_id": {
                  "type": "string"
                },
                "seconds": {
                  "type": "number"
                }
              }
            }
          }
        }
      },
      "user_presence": {
        "type": "object",
        "description": "Present when a live editor session on the parent episode is active: this is presence only, not visible navigation acknowledgement, and the exact Open Clip action still applies. Absent means visibility is unknown."
      },
      "opened": {
        "type": "boolean"
      },
      "review_status": {
        "type": "string",
        "enum": [
          "created_not_opened",
          "idempotency_replay_returned",
          "near_duplicate_returned"
        ]
      },
      "next_action": {
        "type": "object"
      },
      "blockers": {
        "type": "array",
        "items": {
          "type": "object"
        }
      }
    },
    "required": [],
    "additionalProperties": false
  }
}

Live Workspace descriptor

{
  "name": "clip_create",
  "title": "Create a clip",
  "description": "Creates a short derived Clip from one current Program range. Typed input:{type:clip|episode,id:comp_...} plus a stable variant_id creates an explicitly requested fresh alternative. Range uses that input production's local Program time; Rails maps its current source occurrences. Ordinary shortening edits the existing Clip with episode_edit. It creates one single-range Clip; several moments combined into one video are one episode_create rather than several Clips. A simultaneous Picture layout on the Clip is a later camera_program_set scene, which requires distinct-camera coverage of its whole range. The Clip keeps what the parent plays over that range (a pinned or replaced microphone, silence) and program_audio names it; audio that cannot be carried refuses with program_audio_not_preservable and the exact span to avoid. This persists the Clip only; it does not open or render. The rendered MP4 is a separate render_create with target_type:\"clip\", the returned clip_id as target_id, and the returned revision; render_status reports it. Publishing is separate. Optional aspect_ratio sets the draft/render default, not a finished Export.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Compatibility top-level Episode input. Mutually exclusive with input."
      },
      "input": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "episode",
              "clip"
            ]
          },
          "id": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "id"
        ],
        "additionalProperties": false
      },
      "variant_id": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200,
        "description": "Required with typed input. Stable identity of the explicitly requested alternative, unchanged across retries. A separate requested alternative has a new variant_id and idempotency_key."
      },
      "range": {
        "type": "array",
        "items": {
          "type": "number"
        },
        "minItems": 2,
        "maxItems": 2,
        "description": "[start_seconds, end_seconds] in the selected input production's current local Program time."
      },
      "expected_revision": {
        "type": "integer",
        "description": "Required input production Program revision captured with the selected range. A new-key call refuses if the parent changed; an exact same-key replay still returns its existing Clip."
      },
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200,
        "description": "Clip title: 1-200 characters with no surrounding whitespace."
      },
      "description": {
        "type": "string",
        "description": "Optional clip description."
      },
      "aspect_ratio": {
        "type": "string",
        "enum": [
          "9:16",
          "16:9",
          "1:1"
        ],
        "description": "Output shape, set only for a shape the user asked for or a named vertical destination. When omitted, a typed variant preserves its input shape and legacy Episode input follows the footage. Setting 9:16 on landscape footage crops the sides away. render_create still materializes media."
      },
      "idempotency_key": {
        "type": "string",
        "description": "Caller-stable key for safe retry, scoped to the ask (conversation + attempt). A key derived from the media range changes when the cut is refined, so it never replays. A near-duplicate this same session already created comes back with near_duplicate:true instead of a second clip."
      }
    },
    "required": [
      "range",
      "expected_revision",
      "idempotency_key"
    ],
    "additionalProperties": false,
    "oneOf": [
      {
        "required": [
          "episode_id"
        ],
        "not": {
          "anyOf": [
            {
              "required": [
                "input"
              ]
            },
            {
              "required": [
                "variant_id"
              ]
            }
          ]
        }
      },
      {
        "required": [
          "input",
          "variant_id"
        ],
        "not": {
          "required": [
            "episode_id"
          ]
        }
      }
    ]
  },
  "annotations": {
    "title": "Create a clip",
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "clip_id": {
        "type": "string"
      },
      "title": {
        "type": "string",
        "description": "The persisted Clip title, reread from the created or converged Clip."
      },
      "range": {
        "type": "array",
        "items": {
          "type": "number"
        },
        "minItems": 2,
        "maxItems": 2,
        "description": "The exact persisted parent-Episode [start_seconds, end_seconds] range represented by this Clip."
      },
      "episode_id": {
        "type": "string"
      },
      "episode_title": {
        "type": "string"
      },
      "project_id": {
        "type": "string"
      },
      "project_title": {
        "type": "string"
      },
      "status": {
        "type": "string"
      },
      "duration_seconds": {
        "type": "number"
      },
      "revision": {
        "type": "integer"
      },
      "edge_warnings": {
        "type": "array",
        "items": {
          "type": "object"
        },
        "description": "Recording boundary evidence requiring review before delivery."
      },
      "tool_outcome": {
        "type": "object",
        "description": "Persisted production receipt with the exact target, revision, and next Open action."
      },
      "near_duplicate": {
        "type": "boolean",
        "description": "True when nothing was created: this session already made a near-identical clip of this episode and the returned handles are that clip's. That Clip is refined with episode_edit; repeating the create returns it again."
      },
      "already_applied": {
        "type": "boolean",
        "description": "True when the returned persisted Clip was already in place: either an exact same-key replay, or (with near_duplicate:true) same-session range convergence."
      },
      "program_audio": {
        "type": "object",
        "description": "Present on a fresh create cut from existing Episodes/Clips: preserved is true because each selected range was proven to play the same Recording and source second (or silence) as its parent. settled says how: none (plain occurrence audio), pin, intervals or pin_and_intervals.",
        "properties": {
          "preserved": {
            "type": "boolean"
          },
          "settled": {
            "type": "string",
            "enum": [
              "none",
              "pin",
              "intervals",
              "pin_and_intervals"
            ]
          },
          "pinned_camera_group_key": {
            "type": "string",
            "description": "The camera group the new target's Program audio is pinned to, when settled includes pin."
          },
          "authorities": {
            "type": "array",
            "description": "Seconds of the new target played by each authority and Recording.",
            "items": {
              "type": "object",
              "properties": {
                "authority": {
                  "type": "string",
                  "enum": [
                    "occurrence_base",
                    "pinned_primary",
                    "explicit_replace",
                    "explicit_silence",
                    "silence"
                  ]
                },
                "recording_id": {
                  "type": "string"
                },
                "seconds": {
                  "type": "number"
                }
              }
            }
          }
        }
      },
      "user_presence": {
        "type": "object",
        "description": "Present when a live editor session on the parent episode is active: this is presence only, not visible navigation acknowledgement, and the exact Open Clip action still applies. Absent means visibility is unknown."
      },
      "opened": {
        "type": "boolean"
      },
      "review_status": {
        "type": "string",
        "enum": [
          "created_not_opened",
          "idempotency_replay_returned",
          "near_duplicate_returned"
        ]
      },
      "next_action": {
        "type": "object"
      },
      "blockers": {
        "type": "array",
        "items": {
          "type": "object"
        }
      },
      "workspace_binding": {
        "type": "object",
        "properties": {
          "schema": {
            "type": "string",
            "enum": [
              "bitterclip.workspace-binding.v2"
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "live_workspace"
            ]
          },
          "project_id": {
            "type": "string"
          },
          "target_kind": {
            "type": "string",
            "enum": [
              "episode",
              "clip"
            ]
          },
          "target_id": {
            "type": "string"
          },
          "revision": {
            "type": "integer"
          },
          "draft_revision": {
            "type": "string"
          },
          "workspace_url": {
            "type": "string"
          },
          "output_id": {
            "type": "string"
          },
          "output_status": {
            "type": "string",
            "enum": [
              "missing",
              "stale",
              "rendering",
              "ready",
              "failed"
            ]
          },
          "output_revision": {
            "type": "integer"
          },
          "parent_episode_id": {
            "type": "string"
          }
        },
        "required": [
          "schema",
          "mode",
          "target_kind",
          "target_id",
          "revision",
          "draft_revision",
          "workspace_url",
          "output_status"
        ],
        "additionalProperties": false
      }
    },
    "required": [],
    "additionalProperties": false
  }
}

Errors

[
  "composition_not_found",
  "recording_not_found",
  "stale_composition_revision",
  "idempotency_conflict",
  "invalid_time_range",
  "invalid_input",
  "program_audio_not_preservable",
  "program_source_range_unplayable"
]

Examples

[]