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 13 read tools; a read+write credential sees all 18.

Write tools (5) — 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 video — analyze_tiktok_video. Analyze a TikTok video or photo slideshow by URL (/video/ or /photo/ links). Consumes one catalog slot. TikTok URLs only: YouTube Shorts are analyzed in the fypnow.com web app, not here.
  Quota: Catalog slot — standing cap, does not reset. 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).
• 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. 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.
• 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.

Read tools (13) — 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.
  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.
  Quota: Free — does not draw down any plan quota.
• Browse niche catalogue — browse_niche_catalog. Browse available niches with their stats and metadata. Returns niches only, not videos, and carries no per-video AI analysis; that lives behind analyze_tiktok_video.
  Quota: Free — does not draw down any plan quota.
• Get niche videos — get_niche_videos. Top videos in one niche, ranked by how far they outperformed the niche's median (multiplier). Takes a niche id from browse_niche_catalog. 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 comes from analyze_tiktok_video, which takes its URL; that tool does not accept YouTube Shorts. 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.
• 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.
• 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.