MCP tool reference

This list is generated from api/routes.py — the same table that drives REST dispatch, so a tool here can never describe a different endpoint than the one it actually calls. A read-only credential sees only the 18 read tools; a read+write credential sees all 32.

Write tools (14) — require a read+write key

Every write tool asks for per-call confirmation in Claude — it carries `destructiveHint: true` because it spends a quota that does not refund.

• Analyze TikTok or YouTube Short — analyze_tiktok_video. Analyze a TikTok video or photo slideshow (/video/ or /photo/ links) or a YouTube Short (youtube.com/shorts/, youtube.com/watch?v= or youtu.be/ links) by URL. Consumes one catalog slot.
  Quota: Catalog slot — standing cap, does not reset; a slot frees at the end of the UTC day a video is dropped. Reaches TikTok directly (may take longer than a lookup).
• Create niche agent — create_niche. Create a Viral Content Agent that watches a niche by keyword.
  Quota: Custom niche (Viral Content Agent) slot — standing cap. Reaches TikTok directly (may take longer than a lookup).
• Update niche agent — update_niche. Rename a Viral Content Agent, change its 1-3 keywords, and/or set auto_analyse_mode: 'off', 'winners' (each refresh's top 10 by multiplier) or 'all' (every new video), or 'default' for the plan default (off on Creator, all on other plans). Changed keywords re-seed the niche. Auto-analysis uses one catalog slot per video, highest multiplier first, and stops when the catalog is full.
  Quota: Free — does not draw down any plan quota.
• Stop niche agent — stop_niche. Stop a Viral Content Agent. Its slot frees at the next UTC midnight and resume_niche reverses it.
  Quota: Free — does not draw down any plan quota.
• Resume niche agent — resume_niche. Resume a stopped Viral Content Agent. Needs a free niche slot.
  Quota: Free — does not draw down any plan quota.
• Track creator — track_creator. Track a TikTok creator by username or profile URL. Adds the creator to the workspace and scrapes their latest videos in the background; returns a job handle (202). A creator already tracked returns already_tracked, a stopped one is reported as creator_stopped.
  Quota: Free — does not draw down any plan quota. Reaches TikTok directly (may take longer than a lookup).
• Stop tracking creator — stop_tracking_creator. Stop tracking a creator. Their videos are dropped from the catalog (analyses are kept, frozen); resume_tracking_creator reverses it.
  Quota: Free — does not draw down any plan quota.
• Resume tracking creator — resume_tracking_creator. Track a stopped creator again. Videos dropped since the last UTC midnight come back with it.
  Quota: Free — does not draw down any plan quota.
• Drop video from catalog — drop_video. Drop a video from the catalog. The analysis is kept, frozen, and the catalog slot frees at the next UTC midnight.
  Quota: Free — does not draw down any plan quota.
• Restore dropped video — undrop_video. Restore a dropped video to the catalog. Needs a free catalog slot.
  Quota: Catalog slot — standing cap, does not reset; a slot frees at the end of the UTC day a video is dropped.
• Search viral trends — search_viral_trends. Search for breakout videos by hashtag. A cached hashtag returns full results right away. An uncached one returns a job handle (202) with no results yet; that handle is resolved by get_trend_search_result, which reports status complete or error and carries the results.
  Quota: Trend search — monthly allowance, resets on your billing day. Reaches TikTok directly (may take longer than a lookup).
• Generate script — generate_script. Generate a script grounded in the workspace top performers. Returns a job handle (202) rather than the script itself, because generation takes up to a minute. The handle is resolved by get_script_result, which reports status completed or failed and carries the script.
  Quota: Script — monthly allowance, resets on your billing day.
• Save video to library — save_video. Save a video to the workspace library. Works for TikToks and YouTube Shorts; pass platform ('tiktok' or 'youtube') from get_niche_videos, or omit it and a YouTube-shaped id is saved as a Short.
  Quota: Free — does not draw down any plan quota.
• Remove video from library — remove_from_library. Remove a video from the library.
  Quota: Free — does not draw down any plan quota.

Read tools (18) — work with a read-only key

• Get analysis result — get_analysis_result. Resolves the job handle returned by analyze_tiktok_video into the finished analysis. Status is processing, completed or failed, and the response carries a retry_after_seconds hint for how long to wait between attempts while it is still processing. A failed job also carries a machine-readable error_code (for example rate_limited or limit_reached; null when none was recorded) next to the error text.
  Quota: Free — does not draw down any plan quota.
• Get script result — get_script_result. Resolves the job handle returned by generate_script into the finished script. Status is processing, completed or failed, and the response carries a retry_after_seconds hint for how long to wait between attempts while it is still processing.
  Quota: Free — does not draw down any plan quota.
• Get trend search result — get_trend_search_result. Resolves the job handle returned by search_viral_trends into the finished results. Status is pending, complete or error, and the response carries a retry_after_seconds hint for how long to wait between attempts. A search already in flight is resolved here; starting another for the same hashtag spends a second viral search from the monthly allowance.
  Quota: Free — does not draw down any plan quota.
• Search videos — search_videos. Search analyzed videos and slideshows in this workspace by username, view count, date range, or format ('video' or 'slideshow'). Each row carries platform ('tiktok' or 'youtube') and post_format ('photo' carousel, 'slideshow' template, 'video', or null for a video).
  Quota: Free — does not draw down any plan quota.
• Get video analysis — get_video_analysis. Full AI analysis for one video or slideshow. A video returns hook, timing, scenes and transcript; a slideshow (schema_version carousel_v1) returns cover, slide-by-slide breakdown, narrative, aesthetic, audio, swipe and save drivers, and scores.
  Quota: Free — does not draw down any plan quota.
• Find similar videos — find_similar_videos. Find videos or slideshows similar to a given one using vector search. Each row carries post_format.
  Quota: Free — does not draw down any plan quota.
• List breakouts — list_breakouts. List videos currently breaking out among tracked creators. Pass username to see one creator's breakouts.
  Quota: Free — does not draw down any plan quota.
• Browse niche catalogue — browse_niche_catalog. Browse available niches and their metadata, including catalog_video_count (an approximate count of the videos the niche's catalogue holds, a cached counter updated by the nightly refresh). The workspace's own custom niches come first, then the global catalogue. Each niche has a status: 'active', or 'stopped' (no longer refreshing, but its videos are still there to read). auto_analyse_effective says how its videos get analysed automatically: a global niche ('winners', auto_analyse_shared true) has each refresh's top 10 analysed by fypnow for everyone, free; a custom niche runs 'off', 'winners' or 'all' into this workspace, one catalog slot per video (auto_analyse_mode is the stored choice, null = plan default), and auto_analyse_paused_reason 'catalog_full' means it stopped because the catalog is full (upgrade or free slots). Paginated: when meta.has_more is true, request the next page. Returns niches only, not videos, and carries no per-video AI analysis; that lives behind analyze_tiktok_video. Per-niche numbers (typical views, breakouts, top creators, hashtags) come from get_niche_stats.
  Quota: Free — does not draw down any plan quota.
• Get niche videos — get_niche_videos. Top videos in one niche, ranked by multiplier: the video's views divided by its creator's follower count (subscribers for YouTube). As an MCP tool it takes the niche's name (e.g. 'forex'; matched case-insensitively on name, then slug, then singular/plural ('protein noodle' finds 'Protein Noodles'), then the niche's keywords, preferring your own niche over a global one) or a niche id from browse_niche_catalog: pass the name directly rather than browsing first. Your stopped niches still answer; meta.niche gives the niche's status ('active' or 'stopped') and last_refreshed_at, so say when a stopped niche last refreshed. Over REST the id is in the path. Returns catalogue stats — views, likes, author, multiplier, platform — not per-video AI analysis. Niches mix TikToks and YouTube Shorts; platform is 'tiktok' or 'youtube'. A hook and scene teardown of a TikTok or a Short comes from analyze_tiktok_video, which takes its video_url. Rows carry no hook data; the top hooks in a niche come from get_niche_hooks. Each row carries post_format; the format input ('video' or 'slideshow') narrows the list to one.
  Quota: Free — does not draw down any plan quota.
• Get niche hooks — get_niche_hooks. The top hooks in one niche: hook types from the niche's most viral videos (its top 100 catalogue rows by multiplier) that this workspace has analysed. Takes the niche's name (matched like get_niche_videos) or a niche id. Hooks come from videos this workspace has analysed with analyze_tiktok_video and, for a global niche, from the top videos fypnow analyses for everyone after each refresh (examples carry shared: true); catalogue rows carry no hook data, and other workspaces' analyses are never used. Returns hooks (per hook_type: videos, avg_multiplier and up to 3 examples with hook_text, best first, ordered by how many top videos use the hook), analysed_count, catalog_considered, and next_to_analyse: the next most viral unanalysed videos (slideshows left out, since their analysis has no hook), each with a ready video_url for analyze_tiktok_video. limit sizes next_to_analyse (default 10, max 25). When few or none are analysed, the answer is to offer analysing next_to_analyse; each analysis costs one catalog slot, and nothing is analysed without the user agreeing. meta.niche gives the niche and its status.
  Quota: Free — does not draw down any plan quota.
• Get niche stats — get_niche_stats. Stats for one niche from its nightly snapshot: typical post views, breakout posts (3x or more the creator's followers), active creators and views on this week's top posts, each next to the snapshot from a week earlier; top and rising creators, sounds in use, top hashtags, posting times, the top 3 posts this week, posts and breakouts per posting day, and the daily snapshot series. Takes a niche id from browse_niche_catalog. The numbers describe the top posts the nightly crawl keeps per niche (about 50 a night, about 100 for custom niches), not all of TikTok. latest is null until the first nightly snapshot, and week-over-week comparisons need a week of snapshots.
  Quota: Free — does not draw down any plan quota.
• List creators — list_creators. List tracked creators in this workspace, with their ids.
  Quota: Free — does not draw down any plan quota.
• Get creator report — get_creator_report. Profile, follower history and winning patterns for one creator.
  Quota: Free — does not draw down any plan quota.
• List scripts — list_scripts. List generated scripts in this workspace.
  Quota: Free — does not draw down any plan quota.
• Get script — get_script. Fetch one generated script by id.
  Quota: Free — does not draw down any plan quota.
• List library — list_library. List videos saved to the workspace library.
  Quota: Free — does not draw down any plan quota.
• Get growth scorecard — get_growth_scorecard. Grade the workspace own account against its niche benchmarks.
  Quota: Free — does not draw down any plan quota.
• Get account usage — get_account_usage. Current plan allowances and consumption. Free and unmetered.
  Quota: Free — does not draw down any plan quota.

Every tool returns a machine-readable code on failure (e.g. write_scope_required, catalog_full) rather than a bare string — see REST reference for the full error-code table, which applies identically over MCP.