Workspace

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

TOOL 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"

TOOL 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)

TOOL 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)

TOOL 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.

TOOL 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

TOOL 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.

TOOL 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

TOOL 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.

TOOL 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.

TOOL 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.

Resolvers

Buy More Credits