`episode_update`

Update episode metadata

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.

Surface: Default model and app

Product release 1dce717408a55fac1047e7d779177fa3ef8ede51
Public contract commit 1ce47f7857ae3d9b6933fe83d5c33de3ae5efc64
Public contract SHA-256 241d47d25e4b4c1dae9d2263793874d06fc4ba7bc3c78d4cf2bc63fbb32ed7dc
Captured 2026-09-24T16:39:30.100Z. 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": "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

{
  "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

{
  "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

[
  "composition_not_found",
  "stale_composition_revision",
  "idempotency_conflict",
  "invalid_input"
]

Examples

[]