# Workspace

Folders, saved channels, and handle/URL resolvers.

Organize channels into folders, save and manage your research. 30 channels per folder hard cap on all plans.

### `list_folders`

List the user's saved folders with channel counts. Returns folder name, ID, channel count, and creation date for each folder. No parameters required.

**Example prompt**

"Show me my saved folders"

### `create_folder`

Create a new folder for organizing saved channels. Returns 409 if a folder with this name already exists. Folder limits: Starter 15, Pro 50, Ultimate unlimited.

**Example prompt**

"Create a folder called 'Cooking Research'"

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| name | string | required | Folder name (1–50 chars, must be unique per user) |

### `rename_folder`

Rename an existing folder. Pass the current folder name (or ID) and the new name. Returns 409 if the new name collides with another existing folder.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| folder | string \| integer | required | Current folder name OR folder ID |
| new_name | string | required | New folder name (1–50 chars, must be unique) |

### `delete_folder`

Delete a folder AND unsave every channel in it. Destructive — the first call (confirm=false) returns a preview with the channel count so the user can confirm. There is no Uncategorized fallback.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| folder | string \| integer | required | Folder name OR folder ID to delete |
| confirm | boolean | false | Set to `true` to confirm deletion. First call returns the channel count so you can warn the user before they confirm. |

### `get_folder`

Get all channels in a folder with live 24h growth metrics. Returns each channel's current subscriber count, view count, and the latest 24h delta (views_24h, subs_24h).

**Example prompt**

"What's new with my Cooking Research folder?"

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| folder | string \| integer | required | Folder name OR folder ID |

### `save_channels`

Save one or more channels to a folder. Channel IDs must be raw YouTube channel IDs (start with `UC`, 24 chars). For @handles or URLs, call `resolve_handle` / `resolve_url` first. 30 channels per folder hard cap.

**Example prompt**

"Save the top 3 channels from my last search to 'Cooking Research'"

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| channel_ids | array | required | List of YouTube channel IDs (`UCxxxxxxxxxxxxxxxxxxxxxx`). Must be raw IDs — call `resolve_handle` or `resolve_url` first to convert @handles or URLs. |
| folder | string \| integer | required | Folder name OR folder ID. There is no default folder — must be specified. |

### `unsave_channel`

Remove a channel from the user's saved set. The channel disappears from whichever folder it was in.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| channel_id | string | required | YouTube channel ID (`UCxxxxxxxxxxxxxxxxxxxxxx`) to remove from saved channels |

### `move_channel`

Move an already-saved channel from its current folder to a different one. Returns 404 if the channel isn't currently saved. Returns 409 if the target folder is at the 30-channel cap.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| channel_id | string | required | YouTube channel ID (`UCxxxxxxxxxxxxxxxxxxxxxx`) to move |
| to_folder | string \| integer | required | Destination folder name OR folder ID |

## Resolvers

Convert @handles and URLs to stable channel IDs for use with workspace tools. These are narrow-use tools — search tools auto-resolve handles and URLs internally.

### `resolve_handle`

Resolve a YouTube @handle to a stable channel ID. Use only when you need a raw channel ID for `save_channels`. Search tools already auto-resolve handles — do NOT call this before searching.

**Example prompt**

"Save @cheftok to my Cooking Research folder"

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| handle | string | required | A YouTube @handle (e.g. `@cheftok` or `cheftok`). The leading `@` is optional. |

### `resolve_url`

Resolve a YouTube channel URL or video URL to a stable channel ID. For video URLs, the owner channel is returned. Use only when you need a raw channel ID for `save_channels`.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| url | string | required | A YouTube channel URL (`youtube.com/@handle`, `youtube.com/channel/UCxxx`) or video URL (`watch`, `shorts`, `youtu.be`). For video URLs the owner channel is returned. |