# review_points_place

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

Surface: default model and app

Product release: 8e56699756c9c201f2428c4aabba1b0af2dcfb67
Public contract commit: 1ce47f7857ae3d9b6933fe83d5c33de3ae5efc64
Public contract SHA-256: 241d47d25e4b4c1dae9d2263793874d06fc4ba7bc3c78d4cf2bc63fbb32ed7dc
Descriptor SHA-256: 885d46f3ca3939dec2ace0cd6e93611c8b3f741f2d8f7a82e0adfe1452cc9a9e
Captured: 2026-09-25T06:43:18.135Z
Source: https://app.bitterclip.com/api/v1/mcp_descriptors.json

Save 1–20 source-backed, reviewable Moments on one existing Episode, then open the same workspace. If exactly one placement succeeds, it is focused; multiple successful points are visible but not auto-focused. Use this once and last only when the user explicitly asks to save or mark reviewable Moments; never use it for a read-only open/show request, and never follow it with workspace_open. 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": "Save 1–20 source-backed, reviewable Moments on one existing Episode, then open the same workspace. If exactly one placement succeeds, it is focused; multiple successful points are visible but not auto-focused. Use this once and last only when the user explicitly asks to save or mark reviewable Moments; never use it for a read-only open/show request, and never follow it with workspace_open. 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": {
    "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": "Save 1–20 source-backed, reviewable Moments on one existing Episode, then open the same workspace. If exactly one placement succeeds, it is focused; multiple successful points are visible but not auto-focused. Use this once and last only when the user explicitly asks to save or mark reviewable Moments; never use it for a read-only open/show request, and never follow it with workspace_open. 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": {
    "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": "Save 1–20 source-backed, reviewable Moments on one existing Episode, then open the same workspace. If exactly one placement succeeds, it is focused; multiple successful points are visible but not auto-focused. Use this once and last only when the user explicitly asks to save or mark reviewable Moments; never use it for a read-only open/show request, and never follow it with workspace_get_link. 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": {
    "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
[]
```