# episode_update

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

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

Update the saved episode's own title, description, Episode-time chapters, and/or Episode date. Read the exact Episode first and pass its draft_revision; a stale token fails without overwriting newer human copy. Episode date is the durable project chronology field; date-only input is interpreted as 12:00 UTC and sets the basis to manual. This is metadata-only; structural timeline edits use the separate episode_edit patch primitive. Do not use this for YouTube/LinkedIn/X package copy unless the user explicitly asks to rename, redescribe, or correct the date of the episode itself; use publish_prepare or publish_update for channel/package copy.

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_update",
  "title": "Update episode metadata",
  "description": "Update the saved episode's own title, description, Episode-time chapters, and/or Episode date. Read the exact Episode first and pass its draft_revision; a stale token fails without overwriting newer human copy. Episode date is the durable project chronology field; date-only input is interpreted as 12:00 UTC and sets the basis to manual. This is metadata-only; structural timeline edits use the separate episode_edit patch primitive. Do not use this for YouTube/LinkedIn/X package copy unless the user explicitly asks to rename, redescribe, or correct the date of the episode itself; use publish_prepare or publish_update for channel/package copy.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Episode public ID."
      },
      "title": {
        "type": "string",
        "description": "Optional new title."
      },
      "description": {
        "type": "string",
        "description": "Optional new description."
      },
      "chapters": {
        "type": "array",
        "maxItems": 250,
        "description": "Optional user-authored Episode-time chapters. Omit to preserve the current field; pass [] to clear it.",
        "items": {
          "type": "object",
          "properties": {
            "start_seconds": {
              "type": "number",
              "minimum": 0,
              "description": "Chapter start on the playable Episode clock."
            },
            "title": {
              "type": "string"
            }
          },
          "required": [
            "start_seconds",
            "title"
          ]
        }
      },
      "episode_date": {
        "type": "string",
        "description": "Optional ISO8601 date or timestamp for the Episode date. Date-only values are stored at 12:00 UTC."
      },
      "expected_revision": {
        "type": "string",
        "description": "Required opaque draft_revision from a fresh episode_read or binding receipt. A stale token is rejected before any metadata write."
      },
      "idempotency_key": {
        "type": "string",
        "description": "Caller-stable key for safe retry."
      }
    },
    "required": [
      "episode_id",
      "expected_revision",
      "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_update",
  "title": "Update episode metadata",
  "description": "Update the saved episode's own title, description, Episode-time chapters, and/or Episode date. Read the exact Episode first and pass its draft_revision; a stale token fails without overwriting newer human copy. Episode date is the durable project chronology field; date-only input is interpreted as 12:00 UTC and sets the basis to manual. This is metadata-only; structural timeline edits use the separate episode_edit patch primitive. Do not use this for YouTube/LinkedIn/X package copy unless the user explicitly asks to rename, redescribe, or correct the date of the episode itself; use publish_prepare or publish_update for channel/package copy.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Episode public ID."
      },
      "title": {
        "type": "string",
        "description": "Optional new title."
      },
      "description": {
        "type": "string",
        "description": "Optional new description."
      },
      "chapters": {
        "type": "array",
        "maxItems": 250,
        "description": "Optional user-authored Episode-time chapters. Omit to preserve the current field; pass [] to clear it.",
        "items": {
          "type": "object",
          "properties": {
            "start_seconds": {
              "type": "number",
              "minimum": 0,
              "description": "Chapter start on the playable Episode clock."
            },
            "title": {
              "type": "string"
            }
          },
          "required": [
            "start_seconds",
            "title"
          ]
        }
      },
      "episode_date": {
        "type": "string",
        "description": "Optional ISO8601 date or timestamp for the Episode date. Date-only values are stored at 12:00 UTC."
      },
      "expected_revision": {
        "type": "string",
        "description": "Required opaque draft_revision from a fresh episode_read or binding receipt. A stale token is rejected before any metadata write."
      },
      "idempotency_key": {
        "type": "string",
        "description": "Caller-stable key for safe retry."
      }
    },
    "required": [
      "episode_id",
      "expected_revision",
      "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"
      },
      "revision": {
        "type": "integer"
      },
      "draft_revision": {
        "type": "string",
        "description": "Authoritative opaque draft revision after the metadata write."
      },
      "title": {
        "type": "string"
      },
      "description": {
        "type": "string"
      },
      "chapters": {
        "type": "array"
      },
      "chapter_timebase": {
        "type": "string",
        "enum": [
          "episode"
        ]
      },
      "stale_media": {
        "type": "boolean"
      },
      "episode_date": {
        "type": "string"
      },
      "episode_date_basis": {
        "type": "string"
      },
      "episode_date_label": {
        "type": "string"
      },
      "already_applied": {
        "type": "boolean"
      },
      "blockers": {
        "type": "array",
        "items": {
          "type": "object"
        }
      }
    },
    "required": [],
    "additionalProperties": false
  }
}
```

## Live Workspace descriptor

```json
{
  "name": "episode_update",
  "title": "Update episode metadata",
  "description": "Update the saved episode's own title, description, Episode-time chapters, and/or Episode date. Read the exact Episode first and pass its draft_revision; a stale token fails without overwriting newer human copy. Episode date is the durable project chronology field; date-only input is interpreted as 12:00 UTC and sets the basis to manual. This is metadata-only; structural timeline edits use the separate episode_edit patch primitive. Do not use this for YouTube/LinkedIn/X package copy unless the user explicitly asks to rename, redescribe, or correct the date of the episode itself; use publish_prepare or publish_update for channel/package copy.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Episode public ID."
      },
      "title": {
        "type": "string",
        "description": "Optional new title."
      },
      "description": {
        "type": "string",
        "description": "Optional new description."
      },
      "chapters": {
        "type": "array",
        "maxItems": 250,
        "description": "Optional user-authored Episode-time chapters. Omit to preserve the current field; pass [] to clear it.",
        "items": {
          "type": "object",
          "properties": {
            "start_seconds": {
              "type": "number",
              "minimum": 0,
              "description": "Chapter start on the playable Episode clock."
            },
            "title": {
              "type": "string"
            }
          },
          "required": [
            "start_seconds",
            "title"
          ]
        }
      },
      "episode_date": {
        "type": "string",
        "description": "Optional ISO8601 date or timestamp for the Episode date. Date-only values are stored at 12:00 UTC."
      },
      "expected_revision": {
        "type": "string",
        "description": "Required opaque draft_revision from a fresh episode_read or binding receipt. A stale token is rejected before any metadata write."
      },
      "idempotency_key": {
        "type": "string",
        "description": "Caller-stable key for safe retry."
      }
    },
    "required": [
      "episode_id",
      "expected_revision",
      "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"
      },
      "revision": {
        "type": "integer"
      },
      "draft_revision": {
        "type": "string",
        "description": "Authoritative opaque draft revision after the metadata write."
      },
      "title": {
        "type": "string"
      },
      "description": {
        "type": "string"
      },
      "chapters": {
        "type": "array"
      },
      "chapter_timebase": {
        "type": "string",
        "enum": [
          "episode"
        ]
      },
      "stale_media": {
        "type": "boolean"
      },
      "episode_date": {
        "type": "string"
      },
      "episode_date_basis": {
        "type": "string"
      },
      "episode_date_label": {
        "type": "string"
      },
      "already_applied": {
        "type": "boolean"
      },
      "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",
  "stale_composition_revision",
  "idempotency_conflict",
  "invalid_input"
]
```

## Examples

```json
[]
```