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 API key sees only the read tools; a read+write key sees all 14.

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 by URL. Consumes one catalog slot.
  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 — poll GET /v1/trends/search/{job_id} until status is "completed", then read the results from that response.
  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. Always returns a job handle (202), never the script itself — generation can take up to a minute. Poll GET /v1/scripts/jobs/{job_id} until status is "completed", then fetch the script from result_path.
  Quota: Script — monthly allowance.
• Save video to library — save_video. Save a video to the workspace library.
  Quota: Free — does not draw down any plan quota.

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

• Search videos — search_videos. Search analyzed videos in this workspace by username, view count, or date range.
  Quota: Free — does not draw down any plan quota.
• Get video analysis — get_video_analysis. Full AI analysis for one video: hook, timing, scenes, transcript.
  Quota: Free — does not draw down any plan quota.
• Find similar videos — find_similar_videos. Find videos similar to a given video using vector search.
  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. Does not return videos, and carries no per-video AI analysis — that requires analyze_tiktok_video.
  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.