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 eb8538f4a297f331d0399351c1e175bffcd212d2
Public contract commit 20688e11af473a363145ed880d5019c90a7ec1e2
Public contract SHA-256 87a94b85a84dc19245fc03f9b544c70d64bd9f5e08585dcccb38157cace5700d
Captured 2026-10-04T11:55:45.577Z. 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

[]