# episodes_list

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

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

List or find top-level EPISODES — the unit of work; the front door for browse, latest/open, project recaps or coaching prep. `query` matches episode, project, recording, or speaker names across fields ("mike john" finds the Mike & John Show; "me" usually means the studio owner). Rows carry `match_reason`, a dense indexed description, and `episode_shape`/`latest_open_hint` separating ready full-length episodes from short drafts — for "latest episode" asks prefer a ready full-length row and pass `order:"latest"`. Chronological project recaps: keep the default chronological order and read each episode before synthesizing. Returns row-carrying prose only, with each exact `episode_id` in brackets for the next tool call. For a relevant/latest Episode ask: episodes_list(query), shortlist 2–4; for Project content evidence, use transcript_search first, then returned-window episode_read. For a whole Episode, call workspace_open once and last. For a named read-only moment, first read the Episode, then call workspace_open once and last with focus_range and that exact expected_revision; this focuses transiently without saving. An explicit request to save or mark a range uses review_points_place instead. For an explicitly comprehensive recap, read the requested scope. Use episode_zoom only for a candidate edit/review boundary or measurable acoustic/scene seam, never physical-progress proof or post-open exploration. Raw recordings are a drawer (recordings_list); excludes render outputs and derived clips. Read-only.

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": "episodes_list",
  "title": "List episodes",
  "description": "List or find top-level EPISODES — the unit of work; the front door for browse, latest/open, project recaps or coaching prep. `query` matches episode, project, recording, or speaker names across fields (\"mike john\" finds the Mike & John Show; \"me\" usually means the studio owner). Rows carry `match_reason`, a dense indexed description, and `episode_shape`/`latest_open_hint` separating ready full-length episodes from short drafts — for \"latest episode\" asks prefer a ready full-length row and pass `order:\"latest\"`. Chronological project recaps: keep the default chronological order and read each episode before synthesizing. Returns row-carrying prose only, with each exact `episode_id` in brackets for the next tool call. For a relevant/latest Episode ask: episodes_list(query), shortlist 2–4; for Project content evidence, use transcript_search first, then returned-window episode_read. For a whole Episode, call workspace_open once and last. For a named read-only moment, first read the Episode, then call workspace_open once and last with focus_range and that exact expected_revision; this focuses transiently without saving. An explicit request to save or mark a range uses review_points_place instead. For an explicitly comprehensive recap, read the requested scope. Use episode_zoom only for a candidate edit/review boundary or measurable acoustic/scene seam, never physical-progress proof or post-open exploration. Raw recordings are a drawer (recordings_list); excludes render outputs and derived clips. Read-only.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "project_id": {
        "type": "string",
        "description": "Optional project public ID — scope the list to a single project's episodes."
      },
      "query": {
        "type": "string",
        "description": "Optional case-insensitive filter across episode title, project title, segment recording/source titles, and speaker names. Use this before reading a named episode."
      },
      "order": {
        "type": "string",
        "description": "Optional order: `latest` for newest-first latest/last/refresher tasks, or `chronological` for oldest-to-newest project recaps. Project-scoped default is chronological; account-wide default is latest."
      },
      "limit": {
        "type": "integer",
        "description": "Optional maximum number of recent episodes to return. For 'last few', pass 3 unless the user names another count."
      }
    },
    "required": [],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ]
  }
}
```

## App descriptor

```json
{
  "name": "episodes_list",
  "title": "List episodes",
  "description": "List or find top-level EPISODES — the unit of work; the front door for browse, latest/open, project recaps or coaching prep. `query` matches episode, project, recording, or speaker names across fields (\"mike john\" finds the Mike & John Show; \"me\" usually means the studio owner). Rows carry `match_reason`, a dense indexed description, and `episode_shape`/`latest_open_hint` separating ready full-length episodes from short drafts — for \"latest episode\" asks prefer a ready full-length row and pass `order:\"latest\"`. Chronological project recaps: keep the default chronological order and read each episode before synthesizing. Returns row-carrying prose only, with each exact `episode_id` in brackets for the next tool call. For a relevant/latest Episode ask: episodes_list(query), shortlist 2–4; for Project content evidence, use transcript_search first, then returned-window episode_read. For a whole Episode, call workspace_open once and last. For a named read-only moment, first read the Episode, then call workspace_open once and last with focus_range and that exact expected_revision; this focuses transiently without saving. An explicit request to save or mark a range uses review_points_place instead. For an explicitly comprehensive recap, read the requested scope. Use episode_zoom only for a candidate edit/review boundary or measurable acoustic/scene seam, never physical-progress proof or post-open exploration. Raw recordings are a drawer (recordings_list); excludes render outputs and derived clips. Read-only.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "project_id": {
        "type": "string",
        "description": "Optional project public ID — scope the list to a single project's episodes."
      },
      "query": {
        "type": "string",
        "description": "Optional case-insensitive filter across episode title, project title, segment recording/source titles, and speaker names. Use this before reading a named episode."
      },
      "order": {
        "type": "string",
        "description": "Optional order: `latest` for newest-first latest/last/refresher tasks, or `chronological` for oldest-to-newest project recaps. Project-scoped default is chronological; account-wide default is latest."
      },
      "limit": {
        "type": "integer",
        "description": "Optional maximum number of recent episodes to return. For 'last few', pass 3 unless the user names another count."
      }
    },
    "required": [],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ]
  }
}
```

## Live Workspace descriptor

```json
{
  "name": "episodes_list",
  "title": "List episodes",
  "description": "List or find top-level EPISODES — the unit of work; the front door for browse, latest/open, project recaps or coaching prep. `query` matches episode, project, recording, or speaker names across fields (\"mike john\" finds the Mike & John Show; \"me\" usually means the studio owner). Rows carry `match_reason`, a dense indexed description, and `episode_shape`/`latest_open_hint` separating ready full-length episodes from short drafts — for \"latest episode\" asks prefer a ready full-length row and pass `order:\"latest\"`. Chronological project recaps: keep the default chronological order and read each episode before synthesizing. Returns row-carrying prose only, with each exact `episode_id` in brackets for the next tool call. For a relevant/latest Episode ask: episodes_list(query), shortlist 2–4; for Project content evidence, use transcript_search first, then returned-window episode_read. For a whole Episode, call workspace_get_link once and last. For a named read-only moment, first read the Episode, then call workspace_get_link once and last with focus_range and that exact expected_revision; this focuses transiently without saving. An explicit request to save or mark a range uses review_points_place instead. For an explicitly comprehensive recap, read the requested scope. Use episode_zoom only for a candidate edit/review boundary or measurable acoustic/scene seam, never physical-progress proof or post-open exploration. Raw recordings are a drawer (recordings_list); excludes render outputs and derived clips. Read-only.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "project_id": {
        "type": "string",
        "description": "Optional project public ID — scope the list to a single project's episodes."
      },
      "query": {
        "type": "string",
        "description": "Optional case-insensitive filter across episode title, project title, segment recording/source titles, and speaker names. Use this before reading a named episode."
      },
      "order": {
        "type": "string",
        "description": "Optional order: `latest` for newest-first latest/last/refresher tasks, or `chronological` for oldest-to-newest project recaps. Project-scoped default is chronological; account-wide default is latest."
      },
      "limit": {
        "type": "integer",
        "description": "Optional maximum number of recent episodes to return. For 'last few', pass 3 unless the user names another count."
      }
    },
    "required": [],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ]
  }
}
```

## Errors

```json
[
  "project_not_found",
  "invalid_input"
]
```

## Examples

```json
[
  {
    "label": "Find a named episode",
    "input": {
      "query": "Visual Analysis Prototype and Coaching Workflows"
    }
  },
  {
    "label": "List recent episodes",
    "input": {}
  },
  {
    "label": "List a project's episodes",
    "input": {
      "project_id": "proj_..."
    }
  },
  {
    "label": "Find latest session in a project",
    "input": {
      "project_id": "proj_...",
      "order": "latest",
      "limit": 3
    }
  }
]
```