# episode_clone

Canonical HTML page: https://bitterclip.com/docs/assistants/tools/episode_clone

Surface: default model and app

Product release: 1dce717408a55fac1047e7d779177fa3ef8ede51
Public contract commit: 1ce47f7857ae3d9b6933fe83d5c33de3ae5efc64
Public contract SHA-256: 241d47d25e4b4c1dae9d2263793874d06fc4ba7bc3c78d4cf2bc63fbb32ed7dc
Descriptor SHA-256: 885d46f3ca3939dec2ace0cd6e93611c8b3f741f2d8f7a82e0adfe1452cc9a9e
Captured: 2026-09-24T16:39:30.100Z
Source: https://app.bitterclip.com/api/v1/mcp_descriptors.json

Create a clean draft branch from an existing top-level episode only when the user explicitly wants a separate version for comparison or a workshop reset. The clone copies that one episode's source-backed segments, timeline music, overlays, title/copy, aspect ratio, caption setting, and project, but it does not copy rendered media, publish state, origin recording ownership, or revision history. Do not use clone to assemble a new reel from Project sources; use one episode_create with ordered source ranges. Use episode_edit when the current visible draft should change in place.

The JSON blocks below are the exact MCP descriptor projections served by Rails for the named profiles at capture time. Security schemes and resource URIs may vary by connected host.

## Default model descriptor

```json
{
  "name": "episode_clone",
  "title": "Clone an episode",
  "description": "Create a clean draft branch from an existing top-level episode only when the user explicitly wants a separate version for comparison or a workshop reset. The clone copies that one episode's source-backed segments, timeline music, overlays, title/copy, aspect ratio, caption setting, and project, but it does not copy rendered media, publish state, origin recording ownership, or revision history. Do not use clone to assemble a new reel from Project sources; use one episode_create with ordered source ranges. Use episode_edit when the current visible draft should change in place.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Top-level episode public ID to branch from. A recording id alias (src_...) resolves to that recording's episode-of-one."
      },
      "title": {
        "type": "string",
        "description": "Optional title for the clone. Defaults to 'Copy of <source title>'."
      },
      "description": {
        "type": "string",
        "description": "Optional description for the clone. Defaults to the source episode's displayed description."
      },
      "idempotency_key": {
        "type": "string",
        "description": "Caller-stable key for safe retry of the same clone request."
      }
    },
    "required": [
      "episode_id",
      "idempotency_key"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ],
    "ui": {
      "visibility": [
        "model",
        "app"
      ]
    },
    "openai/widgetAccessible": true
  }
}
```

## App descriptor

```json
{
  "name": "episode_clone",
  "title": "Clone an episode",
  "description": "Create a clean draft branch from an existing top-level episode only when the user explicitly wants a separate version for comparison or a workshop reset. The clone copies that one episode's source-backed segments, timeline music, overlays, title/copy, aspect ratio, caption setting, and project, but it does not copy rendered media, publish state, origin recording ownership, or revision history. Do not use clone to assemble a new reel from Project sources; use one episode_create with ordered source ranges. Use episode_edit when the current visible draft should change in place.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Top-level episode public ID to branch from. A recording id alias (src_...) resolves to that recording's episode-of-one."
      },
      "title": {
        "type": "string",
        "description": "Optional title for the clone. Defaults to 'Copy of <source title>'."
      },
      "description": {
        "type": "string",
        "description": "Optional description for the clone. Defaults to the source episode's displayed description."
      },
      "idempotency_key": {
        "type": "string",
        "description": "Caller-stable key for safe retry of the same clone request."
      }
    },
    "required": [
      "episode_id",
      "idempotency_key"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "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": {
      "episode_id": {
        "type": "string",
        "description": "New clone episode public ID."
      },
      "source_episode_id": {
        "type": "string",
        "description": "Episode public ID the clone branched from."
      },
      "cloned_from_episode_id": {
        "type": "string",
        "description": "Alias for source_episode_id for lineage displays."
      },
      "cloned_from_revision": {
        "type": "integer",
        "description": "Source episode revision captured by the clone."
      },
      "duration_seconds": {
        "type": "number",
        "description": "Kept play length in seconds."
      },
      "revision": {
        "type": "integer",
        "description": "Durable revision counter, always 1 for a fresh clone."
      },
      "segments": {
        "type": "array",
        "description": "The cloned segment manifest (index, source_id, source_range, episode_range, boundary)."
      },
      "edge_warnings": {
        "type": "array",
        "description": "Always present. Non-mutating warnings for cloned cut edges that land strictly inside transcript words.",
        "items": {
          "type": "object",
          "properties": {
            "segment_index": {
              "type": "integer"
            },
            "edge": {
              "type": "string",
              "enum": [
                "start",
                "end"
              ]
            },
            "at_seconds": {
              "type": "number",
              "description": "Recording source time for the flagged edge. This legacy field name is not Episode time."
            },
            "source_id": {
              "type": "string",
              "description": "Recording containing the flagged source edge."
            },
            "occurrence_id": {
              "type": "string",
              "description": "Exact created-target occurrence containing this edge, when mapped."
            },
            "episode_seconds": {
              "type": "number",
              "description": "Exact flagged point on the created target's Episode clock. Use directly as an episode_zoom edge; occurrence_id identifies its source side."
            },
            "word": {
              "type": "string"
            },
            "word_range_source": {
              "type": "array",
              "items": {
                "type": "number"
              },
              "minItems": 2,
              "maxItems": 2
            }
          }
        }
      },
      "status": {
        "type": "string",
        "description": "Always draft — cloned but not rendered."
      },
      "workspace_url": {
        "type": "string",
        "description": "Same-origin path that opens the new clone in the composite editor."
      },
      "already_applied": {
        "type": "boolean",
        "description": "true when this idempotency_key already created the same clone and the existing clone was returned."
      },
      "next_action": {
        "type": "object",
        "description": "Suggested next tool call: edit the clone with episode_edit using its current revision."
      },
      "blockers": {
        "type": "array",
        "items": {
          "type": "object"
        }
      }
    },
    "required": [],
    "additionalProperties": false
  }
}
```

## Live Workspace descriptor

```json
{
  "name": "episode_clone",
  "title": "Clone an episode",
  "description": "Create a clean draft branch from an existing top-level episode only when the user explicitly wants a separate version for comparison or a workshop reset. The clone copies that one episode's source-backed segments, timeline music, overlays, title/copy, aspect ratio, caption setting, and project, but it does not copy rendered media, publish state, origin recording ownership, or revision history. Do not use clone to assemble a new reel from Project sources; use one episode_create with ordered source ranges. Use episode_edit when the current visible draft should change in place.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Top-level episode public ID to branch from. A recording id alias (src_...) resolves to that recording's episode-of-one."
      },
      "title": {
        "type": "string",
        "description": "Optional title for the clone. Defaults to 'Copy of <source title>'."
      },
      "description": {
        "type": "string",
        "description": "Optional description for the clone. Defaults to the source episode's displayed description."
      },
      "idempotency_key": {
        "type": "string",
        "description": "Caller-stable key for safe retry of the same clone request."
      }
    },
    "required": [
      "episode_id",
      "idempotency_key"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "New clone episode public ID."
      },
      "source_episode_id": {
        "type": "string",
        "description": "Episode public ID the clone branched from."
      },
      "cloned_from_episode_id": {
        "type": "string",
        "description": "Alias for source_episode_id for lineage displays."
      },
      "cloned_from_revision": {
        "type": "integer",
        "description": "Source episode revision captured by the clone."
      },
      "duration_seconds": {
        "type": "number",
        "description": "Kept play length in seconds."
      },
      "revision": {
        "type": "integer",
        "description": "Durable revision counter, always 1 for a fresh clone."
      },
      "segments": {
        "type": "array",
        "description": "The cloned segment manifest (index, source_id, source_range, episode_range, boundary)."
      },
      "edge_warnings": {
        "type": "array",
        "description": "Always present. Non-mutating warnings for cloned cut edges that land strictly inside transcript words.",
        "items": {
          "type": "object",
          "properties": {
            "segment_index": {
              "type": "integer"
            },
            "edge": {
              "type": "string",
              "enum": [
                "start",
                "end"
              ]
            },
            "at_seconds": {
              "type": "number",
              "description": "Recording source time for the flagged edge. This legacy field name is not Episode time."
            },
            "source_id": {
              "type": "string",
              "description": "Recording containing the flagged source edge."
            },
            "occurrence_id": {
              "type": "string",
              "description": "Exact created-target occurrence containing this edge, when mapped."
            },
            "episode_seconds": {
              "type": "number",
              "description": "Exact flagged point on the created target's Episode clock. Use directly as an episode_zoom edge; occurrence_id identifies its source side."
            },
            "word": {
              "type": "string"
            },
            "word_range_source": {
              "type": "array",
              "items": {
                "type": "number"
              },
              "minItems": 2,
              "maxItems": 2
            }
          }
        }
      },
      "status": {
        "type": "string",
        "description": "Always draft — cloned but not rendered."
      },
      "workspace_url": {
        "type": "string",
        "description": "Same-origin path that opens the new clone in the composite editor."
      },
      "already_applied": {
        "type": "boolean",
        "description": "true when this idempotency_key already created the same clone and the existing clone was returned."
      },
      "next_action": {
        "type": "object",
        "description": "Suggested next tool call: edit the clone with episode_edit using its current revision."
      },
      "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

```json
[
  "composition_not_found",
  "recording_not_found",
  "idempotency_conflict",
  "invalid_input"
]
```

## Examples

```json
[
  {
    "label": "Branch an episode before trying an alternate cut",
    "input": {
      "episode_id": "comp_...",
      "title": "Workshop branch A",
      "idempotency_key": "clone-branch-a"
    }
  }
]
```