# review_points_place

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

Surface: default model and app

Product release: 185ad8f4adfa21ae055b5bd6f97968d9044480d1
Public contract commit: d2ab41fab4088c07c0f6b924fa4f3c63481b936a
Public contract SHA-256: 2365c73c2aef7b9f85e8434d8e29ea29f40824bc3a46a72a356155ea328757fc
Descriptor SHA-256: ef560141873b318181e4a3e6c2c93c1bbe9d49fc3c3fd417cce2e079ef1c4bee
Captured: 2026-10-29T03:35:56.855Z
Source: https://app.bitterclip.com/api/v1/mcp_descriptors.json

Saves 1–20 source-backed, reviewable Moments on one existing Episode, then opens the same workspace. If exactly one placement succeeds, it is focused; multiple successful points are visible but not auto-focused. Use this when the user explicitly asks to save or mark reviewable Moments, not for a read-only open/show request; it opens the workspace itself. Each range is a half-open [start_seconds, end_seconds) interval on the playable Episode clock. Retries converge on an existing active Moment at the exact same source-time range. This changes review metadata only; it never changes source footage or the Program, creates a reel, or renders media.

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": "review_points_place",
  "title": "Place review points",
  "description": "Saves 1–20 source-backed, reviewable Moments on one existing Episode, then opens the same workspace. If exactly one placement succeeds, it is focused; multiple successful points are visible but not auto-focused. Use this when the user explicitly asks to save or mark reviewable Moments, not for a read-only open/show request; it opens the workspace itself. Each range is a half-open [start_seconds, end_seconds) interval on the playable Episode clock. Retries converge on an existing active Moment at the exact same source-time range. This changes review metadata only; it never changes source footage or the Program, creates a reel, or renders media.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Exact Episode or derived Clip handle returned by BitterClip."
      },
      "expected_revision": {
        "type": "integer",
        "minimum": 0,
        "description": "Exact structural revision returned by episode_read. Stale revisions fail before any Moment is written."
      },
      "selections": {
        "type": "array",
        "minItems": 1,
        "maxItems": 20,
        "description": "Review points to place in Episode time.",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "range",
            "title"
          ],
          "properties": {
            "range": {
              "type": "array",
              "items": {
                "type": "number"
              },
              "minItems": 2,
              "maxItems": 2,
              "description": "Half-open [start_seconds, end_seconds) range on the playable Episode clock."
            },
            "title": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120,
              "description": "Short label for the review point."
            },
            "rationale": {
              "type": "string",
              "maxLength": 500,
              "description": "Optional editorial reason the moment is useful."
            }
          }
        }
      }
    },
    "required": [
      "episode_id",
      "expected_revision",
      "selections"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "title": "Place review points",
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ],
    "ui": {
      "resourceUri": "ui://bitterclip/workspace.chatgpt-v2.html",
      "visibility": [
        "model",
        "app"
      ]
    },
    "openai/widgetAccessible": true,
    "openai/outputTemplate": "ui://bitterclip/workspace.chatgpt-v2.html",
    "openai/toolInvocation/invoking": "Placing review points...",
    "openai/toolInvocation/invoked": "Review points ready"
  }
}
```

## App descriptor

```json
{
  "name": "review_points_place",
  "title": "Place review points",
  "description": "Saves 1–20 source-backed, reviewable Moments on one existing Episode, then opens the same workspace. If exactly one placement succeeds, it is focused; multiple successful points are visible but not auto-focused. Use this when the user explicitly asks to save or mark reviewable Moments, not for a read-only open/show request; it opens the workspace itself. Each range is a half-open [start_seconds, end_seconds) interval on the playable Episode clock. Retries converge on an existing active Moment at the exact same source-time range. This changes review metadata only; it never changes source footage or the Program, creates a reel, or renders media.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Exact Episode or derived Clip handle returned by BitterClip."
      },
      "expected_revision": {
        "type": "integer",
        "minimum": 0,
        "description": "Exact structural revision returned by episode_read. Stale revisions fail before any Moment is written."
      },
      "selections": {
        "type": "array",
        "minItems": 1,
        "maxItems": 20,
        "description": "Review points to place in Episode time.",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "range",
            "title"
          ],
          "properties": {
            "range": {
              "type": "array",
              "items": {
                "type": "number"
              },
              "minItems": 2,
              "maxItems": 2,
              "description": "Half-open [start_seconds, end_seconds) range on the playable Episode clock."
            },
            "title": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120,
              "description": "Short label for the review point."
            },
            "rationale": {
              "type": "string",
              "maxLength": 500,
              "description": "Optional editorial reason the moment is useful."
            }
          }
        }
      }
    },
    "required": [
      "episode_id",
      "expected_revision",
      "selections"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "title": "Place review points",
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ],
    "ui": {
      "resourceUri": "ui://bitterclip/workspace.chatgpt-v2.html",
      "visibility": [
        "model",
        "app"
      ]
    },
    "openai/widgetAccessible": true,
    "openai/outputTemplate": "ui://bitterclip/workspace.chatgpt-v2.html",
    "openai/toolInvocation/invoking": "Placing review points...",
    "openai/toolInvocation/invoked": "Review points ready"
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "opened": {
        "type": "boolean"
      },
      "workspace_url": {
        "type": "string"
      },
      "project_id": {
        "type": "string"
      },
      "project": {
        "type": "object"
      },
      "composition": {
        "type": "object"
      },
      "workspace_navigation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "target",
          "route"
        ],
        "properties": {
          "schema": {
            "type": "string",
            "enum": [
              "bitterclip.workspace-nav.v1"
            ]
          },
          "target": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "kind",
              "id"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "episode",
                  "clip"
                ]
              },
              "id": {
                "type": "string",
                "pattern": "^comp_[A-Za-z0-9_-]{1,120}$"
              }
            }
          },
          "route": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "name",
              "mode"
            ],
            "properties": {
              "name": {
                "type": "string",
                "enum": [
                  "composition"
                ]
              },
              "mode": {
                "type": "string",
                "enum": [
                  "review"
                ]
              }
            }
          }
        }
      },
      "editor_document": {
        "type": "object",
        "description": "Versioned application document consumed by the shared editor."
      },
      "moments": {
        "type": "array",
        "description": "Active source-backed review points visible on this Episode."
      },
      "selection_results": {
        "type": "array",
        "description": "One compact, handle-free placement result per requested review point.",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "ok"
          ],
          "properties": {
            "ok": {
              "type": "boolean"
            },
            "title": {
              "type": "string"
            },
            "label": {
              "type": "string"
            },
            "episode_start_seconds": {
              "type": "number",
              "description": "Requested Episode start."
            },
            "episode_end_seconds": {
              "type": "number",
              "description": "Requested Episode end."
            },
            "placed_episode_start_seconds": {
              "type": "number",
              "description": "Actual persisted Episode start."
            },
            "placed_episode_end_seconds": {
              "type": "number",
              "description": "Actual persisted Episode end."
            },
            "reason": {
              "type": "string",
              "description": "Closed placement, clamp, or failure reason."
            },
            "message": {
              "type": "string"
            },
            "deduped": {
              "type": "boolean",
              "description": "True when an exact active review point already existed."
            }
          }
        }
      },
      "route": {
        "type": "object"
      },
      "blockers": {
        "type": "array",
        "items": {
          "type": "object"
        }
      },
      "next_actions": {
        "type": "array"
      },
      "handle_policy": {
        "type": "string"
      }
    },
    "required": [],
    "additionalProperties": false
  }
}
```

## Live Workspace descriptor

```json
{
  "name": "review_points_place",
  "title": "Place review points",
  "description": "Saves 1–20 source-backed, reviewable Moments on one existing Episode, then opens the same workspace. If exactly one placement succeeds, it is focused; multiple successful points are visible but not auto-focused. Use this when the user explicitly asks to save or mark reviewable Moments, not for a read-only open/show request; it opens the workspace itself. Each range is a half-open [start_seconds, end_seconds) interval on the playable Episode clock. Retries converge on an existing active Moment at the exact same source-time range. This changes review metadata only; it never changes source footage or the Program, creates a reel, or renders media.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Exact Episode or derived Clip handle returned by BitterClip."
      },
      "expected_revision": {
        "type": "integer",
        "minimum": 0,
        "description": "Exact structural revision returned by episode_read. Stale revisions fail before any Moment is written."
      },
      "selections": {
        "type": "array",
        "minItems": 1,
        "maxItems": 20,
        "description": "Review points to place in Episode time.",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "range",
            "title"
          ],
          "properties": {
            "range": {
              "type": "array",
              "items": {
                "type": "number"
              },
              "minItems": 2,
              "maxItems": 2,
              "description": "Half-open [start_seconds, end_seconds) range on the playable Episode clock."
            },
            "title": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120,
              "description": "Short label for the review point."
            },
            "rationale": {
              "type": "string",
              "maxLength": 500,
              "description": "Optional editorial reason the moment is useful."
            }
          }
        }
      }
    },
    "required": [
      "episode_id",
      "expected_revision",
      "selections"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "title": "Place review points",
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ],
    "openai/toolInvocation/invoking": "Placing review points...",
    "openai/toolInvocation/invoked": "Review points ready"
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "opened": {
        "type": "boolean"
      },
      "workspace_url": {
        "type": "string"
      },
      "project_id": {
        "type": "string"
      },
      "project": {
        "type": "object"
      },
      "composition": {
        "type": "object"
      },
      "workspace_navigation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "target",
          "route"
        ],
        "properties": {
          "schema": {
            "type": "string",
            "enum": [
              "bitterclip.workspace-nav.v1"
            ]
          },
          "target": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "kind",
              "id"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "episode",
                  "clip"
                ]
              },
              "id": {
                "type": "string",
                "pattern": "^comp_[A-Za-z0-9_-]{1,120}$"
              }
            }
          },
          "route": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "name",
              "mode"
            ],
            "properties": {
              "name": {
                "type": "string",
                "enum": [
                  "composition"
                ]
              },
              "mode": {
                "type": "string",
                "enum": [
                  "review"
                ]
              }
            }
          }
        }
      },
      "editor_document": {
        "type": "object",
        "description": "Versioned application document consumed by the shared editor."
      },
      "moments": {
        "type": "array",
        "description": "Active source-backed review points visible on this Episode."
      },
      "selection_results": {
        "type": "array",
        "description": "One compact, handle-free placement result per requested review point.",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "ok"
          ],
          "properties": {
            "ok": {
              "type": "boolean"
            },
            "title": {
              "type": "string"
            },
            "label": {
              "type": "string"
            },
            "episode_start_seconds": {
              "type": "number",
              "description": "Requested Episode start."
            },
            "episode_end_seconds": {
              "type": "number",
              "description": "Requested Episode end."
            },
            "placed_episode_start_seconds": {
              "type": "number",
              "description": "Actual persisted Episode start."
            },
            "placed_episode_end_seconds": {
              "type": "number",
              "description": "Actual persisted Episode end."
            },
            "reason": {
              "type": "string",
              "description": "Closed placement, clamp, or failure reason."
            },
            "message": {
              "type": "string"
            },
            "deduped": {
              "type": "boolean",
              "description": "True when an exact active review point already existed."
            }
          }
        }
      },
      "route": {
        "type": "object"
      },
      "blockers": {
        "type": "array",
        "items": {
          "type": "object"
        }
      },
      "next_actions": {
        "type": "array"
      },
      "handle_policy": {
        "type": "string"
      },
      "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",
  "invalid_input",
  "stale_composition_revision",
  "episode_changed_during_read"
]
```

## Examples

```json
[]
```
