add_channels_to_watchlist
ChatGPTAdds one or more channels to the user's Sandcastles watchlist so they can follow those creators. Channels can be specified by UUID, handle, or URL. This only changes the user's own watchlist; it never posts, messages, or changes anything on YouTube, TikTok, or Instagram. When to call it: Use this when the user explicitly asks to add channels to their watchlist. Examples: "add @mkbhd to my watchlist," "follow these channels," "add these 5 to my list," "add this channel: [URL]." Important — when NOT to call it automatically. Do not call this tool on your own based on discover_channels results. After discover_channels returns suggestions, propose them to the user and wait for explicit selection. The user has to specifically say which channels to add (e.g., "add the first three" or "add MrBeast and HasanAbi") before this tool is called. When NOT to call it (other cases): - Use discover_channels first if the user wants suggestions on who to follow. - Use get_channel_recap if the user wants a summary of a specific channel rather than to add it. Input. Accepts a list of channel identifiers in any combination of formats: UUIDs, handles (e.g., @mkbhd), or URLs. The server resolves each one. Choose the most specific identifier available. When you have a UUID from a previous tool call (such as discover_channels), pass the UUID — it's unambiguous and faster to resolve. Only fall back to handles or URLs when the user is naming a channel that wasn't previously surfaced. Three result categories. Each input ends up in one of three buckets: - `added` — channel already existed in Sandcastles' database and was added to the user's watchlist. - `submitted` — channel wasn't in Sandcastles yet; it was set up and added to the user's watchlist. Tell the user the channel was added and its details may take a few minutes to appear. - `skipped` — channel could not be added (already in watchlist, not found, invalid input, watchlist full, monthly submission quota reached, or ambiguous). Ambiguity handling. If the user provides a handle or name that matches multiple channels across different platforms (e.g., the same handle on YouTube and TikTok), the server returns an ambiguity response listing the candidates. If the user already named a platform, retry with that candidate's channel_uuid; otherwise ask the user which they meant. Soft limits. The user has a watchlist size limit and a monthly limit on how many channels new to Sandcastles they can add. If either limit is hit, the relevant additions are skipped with a clear reason. Tell the user what happened plainly ("you've reached this month's limit for new channels"). Guests. A guest in someone else's workspace can't change its watchlist; the call fails with permission_denied. No credit cost.
add_items
ChatGPTAdds one or more videos to an existing project. Accepts a list of video UUIDs. The MCP surface only supports adding videos — scripts must be added through the Sandcastles webapp. When to call it: Use this when the user explicitly asks to save, add, or put videos into a specific project. Examples: "add these to my inspiration project," "save this video to my client review folder," "put the top three in project X." When NOT to call it: - Use create_project first if the user names a project that doesn't exist yet. - Use list_projects first if you need to find the project UUID by name. - Use remove_items when the user wants to take videos out of a project. Best-effort semantics: If some videos can't be added (not found, wrong workspace, already in the project), the call still processes the rest. The response reports per-video success or failure with a reason. No credit cost.
analyze_video
ChatGPTAnalyzes a single video to extract its hook, format, narrative structure, topic, and other components. Used when the user wants to deeply understand why a specific video worked. When to call it: Use this when the user wants Sandcastles to analyze a specific video. Examples: "analyze this video [url]," "what's the breakdown on this [url]," "tell me why this video worked [url]," "show me the analysis for [url]." If the user pastes a URL without asking for analysis, ask them whether they want it analyzed before calling. When NOT to call it: - Use get_video_details if the user wants the full payload of a video that's already been analyzed and is in the workspace. - Use search_my_videos or the top_* tools if the user wants to discover videos rather than analyze a specific one. - Use create_automation_rule when the user wants standing, recurring auto-analysis based on performance criteria rather than a one-off analysis of a specific video. Input requirements. Pass exactly one of: - url — a video URL (TikTok, Instagram, or YouTube Shorts supported) - video_uuid — a Sandcastles video UUID Passing both or neither returns an error. URLs from unsupported platforms return an error from the server. Cost. This tool consumes one analysis credit per new video. If the video is already in the workspace's library, no credit is consumed. Behavior. The tool returns as soon as the video is queued — it never waits for the analysis and never returns the analysis itself. The response is always status: "still_analyzing" with a video_uuid and a recommended retry interval, even when the video has been analyzed before. Tell the user the analysis is in progress and either: - Ask the user to wait about a minute and ask again, or - Call get_video_details after about 30 seconds to fetch the analysis, then every 30 seconds until it is complete.
check_connection
ChatGPTConfirms the connection to Sandcastles is working. Call this if the user asks whether Sandcastles is connected, or as a first call to verify the integration. Returns the user's identity and active workspace.
create_automation_rule
ChatGPTCreates an automation rule in the current workspace that auto-analyzes videos matching the specified criteria each day, up to a daily limit. Saves the user from manually browsing their feed for high-performers — matching videos are analyzed and added to their library automatically. When to call it: Use this when the user asks to set up automatic analysis, create a rule, or automate video analysis based on performance criteria. Examples: "auto-analyze every video from @mkbhd over 100K views," "create a rule for high outlier videos in my watchlist," "automate this for me." When NOT to call it: - Use analyze_video for a one-off analysis of a specific video. - Use add_channels_to_watchlist if the user wants to expand the pool of channels the rules can draw from — rules can only target channels already in the watchlist. - Use update_automation_rule to modify an existing rule rather than create a duplicate. Channel filter: optional. If provided, must be the UUID of a channel already in the user's watchlist. If the user names a channel by handle or URL, resolve it to a UUID via the watchlist first; channels not in the watchlist cannot be used and will error. If omitted, the rule applies across all watchlist channels and the daily limit covers the combined top performers (not per-channel). Thresholds: min view count, min engagement rate, and min outlier score are all optional. Engagement rate is expressed as a percentage (2 = 2%). Outlier score is a multiplier where 1.0 is average and 2.0 is twice the channel average. Defaults: name defaults to "New rule" if not provided. Daily limit defaults to 3 if not provided, minimum 1. Higher daily limits consume credits faster — mention this if the user requests a high limit (e.g., 20+). No immediate credit cost. Credits are consumed when matching videos are analyzed by the rule on subsequent days.
create_project
ChatGPTCreates a new project in the user's workspace. Projects are folders for organizing videos and scripts — for example, inspiration for an upcoming video, a batch of scripts the user is working on, or a list of videos to send to a client for review. When to call it: Use this when the user explicitly asks to create a new project, folder, or collection. Examples: "make a new project for my next video," "create a folder called 'client review,'" "start a project for morning routine research." When NOT to call it: - Use list_projects if the user wants to see projects they already have rather than create a new one. - Use add_items if the user wants to add videos to an existing project — don't create a duplicate. No credit cost.
delete_project
ChatGPTDeletes a project and removes all videos and scripts contained in it. The items themselves are not deleted from Sandcastles — only their association with the project is removed. When to call it: Use this when the user explicitly asks to delete, remove, or get rid of a project. Examples: "delete my old inspiration project," "remove the client review folder." When NOT to call it: - Use remove_items when the user wants to clear items out of a project but keep the project itself. - Use rename_project when the user wants to rename rather than delete. Always confirm before calling. This is high-stakes — the project and all its associations are gone. Even when the user has explicitly asked to delete the project, confirm by name before calling. If the project has items in it, mention how many will be unlinked so the user can decide knowingly. No credit cost.
discover_channels
ChatGPTRecommends channels for the user to follow. The recommendation can be based on the channels they already have in their watchlist (when no query is provided), on a topic the user wants to explore (when a query is provided), or on one channel they want more creators like (when a channel is provided). When to call it: Use this when the user is looking for new creators to add to their watchlist or wants to find creators on a specific topic. Three common patterns: - No query (recommendation based on existing watchlist): When the user asks who else they should follow, who to add to their watchlist, or wants suggestions in their existing niche. Examples: "who else should I follow," "recommend channels for me," "who makes content like this," "who should I add to my watchlist." For these, leave query empty. - With a query (search by topic or niche): When the user names a specific topic, niche, or kind of creator. Examples: "find me creators who talk about vegan diets," "who's making content about AI productivity," "show me sustainable fashion creators." For these, pass the user's topic in query. - With a channel (similar channels): When the user wants creators like one specific channel. Examples: "find channels similar to @example," "who else makes content like @example on TikTok." For these, pass the channel's UUID, handle, or URL in channel, and platform if the user named one. Pass either query or channel, never both. Guests in someone else's workspace can't search for similar channels. When NOT to call it: - Use add_channels_to_watchlist if the user explicitly says they want to add specific channels by name. - Use search_all_videos if the user is looking for content rather than creators. - Use get_channel_recap if the user wants a summary of one specific channel they've named. - Use search_channels to find one specific creator by handle. How to use the response. Returns up to 18 channels not already in the user's watchlist, each with handle, platform, subscriber count, AI-generated description, and category. Use channel descriptions intelligently — the user often has more context about their content goals than Sandcastles does (from the conversation, their writing style, project context). Match descriptions against that broader context to explain why each recommendation fits. No side effects, no credit cost.
get_channel_recap
ChatGPTReturns recent videos from a single channel along with channel-level stats and metadata, intended for the LLM to synthesize into a brief on what the channel has been doing and how it's performing. When to call it: Use this when the user wants a summary of a specific channel's recent content and performance, or just wants a specific channel's videos, whether or not the channel is in their watchlist. Examples: "tell me about @veritasium," "what has MrBeast been posting about," "summarize this channel's recent videos," "what's @example been up to," "how is @creator doing," "give me a recap of [channel]," "what's [channel]'s focus," "show me @example's latest videos," "get the videos from @example's Instagram." Call it first whenever the user wants videos from a channel they name, even when they want them filtered (see Filters). When NOT to call it: - Use analyze_video for deep analysis of a single specific video. - Use get_video_details to drill into one specific video's full payload. - Use top_topics, top_hooks, or top_formats for cross-channel pattern analysis across the user's watchlist. - Use discover_channels if the user wants to find new channels to follow. Input. A single channel identifier — UUID, handle, or URL. Same resolution behavior as add_channels_to_watchlist. If the handle is ambiguous (matches multiple platforms), the server returns candidates for the user to pick from. When the user names a platform ("@example on Instagram"), pass it in platform so only that platform's channel is matched. If the channel doesn't exist in Sandcastles' database, the response indicates this — offer the user the option to add it via add_channels_to_watchlist. Filters. This tool doesn't filter by views, engagement rate, or outlier score. If the user asked for filters and channel.is_in_watchlist is true, call search_my_videos with channel_uuids set to channel.uuid and those filters. If it's false, don't filter the rows yourself: tell the user filters only work on channels in their watchlist, and offer to add it via add_channels_to_watchlist. Aggregate, don't relay. Unless the user asked for the videos themselves, in which case list them, the rows are raw material, not a list to print back. Read across them, identify patterns, and ground claims in specific videos. Output. channel includes the creator's thumbnail. Each video includes thumbnail and sandcastles_url (the video in the Sandcastles web app). A good channel recap covers: - The channel's focus and identity — what they're about, drawn from the channel description and patterns across their video titles. - What they've been making content about recently — topical patterns and themes. - How they've been performing — outlier scores, engagement, views, and whether they're trending up, flat, or down over the period. - 2-3 specific high-performing videos as examples with their Sandcastles links. Workspace-scoped detail. Videos that the user has added to their workspace library include rich analysis fields (topic, seed, summary, hook, format). Videos not in their library have only basic metadata. If the analysis fields are mostly empty, lean on titles and performance metrics to infer patterns. Unanalyzed videos. Each result includes analyzed. Videos that aren't analyzed can be analyzed with analyze_video (one credit each) if the user wants hooks, formats, topics, or narrative structure. Defaults. Returns up to 15 videos from the last 30 days. Set lookback_days higher if the user asks for a broader perspective ("what has @example been doing this year"). No side effects, no credit cost.
get_credit_usage
ChatGPTReturns the organization's current credit usage and remaining balance for the active billing period. When to call it: Use this when the user asks about credits, usage, billing, how many credits they've used, or how many they have left. Examples: "how many credits do I have left," "what's my current usage," "am I running low on credits." When NOT to call it: - This tool doesn't show per-workspace or per-tool breakdowns — only the org-level totals. If the user wants that level of detail, direct them to the Sandcastles webapp. Scope: Organization-level only. Credit usage isn't tracked per workspace, so this tool takes no parameters. No side effects, no credit cost.
get_personal_analytics
ChatGPTReturns the user's dashboard numbers for their own verified channels over the last 7 days: headline stats, the view/engagement chart, and their most recent videos. This is the performance snapshot — it does not contain any written analysis. When to call it: Use this when the user asks how their channel is doing, about their recent numbers, views, engagement, followers, or what they've posted lately. Examples: "how am I doing," "what are my numbers this week," "show me my dashboard," "what did I post recently." When NOT to call it: - Use list_reports and get_report_details when the user wants a written analysis of their content strategy — that lives in reports now, not here. - Use search_my_videos to find specific videos rather than see the recent list. - Use top_topics, top_formats, or top_hooks for synthesis of what's working by dimension. - Use get_channel_recap for a summary of some other channel rather than the user's own. How to use the response: The numbers are for interpretation — what actually moved, what changed, and what it suggests. Hold the response in context and answer follow-ups from it rather than calling again. All three fields come back empty when the user has no verified channels; say they need to verify a channel and enable personal analytics rather than reporting zeros as performance. No side effects, no credit cost.
get_report_details
ChatGPTReturns one generated report in full, including its data payload — the actual findings the report produced. Requires an execution_uuid, from list_reports or given by the user. When to call it: Use this when the user wants to read, summarize, discuss, or dig into a specific report. Examples: "what did my content audit say," "walk me through last week's report," "what were the takeaways," or any follow-up question about a report you've already pulled. When NOT to call it: - Use list_reports when the user wants to know which reports exist rather than what one says. - Use get_personal_analytics for the dashboard report, which is a separate surface. How to use the response: data is the report itself, shaped by the report type — read it rather than assuming a schema. Keep the full payload in context and answer follow-ups from it instead of calling again. Synthesize across sections and say what the findings imply — don't just enumerate the JSON back. A report that hasn't succeeded returns with its status and a null data: queued or in_progress means it's still running, failed means it won't produce data and failure_reason says why. Tell the user plainly rather than treating it as an error. No side effects, no credit cost.
get_script
ChatGPTReturns one of the user's scripts in full: its topic, body, hooks, research, supporting facts, the prompt it was written from, and the video it was based on. Requires a script_uuid, from list_scripts or given by the user. When to call it: Use this when the user wants to read, review, rewrite, or discuss a specific script. Examples: "read me my cold plunge script," "which hook did I pick for that script," "tighten the body of my latest script." When NOT to call it: - Use list_scripts first if you don't have the script's script_uuid. - Use get_video_details with source_video_uuid for the analysis of the video the script was based on. Fields. body is the script text. hooks lists the hooks written for the script, newest first; active marks the one the user chose. prompt is what the user asked for when they started the script. research and supporting_facts are the research Sandcastles gathered for it. No side effects, no credit cost.
get_video_details
ChatGPTReturns the full payload for a single Sandcastles video, including basic metadata and (when available in the user's workspace library) the complete analysis. Used to drill into one specific video. When to call it: Use this whenever you need more depth on a specific video than was returned in a summary or list tool. Most often called as a follow-up: - When the user picks one of the videos returned by search_my_videos, search_all_videos, or any of the top_* tools and wants to know more. - When polling for the result of an in-progress analyze_video call. - When the user pastes a Sandcastles URL or references a video by UUID. - When the user asks for the full analysis of a specific video. When NOT to call it: - Use analyze_video if the video isn't analyzed in this workspace and the user wants it analyzed (this tool only returns analysis if it's already available; it does not trigger analysis). - Use search_my_videos or top_* tools when the user wants to discover videos rather than drill into a specific one. Returns the full payload always — including all metadata, and the full analysis blob if the video has been analyzed and added to the user's workspace library. About the `analyzed` field. This is true only if the video has been added to the user's current workspace library AND the analysis is complete. It is false in three cases: - The video has never been analyzed by anyone in Sandcastles. - The video has been analyzed by someone else but isn't in this workspace's library. - The video is in this workspace's library but analysis is still in progress or failed. When analyzed is false and the user wants the analysis, offer to call analyze_video to run it (costs one credit; if the analysis already exists globally, it returns quickly). Transcript. Transcript requests are handled here — there is no separate transcript tool. No standalone transcript field is returned. The flow: - If analyzed: true, stitch the transcript from analysis.narrative_structure.structure_sections[].transcript_sentences (in section order) and return it to the user. - If analyzed: false, no transcript is available yet. analyze_video (one credit) produces one. Output. The video includes thumbnail, sandcastles_url (the video in the Sandcastles web app), and a channel object with the creator's thumbnail. Input: a single video_uuid parameter. No side effects, no credit cost.
list_automation_rules
ChatGPTReturns all automation rules configured for the current workspace, including their filter parameters, daily limits, and active/inactive status. When to call it: Use this when the user asks about their automation rules, what rules they have set up, what's auto-analyzing for them, or wants to review or audit their current automation configuration. Examples: "what automation rules do I have," "show me my rules," "what's set to auto-analyze." Also call this as a prerequisite before update_automation_rule when the user refers to a rule by name rather than UUID — you'll need to resolve the name to a UUID. When NOT to call it: - Use create_automation_rule when the user wants to set up a new rule. - Use update_automation_rule when the user wants to modify a specific rule, deactivate it, or delete it (deletion is handled via update). - Use analyze_video when the user wants to analyze a specific video right now rather than configure standing automation. Returns rules in the current workspace only. Each rule includes its UUID, name, channel filter (if any), thresholds (min view count, min engagement rate, min outlier score), daily limit, and active status. No side effects, no credit cost.
list_ideas
ChatGPTReturns the user's ideas: the videos they've analyzed into their workspace, each with its review status, the personalized twists Sandcastles suggested for the user's own content, and the user's notes. This is the Ideas page in the Sandcastles web app. When to call it: Use this when the user asks about their ideas, their inbox, their shortlist, the videos they've saved or analyzed, or what to make next from them. Examples: "what's in my ideas inbox," "show my shortlist," "which ideas did I save this week," "give me a twist on one of my ideas." When NOT to call it: - Use search_my_videos when the user asks about their feed or watchlist rather than their ideas. - Use get_video_details for the full analysis of one idea. - Use update_ideas to shortlist, discard, or add notes to ideas. Statuses. review_status is for_review (the Inbox), approved (the Shortlist), or rejected (discarded). Optional status filters to one of these; the default all returns the Inbox and the Shortlist, the same as the web app. Filters and sorting. Optional saved_within_days limits to ideas saved in the last N days. Optional query matches the idea's seed and topic. sort accepts saved_at (default), published_at, view_count, outlier_score, or engagement_rate, and sort_direction accepts desc (default) or asc. Personalization. personalization holds up to three twists (option_1 to option_3, each with a title and description) for adapting the video to the user's content. It is empty when the user hasn't described their content in Sandcastles yet, or when the video is from the user's own channel. Still analyzing. Videos appear here once their analysis finishes, so a video just sent to analyze_video may not be listed yet. No side effects, no credit cost.
list_items
ChatGPTReturns the videos and scripts inside a specific project, sorted by most recently added first. Scripts are included in the response when present, though scripts can't be added to a project from this MCP surface — they're added in the Sandcastles webapp. When to call it: Use this when the user asks to see what's inside a specific project, what videos they saved to a folder, or what they have in a particular collection. Examples: "what's in my morning routine project," "show me the videos in the client review folder," "list the items in project X." When NOT to call it: - Use list_projects when the user wants the list of projects, not the contents of one. - Use add_items or remove_items when the user wants to modify a project's contents. - Use get_video_details when the user wants a deep dive into one specific video in the project. Defaults: Returns up to 250 items per call, sorted by most recently added first. Paging: When the response includes next_cursor, pass it back as cursor, with the same kind, query, and limit, to get the next page. next_cursor is null on the last page. No side effects, no credit cost.
list_projects
ChatGPTReturns the user's projects in the current workspace, with basic metadata for each (name, item count, last updated). Supports searching projects by name. When to call it: Use this when the user asks to see their projects, find a specific project by name, or wants to know what projects exist before adding items to one. Examples: "what projects do I have," "find my project about morning routines," "show me my folders." When NOT to call it: - Use list_items when the user wants to see the contents of a specific project, not the list of projects themselves. - Use create_project when the user wants to start a new one. Defaults: Returns up to 20 projects per call (limit up to 100), sorted by most recently updated first. Pass query to filter by name when the user is looking for a specific project. Paging: When the response includes next_cursor, pass it back as cursor, with the same query and limit, to get the next page. next_cursor is null on the last page. No side effects, no credit cost.
list_reports
ChatGPTReturns the reports the user has generated in the current workspace, most recent first, with the status and timing of each run. This is the index — it doesn't include report contents. Use get_report_details to read one. When to call it: Use this when the user asks what reports they have, when a report last ran, whether a report finished, or wants to find a specific report before reading it. Examples: "what reports do I have," "did my content audit run this week," "show me my recent reports," "find my report on the cooking channel." When NOT to call it: - Use get_report_details when the user wants to read or discuss the contents of a report — don't call this first if they've already given you an execution_uuid. - Use get_personal_analytics for the user's dashboard, which is a different surface from reports. Filtering: Pass search to match on the report's name or its report type (e.g. "Content Strategy Audit") when the user names one. Pass instance_uuid to see every run of one configured report over time — take that UUID from a previous response. With neither, you get everything recent. Defaults: Returns up to 100 runs. If truncated is true, tell the user the list may be incomplete and offer to narrow it with a search. No side effects, no credit cost.
list_scripts
ChatGPTReturns the user's scripts in the current workspace, newest first, with each script's topic and creation date. This is the Scripts page in the Sandcastles web app. When to call it: Use this when the user asks what scripts they have, wants to find a script by topic, or wants to pick up a script they started. Examples: "what scripts have I written," "find my script about cold plunges," "show my latest scripts." When NOT to call it: - Use get_script to read one script's body, hooks, and research. - Use list_ideas for the videos the user saved rather than the scripts they wrote. Search and paging. Optional query matches the script's topic. Returns up to 20 scripts per call (limit up to 100). When the response includes next_cursor, pass it back as cursor, with the same query and limit, to get the next page. No side effects, no credit cost.
list_watchlist_channels
ChatGPTReturns the channels in the user's Sandcastles watchlist for the current workspace, the same list as the Channels tab in the web app. When to call it: Use this when the user asks who or what is in their watchlist or which channels they follow. Examples: "who's in my watchlist," "which channels am I following." Also use it before remove_channels_from_watchlist when the user wants to remove channels but hasn't said exactly which. When NOT to call it: - Use get_channel_recap for one channel's videos or performance. - Use discover_channels to find new channels to follow. Output. Each channel includes uuid, handle, platform, channel_title, thumbnail, subscriber_count, and total_view_count, sorted by handle (up to 250). No side effects, no credit cost.
list_workspaces
ChatGPTLists all workspaces the user has access to in Sandcastles, including which one is currently active. Call this when the user asks about their workspaces, asks which one they're currently in, or wants to know what other workspaces they could switch to. Workspaces are the user's subdivisions for managing different content niches or client work. Do not call if the user hasn't asked about workspaces. This tool does not consume credits or have side effects.
remove_channels_from_watchlist
ChatGPTRemoves one or more channels from the user's Sandcastles watchlist. This only changes the user's own watchlist; it never posts, messages, or changes anything on YouTube, TikTok, or Instagram. When to call it: Use this when the user explicitly asks to remove, unfollow, or stop tracking specific channels. Examples: "remove @mkbhd from my watchlist," "stop following these two," "unfollow [URL]." When NOT to call it: - Don't remove channels on your own initiative or based on your own suggestions. If the user asks for something vague ("clean up my watchlist"), call list_watchlist_channels, propose which to remove, and wait for the user to say which. - Use add_channels_to_watchlist to add channels. Input. A list of channels, each a UUID, handle, or URL, matched against the channels in the watchlist. Pass platform when the user names one ("@example on Instagram"). If a handle is in the watchlist on more than one platform, it's skipped as ambiguous with the candidates; retry with the candidate's channel_uuid if the user already named a platform, otherwise ask which they meant. Results. Each input is either removed or skipped (not_in_watchlist, invalid_input, or ambiguous). Removing a channel doesn't delete videos already saved or analyzed in the workspace. Guests. A guest in someone else's workspace can't change its watchlist; the call fails with permission_denied. No credit cost.
remove_items
ChatGPTRemoves one or more videos from a project. The videos themselves are not deleted from Sandcastles — only their association with the project is removed. When to call it: Use this when the user explicitly asks to remove, take out, or unlink videos from a specific project. Examples: "remove this video from my inspiration project," "take these out of the client folder." When NOT to call it: - Use delete_project when the user wants to remove the entire project, not just specific items from it. - Use add_items when the user wants to add rather than remove. Confirmation: Confirm before calling when the user is removing more than 5 videos in a single call. Best-effort semantics: If some videos can't be removed (not in the project, not found), the call still processes the rest and reports per-video results. No credit cost.
rename_project
ChatGPTUpdates an existing project's properties. Today only the project name can be changed. When to call it: Use this when the user explicitly asks to rename a project or change its name. Examples: "rename my project to X," "change the name of the client review folder." When NOT to call it: - Use delete_project when the user wants to remove a project entirely. - Use add_items or remove_items when the user wants to change a project's contents rather than its metadata. No credit cost.
search_all_videos
ChatGPTReturns videos from across all videos Sandcastles has indexed, newest first by default, not limited to the user's watchlist. When to call it: Use this whenever the user wants to find videos on a topic, with or without filters ("find videos about cold plunges," "what's performing well about AI tools," "viral fitness videos over 1M views this week"), unless they ask specifically about their feed, their watchlist, or the channels they follow. Also use it when they explicitly mention "globally," "across all videos," or "beyond the channels I follow." A `query` is strongly recommended. Without a topic to focus on, results will be the newest videos across every niche on the platform, which is rarely useful. If the user asks for global trending content without specifying a topic ("what's performing well globally?"), prefer asking them what topic they want to look at first, then call with a query. No narrowing by channel. This tool does not accept channel_uuids — passing them fails with invalid_input. For one specific channel's videos, use get_channel_recap. When NOT to call it: - Use search_my_videos when the user asks about their feed, their watchlist, or the channels they follow. - Use top_hooks when the user specifically asks about hook patterns. - Use top_topics when the user asks about topics or themes. - Use top_formats when the user asks about formats or styles. - Use get_channel_recap when the user wants one specific channel's videos or a recap of it. Sorting. Optional sort accepts published_at (default), view_count, outlier_score, or engagement_rate, and sort_direction accepts desc (default) or asc. When the user asks for the best, top, top-performing, or viral videos, or what's performing well, set sort to outlier_score with sort_direction desc, and set lookback_days to 30 unless the user named a time period. Use view_count for "most viewed" and engagement_rate for "most engaging." Any other value fails with invalid_input. Sorting does not change which videos qualify — it reorders the videos that pass the filters, so pair a change of sort with the filters the user asked for. Defaults: Returns up to 50 videos per page, newest first, with no minimum views, engagement rate, or outlier score and no time window, the same as global search in the Sandcastles web app. Each result includes whether the video has been analyzed by Sandcastles, and whether the source channel is already in the user's watchlist. Unanalyzed videos. Each result includes analyzed. Videos that aren't analyzed can be analyzed with analyze_video (one credit each) if the user wants hooks, formats, topics, or narrative structure. Aggregate, don't relay. Unless the user asked for the videos themselves, in which case list them, the rows are raw material for synthesis, insight, and aggregation across videos, not a list to print back. Read across them, identify patterns, and ground claims in specific videos. Output. Each video includes thumbnail, sandcastles_url (the video in the Sandcastles web app), and a channel object with the creator's thumbnail. No side effects, no credit cost.
search_channels
ChatGPTFinds channels in Sandcastles by handle, with their basic metrics and whether each one is in the user's watchlist. When to call it: Use this when the user is looking for one specific creator and you don't have their exact handle, UUID, or URL. Examples: "find the channel mrbeast," "is @gymshark on Sandcastles," "which channel is veritasium." Use it before add_channels_to_watchlist or get_channel_recap when you're unsure of the handle. Matches handles only. The query is matched against channel handles, not display names or descriptions, so "Marques Brownlee" won't find @mkbhd. If the user gives a display name, try the handle you'd expect, or ask the user for it. When NOT to call it: - Use discover_channels to find creators by topic or niche, or channels similar to one channel. - Use list_watchlist_channels for the channels the user already follows. Output. Exact handle matches first, then similar spellings, up to limit. Each channel includes uuid, handle, platform, channel_title, channel_description, thumbnail, subscriber_count, total_view_count, summary, and is_in_watchlist. No side effects, no credit cost.
search_my_videos
ChatGPTReturns videos from the user's watchlist, newest first by default, with their basic metrics and metadata. When to call it: Use this when the user asks about their feed, their watchlist, or the channels they follow — what's performing well, what's been viral lately, what they should be looking at — with or without a topic and filters. It is also the fallback when the user asks what's performing well without naming a topic or a channel, and the second step when the user wants filtered videos from one specific channel in their watchlist (see Narrowing by channel). When NOT to call it: - Use search_all_videos when the user wants videos on a topic and hasn't asked about their feed, watchlist, or the channels they follow. - Use top_hooks when the user specifically asks about hooks, hook patterns, opening lines, or how videos are starting. - Use top_topics when the user specifically asks about topics, subjects, themes, or what content is "about." - Use top_formats when the user specifically asks about formats, video styles, or structural patterns. - Use get_channel_recap when the user wants a recap of one specific channel, or videos from a channel that isn't in their watchlist. Narrowing by channel. Optional channel_uuids parameter accepts a list of channel UUIDs to narrow the search to specific channels in the user's watchlist. If the user names a channel by handle or URL, call get_channel_recap first and pass its channel.uuid here only when channel.is_in_watchlist is true. UUIDs that aren't in the watchlist are dropped. If none of the provided UUIDs are in the watchlist, the call fails with invalid_input — use get_channel_recap for those channels instead. Do not invent or guess UUIDs. Each value must be a valid UUID or the call will fail with invalid_input. Leave empty to search across the entire watchlist. Sorting. Optional sort accepts published_at (default), view_count, outlier_score, or engagement_rate, and sort_direction accepts desc (default) or asc. When the user asks for the best, top, top-performing, or viral videos, or what's performing well, set sort to outlier_score with sort_direction desc, and set lookback_days to 30 unless the user named a time period. Use view_count for "most viewed" and engagement_rate for "most engaging." Any other value fails with invalid_input. Sorting does not change which videos qualify — it reorders the videos that pass the filters, so pair a change of sort with the filters the user asked for. Defaults: Returns up to 50 videos per page, newest first, with no minimum views, engagement rate, or outlier score and no time window, the same as the Videos tab in the Sandcastles web app. Searches the user's watchlist only. The user can narrow results by phrasing (e.g., "in the last week," "with more than 100K views," "on TikTok"). Each result includes whether the video has been analyzed by Sandcastles — analyzed videos have richer detail available via get_video_details. Unanalyzed videos. Each result includes analyzed. Videos that aren't analyzed can be analyzed with analyze_video (one credit each) if the user wants hooks, formats, topics, or narrative structure. Aggregate, don't relay. Unless the user asked for the videos themselves, in which case list them, the rows are raw material for synthesis, insight, and aggregation across videos, not a list to print back. Read across them, identify patterns, and ground claims in specific videos. Output. Each video includes thumbnail, sandcastles_url (the video in the Sandcastles web app), and a channel object with the creator's thumbnail. No side effects, no credit cost.
switch_workspace
ChatGPTSwitches the user's active workspace. All subsequent tool calls in this session operate against the new workspace. Also affects the user's webapp session — when they next open Sandcastles in their browser, they'll be in the new workspace. Confirm with the user before calling this if they didn't explicitly request a switch. Use list_workspaces first if you don't know the target workspace's UUID. This tool does not consume credits.
top_formats
ChatGPTReturns analyzed videos with their AI-extracted format category and type, intended for the LLM to synthesize into a summary of what video formats are currently working. When to call it: Use this when the user asks about formats, video styles, structural patterns, or what kinds of videos are working. Examples: "what formats are working," "what video styles are popular," "what structural patterns are getting traction," "what kinds of videos are creators making." When NOT to call it: - Use search_my_videos for general "what's performing well" questions without a format angle. - Use top_topics when the user asks about subjects or themes. - Use top_hooks when the user asks about hook patterns or opening lines. Scope. Defaults to "watchlist" (the user's niche). Set scope: "all" when the user wants to see formats working across the entire platform globally, or asks about formats in a niche they don't follow. Topic (`scope: "all"` only). Pass the topic the user asked about in query (e.g. "personal finance," "AI tools for marketers"). The server turns it into search terms and returns the top analyzed videos on that topic across all of Sandcastles. Without a query, it uses the workspace's content description. query is ignored for scope: "watchlist". Aggregate, don't relay. The rows are raw material, not a list to print back. Read across them, identify patterns, and ground claims in specific videos. Output. Each video includes thumbnail, channel_thumbnail (the creator's avatar), and sandcastles_url (the video in the Sandcastles web app). Group the videos by their format_category. Summarize each group with what's distinctive about it and 2-3 example videos with links. Identify which formats are dominant or rising. Defaults: last 30 days, min 25K views, 2% engagement, 1.0x outlier, for both scopes. Watchlist results are sorted by views, global results by outlier score. Always returns only analyzed videos. If the user asks for a deeper sweep, set limit up to 50. Coverage note. Only analyzed videos are included; to get a richer picture, the user will need to trigger analysis on more videos. No side effects, no credit cost.
top_hooks
ChatGPTReturns analyzed videos with their AI-extracted hook category and spoken hook madlib (the storytelling template the creator used), intended for the LLM to synthesize into a summary of what hook patterns are currently working. When to call it: Use this when the user asks about hooks, opening lines, hook patterns, how videos are starting, or what attention-grabbing techniques are working. Examples: "what hooks are working," "how are creators opening their videos," "what's the best way to start a video right now," "what hook patterns are getting traction." When NOT to call it: - Use search_my_videos for general "what's performing well" questions without a hook angle. - Use top_topics when the user asks about subjects or themes. - Use top_formats when the user asks about overall video format or structural patterns rather than the opening hook specifically. Scope. Defaults to "watchlist" (the user's niche). Set scope: "all" when the user wants to see hooks working across the platform globally, or asks about hook patterns in a niche they don't follow. Topic (`scope: "all"` only). Pass the topic the user asked about in query (e.g. "personal finance," "AI tools for marketers"). The server turns it into search terms and returns the top analyzed videos on that topic across all of Sandcastles. Without a query, it uses the workspace's content description. query is ignored for scope: "watchlist". Aggregate, don't relay. The rows are raw material, not a list to print back. Read across them, identify patterns, and ground claims in specific videos. Output. Each video includes thumbnail, channel_thumbnail (the creator's avatar), and sandcastles_url (the video in the Sandcastles web app). Read across two fields. spoken_hook_category gives you the broad bucket (e.g., curiosity gap, contrarian reframe, personal story); spoken_hook_madlib gives you the storytelling template underneath (e.g., "Most people think X but actually Y", "I tried X for 30 days and..."). Look for patterns within categories (different madlib variations of the same category) and across categories (the same madlib appearing in different categories). Lead with whichever lens surfaces the most interesting insight — usually category-as-primary with madlib as variation, but be willing to flip if a madlib pattern is genuinely cutting across categories. Cite 2-3 example videos per pattern with their Sandcastles links. Defaults: last 30 days, min 25K views, 2% engagement, 1.0x outlier, for both scopes. Watchlist results are sorted by views, global results by outlier score. Always returns only analyzed videos. If the user asks for a deeper sweep, set limit up to 50. Coverage note. Only analyzed videos are included; to get a richer picture, the user will need to trigger analysis on more videos. No side effects, no credit cost.
top_topics
ChatGPTReturns analyzed videos from the user's watchlist along with their AI-extracted topic and seed, intended for the LLM to synthesize into either a clustered summary of trending topics, or a prescriptive ranked recommendation of what the user should make next. Both modes use the same data; the LLM picks the response style based on what the user asked. When to call it: Use this for two distinct user intents: - Descriptive intent — when the user asks about topics, subjects, themes, or what content is "about" right now in their niche. Examples: "what topics are trending," "what are people making videos about," "what subjects are getting traction." - Prescriptive intent — when the user asks what they should make next, what's worth their time to investigate, or wants topic ideas for their next video. Examples: "what should I make my next video about," "give me ideas for what to make," "what topic is worth diving into next." When NOT to call it: - Use search_my_videos for general "what's performing well" questions that don't reference topics or video ideas. - Use search_all_videos if the user wants to look beyond their watchlist. - Use top_hooks when the user asks about hook patterns or opening lines. - Use top_formats when the user asks about format styles or structural patterns. Aggregate, don't relay. The rows are raw material, not a list to print back. Read across them, identify patterns, and ground claims in specific videos. Output. Each video includes thumbnail, channel_thumbnail (the creator's avatar), and sandcastles_url (the video in the Sandcastles web app). The approach depends on the user's intent: - Descriptive mode: Read across the topic and seed fields, cluster the videos into 3-5 distinct themes based on semantic similarity, and write a short brief. Name each theme, describe what's distinctive, and cite 2-3 example videos per theme with their Sandcastles links. - Prescriptive mode: Cluster the videos as in descriptive mode, then go further. Pick 3-5 topics worth the user's investigation and present them as a ranked recommendation, not a random shortlist. The order matters — lead with the topic that has the strongest combination of momentum, room for a fresh angle, and fit for the user's niche. Justify each ranking briefly: why this one is at the top, why the second one is also worth considering, what trade-off makes the third lower-ranked. For each recommendation, cite 2-3 example videos with links as research starting points. Scope and constraints: Always operates against the user's watchlist only — never global. Always returns only analyzed videos. If the user asks for a deeper sweep, set limit up to 50. Defaults: Returns up to 25 videos from the last 30 days with at least 25,000 views, 2% engagement rate, and a 1.0x outlier score. Coverage note. Only analyzed videos are included; to get a richer picture, the user will need to trigger analysis on more videos. No side effects, no credit cost.
update_automation_rule
ChatGPTUpdates an existing automation rule via partial update — only the fields you pass are changed; fields you omit or pass as null are left as-is. To unset a filter (channel, min view count, min engagement rate, min outlier score), name it in the clear list — passing null never unsets anything. When to call it: Use this when the user wants to modify an existing rule's parameters, change its thresholds, raise or lower its daily limit, switch which channel it targets, activate it, or deactivate it. Examples: "raise the daily limit on my MKBHD rule to 5," "pause my high-outlier rule," "turn off auto-analysis for that channel," "remove the view count threshold on my rule," "reactivate my paused rule." Important — this tool also handles deletion requests. If the user asks to delete, remove, or get rid of a rule, call this tool with active: false rather than treating it as a hard delete. Deactivated rules stop running but remain in the workspace, so the user can reactivate them later. There is no hard-delete tool — deactivation is the only stop mechanism. Briefly tell the user you've deactivated the rule and that they can reactivate it any time. When NOT to call it: - Use create_automation_rule when the user wants a new rule rather than modifying an existing one. - Use list_automation_rules first if you don't know the rule's UUID — the user will usually refer to rules by name. Channel filter: same rules as create — must be a UUID of a channel currently in the workspace watchlist, or clear: ["channel_uuid"] to drop the filter and have the rule apply across all watchlist channels. Partial update semantics: a field is modified only when you pass it a non-null value, or name it in clear. Everything else is left untouched, so it is always safe to send only the fields you intend to change. clear accepts any of: channel_uuid, outlier_score_min, views_min, engagement_rate_min_percent — the rule's name, daily limit and active status cannot be cleared, only set to a new value. Clearing removes that filter from the rule. Pass clear only when the user has actually asked to remove that filter, not when pausing a rule. No immediate credit cost.
update_ideas
ChatGPTChanges the review status and/or the notes of one or more of the user's ideas. When to call it: Use this when the user asks to shortlist, approve, discard, reject, or move ideas back to their inbox, or to save notes on an idea. Examples: "shortlist the first two," "discard this one," "move it back to my inbox," "add a note to this idea: film it in the gym." When NOT to call it: - Use list_ideas first if you don't have the ideas' video_uuids. - Use analyze_video to turn a new video into an idea. Input. video_uuids lists the ideas to change (up to 100), with status (for_review for the Inbox, approved for the Shortlist, rejected to discard), notes, or both. The same values apply to every listed idea. notes replaces the existing notes, so to add to them, read the current notes with list_ideas first. Results. Each input is either updated or skipped (not_found when the video isn't one of the user's ideas, or invalid_input). Guests. A guest in someone else's workspace can't change its ideas; the call fails with permission_denied. Confirmation. Confirm with the user before discarding ideas or replacing notes unless they explicitly asked for it. No credit cost.
add_channels_to_watchlist
Claudeadd_items
Claudeanalyze_video
Claudecheck_connection
Claudecreate_automation_rule
Claudecreate_project
Claudedelete_project
Claudediscover_channels
Claudeget_channel_recap
Claudeget_credit_usage
Claudeget_personal_analytics
Claudeget_report_details
Claudeget_video_details
Claudelist_automation_rules
Claudelist_items
Claudelist_projects
Claudelist_reports
Claudelist_workspaces
Clauderemove_items
Clauderename_project
Claudesearch_all_videos
Claudesearch_my_videos
Claudeswitch_workspace
Claudetop_formats
Claudetop_hooks
Claudetop_topics
Claudeupdate_automation_rule
Claude