hooklayer

Analyze a TikTok, YouTube, or Instagram creator by handle or channel ID. Returns viral DNA scores (viral_dna_score, replicability_score, originality_score, consistency_score, audience_fatigue), content patterns, format fingerprint, top recent videos with transcripts, content gaps, a headline_insight object (the single largest quantified performance gap across length, hook, format, and cadence, plus its so_what), and suggested next research steps. Use when the user asks to analyze a creator, account, channel, or competitor. Supports TikTok (full transcript extraction), YouTube (Shorts and longform analysis with captions when available), and Instagram (Reels with best-effort transcripts).

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "description": "Creator handle (with or without @ prefix) or YouTube channel ID. Examples: \"@mrbeast\", \"mrbeast\", \"UCX6OQ3DkcsbYNE6H8uQQuVA\"."
    },
    "platform": {
      "type": "string",
      "enum": [
        "tiktok",
        "youtube",
        "instagram"
      ],
      "description": "Platform to analyze. \"tiktok\" (default) returns full pipeline with transcripts. \"youtube\" analyzes recent Shorts via YouTube Data API + Innertube caption extraction — videos with captions disabled or geoblocked resolve to transcript: null. \"instagram\" (shipped 2026-07-06) fetches the creator's reels via ScrapeCreators Instagram API + best-effort reel transcripts on the top 5 — Instagram data lacks lifetime totalLikes so that field defaults to 0."
    },
    "since": {
      "type": "string",
      "description": "Optional ISO date (e.g. \"2026-04-01\"). Filter the candidate video pool to those posted on/after this date. Useful when the user asks \"show me what they've done THIS month\" — the route returns honest empty + warning when the filter matches 0, no credits charged. Use either `since` or `window`, not both."
    },
    "window": {
      "type": "string",
      "enum": [
        "24h",
        "7d",
        "30d",
        "90d",
        "6m",
        "12m",
        "this-month"
      ],
      "description": "Recency sugar — same effect as `since` but takes a friendlier bucket. Maps to a since-cutoff at request time. Use either `since` or `window`, not both."
    },
    "recent_only": {
      "type": "boolean",
      "description": "When true, hard-cap the candidate pool to videos posted in the last 90 days. Stricter than `window=90d` because it never falls through to archival data on a thin recent corpus."
    }
  },
  "required": [
    "handle"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "profile": {
      "type": "object",
      "description": "Creator profile (handle, bio, followers, following, total_likes, total_videos)"
    },
    "headline_insight": {
      "type": "object",
      "properties": {
        "wow": {
          "type": "string",
          "description": "The single most material finding in the account's data: the dimension (video length, hook type, format, posting cadence, or topic) with the largest quantified performance gap, stated with two real numbers from the creator's videos. Not a restated score."
        },
        "so_what": {
          "type": "string",
          "description": "The one concrete change the wow gap implies, stated in a single line."
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low"
          ],
          "description": "Confidence in the headline insight; lower on thin (<8 videos) or stale (>30 days) samples."
        }
      },
      "description": "The largest quantified performance gap for this creator, plus its implication. Presentation-neutral data — the caller decides whether and how to surface it."
    },
    "viral_dna": {
      "type": "object",
      "properties": {
        "viral_dna_score": {
          "type": "number"
        },
        "replicability_score": {
          "type": "number"
        },
        "originality_score": {
          "type": "number"
        },
        "consistency_score": {
          "type": "number"
        },
        "audience_fatigue": {
          "type": "number"
        }
      },
      "description": "Five viral DNA scores (0-100 each)"
    },
    "format_fingerprint": {
      "type": "object",
      "description": "Dominant content format patterns (durations, styles, edit types)"
    },
    "pattern_analysis": {
      "type": "object",
      "description": "Content pattern breakdown (posting cadence, topic clusters)"
    },
    "recent_videos": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Top recent videos with view counts, transcripts, and engagement"
    },
    "steal_map": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Actionable elements to replicate from this creator"
    },
    "content_gaps": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Untapped content opportunities the creator is missing"
    },
    "recommended_chain": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tool": {
            "type": "string",
            "description": "Exact tool name to call"
          },
          "params": {
            "type": "object",
            "description": "Pre-filled parameters for the tool"
          },
          "reason": {
            "type": "string",
            "description": "Why this step is recommended"
          },
          "confidence": {
            "type": "string",
            "enum": [
              "high",
              "medium",
              "low"
            ],
            "description": "Signal-derived confidence that this step will produce useful results"
          },
          "cost": {
            "type": "number",
            "description": "Credit cost for this tool call"
          },
          "side_effects": {
            "type": "string",
            "description": "Always \"none\" — all tools are read-only"
          },
          "action_class": {
            "type": "string",
            "enum": [
              "research",
              "synthesize",
              "draft",
              "publish",
              "account"
            ],
            "description": "Authority taxonomy: research (read-only data gathering, lowest authority), synthesize (generate content in-memory, low), draft (save to workspace, medium), publish (post to external platforms, HIGH), account (modify account/billing, HIGHEST). All Hooklayer v1 tools are research or synthesize."
          },
          "expected_output": {
            "type": "string",
            "description": "One-line summary of what this tool returns"
          }
        }
      },
      "description": "Suggested next tool calls with pre-filled parameters — advisory only, agent decides whether to execute"
    },
    "credits_remaining": {
      "type": "number",
      "description": "Credits remaining after this call"
    },
    "from_subscription": {
      "type": "boolean",
      "description": "Whether credits came from subscription"
    },
    "from_payg": {
      "type": "boolean",
      "description": "Whether credits came from pay-as-you-go balance"
    }
  }
}

Start tracking a creator so future calls can detect what changed. Creates a durable CreatorWatch + a baseline CreatorSnapshot capturing the creator's current viral DNA scores, format fingerprint, and top recent videos. Use when the user says 'track', 'watch', 'follow', 'keep an eye on' a creator/channel/handle. Idempotent — calling 'watch @same' twice with a fresh baseline in place returns the existing watch with credits_charged=0. Cost: 0 credits when a fresh existing watch snapshot or a compatible recent analyze_account cache can be reused. Otherwise a fresh baseline invokes analyze_account and costs 5 credits — this can happen even for an already-existing watch once freshness expires. Reuses the same 'analyze' permission as analyze_account — no new OAuth scope, no re-consent required.

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "description": "Creator handle (with or without @ prefix). Examples: \"@mrbeast\", \"mrbeast\"."
    },
    "platform": {
      "type": "string",
      "enum": [
        "tiktok",
        "instagram",
        "youtube"
      ],
      "description": "Platform the creator publishes on. Same platforms as analyze_account."
    }
  },
  "required": [
    "handle",
    "platform"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "tracked",
        "already_tracked"
      ]
    },
    "watch_id": {
      "type": "string"
    },
    "creator": {
      "type": "string",
      "description": "Normalized \"@handle\" the watch is stored under"
    },
    "platform": {
      "type": "string",
      "enum": [
        "tiktok",
        "instagram",
        "youtube"
      ]
    },
    "baseline_created_at": {
      "type": "string",
      "description": "ISO timestamp of the baseline snapshot"
    },
    "baseline_source": {
      "type": "string",
      "enum": [
        "watch_snapshot",
        "analysis_cache",
        "fresh"
      ],
      "description": "watch_snapshot = existing CreatorWatch already had a fresh snapshot (0 credits); analysis_cache = recent analyze_account response reused to build a new baseline (0 credits); fresh = analyze_account invoked, 5 credits charged."
    },
    "credits_charged": {
      "type": "number"
    },
    "data_age_days": {
      "type": "number",
      "description": "Age in days of the newest video in the baseline"
    },
    "snapshot_count": {
      "type": "number",
      "description": "Total snapshots stored for this watch so far"
    },
    "message": {
      "type": "string"
    }
  }
}

Detect what changed since the last saved baseline for a tracked creator. Runs a fresh analyze_account under the hood, compares against the most recent CreatorSnapshot, persists the new snapshot, and returns ONLY the meaningful shifts (format, viral DNA, engagement, hook pattern, topic pillars, outlier videos). Use when the user asks 'what changed with @creator', 'anything new', 'check this competitor again', 'what's different since last time', 'check my tracked creator', or 'has anything changed'. Requires a previously tracked creator (call analyze_account + watch_account first if there is no baseline yet). Costs 5 credits per call because the fresh analysis is genuine (not cached). Returns a top_action pointing at the single next tool worth calling given the detected change. Returns status='no_meaningful_change' honestly when nothing shifted — no fabricated deltas.

{
  "type": "object",
  "properties": {
    "watch_id": {
      "type": "string",
      "description": "Watch identifier returned by watch_account or list_watches. Preferred over (platform, handle) when you have it — the ownership check is exact."
    },
    "platform": {
      "type": "string",
      "enum": [
        "tiktok",
        "instagram",
        "youtube"
      ],
      "description": "Platform the tracked creator publishes on. Required if watch_id is not provided."
    },
    "handle": {
      "type": "string",
      "description": "Creator handle (with or without @). Required if watch_id is not provided."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "changes_found",
        "no_meaningful_change",
        "baseline_refreshed",
        "not_tracked",
        "no_baseline"
      ],
      "description": "changes_found = meaningful shifts detected; no_meaningful_change = fresh analysis ran, nothing shifted enough to matter; baseline_refreshed = prior snapshot used an incompatible schema, new baseline saved; not_tracked = no active CreatorWatch for that creator; no_baseline = watch exists but has no snapshots yet."
    },
    "creator": {
      "type": "string"
    },
    "platform": {
      "type": "string",
      "enum": [
        "tiktok",
        "instagram",
        "youtube"
      ]
    },
    "previous_snapshot_at": {
      "type": "string"
    },
    "current_snapshot_at": {
      "type": "string"
    },
    "meaningful_changes": {
      "type": "number",
      "description": "Count of high + medium importance changes."
    },
    "high_importance": {
      "type": "number"
    },
    "medium_importance": {
      "type": "number"
    },
    "changes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "change_type": {
            "type": "string",
            "enum": [
              "viral_dna_shift",
              "engagement_shift",
              "follower_shift",
              "format_shift",
              "hook_pattern_shift",
              "topic_shift",
              "outlier_emergence"
            ]
          },
          "importance": {
            "type": "string",
            "enum": [
              "high",
              "medium",
              "low"
            ]
          },
          "before": {},
          "after": {},
          "delta": {
            "type": "number"
          },
          "delta_pct": {
            "type": "number"
          },
          "evidence": {
            "type": "string"
          },
          "why_it_matters": {
            "type": "string"
          },
          "recommended_action": {
            "type": "object",
            "properties": {
              "tool": {
                "type": "string"
              },
              "reason": {
                "type": "string"
              },
              "params": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "top_action": {
      "type": "object",
      "description": "Single most useful next tool call given the detected changes. null when nothing meaningful shifted.",
      "properties": {
        "tool": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        },
        "params": {
          "type": "object"
        }
      }
    },
    "credits_charged": {
      "type": "number"
    },
    "snapshot_count": {
      "type": "number",
      "description": "Total snapshots saved for this watch after this call."
    }
  }
}

List every creator the authenticated user is tracking. Read-only, 0 credits. Returns each watch's id, platform, handle, when it was created + last updated, when the last snapshot was taken, and whether it's active. Does NOT return the snapshot payload itself — call watch_account (idempotent) to refresh a baseline. Use when the user asks 'what am I tracking', 'show my watches', 'list creators'.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "watches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "watch_id": {
            "type": "string"
          },
          "platform": {
            "type": "string",
            "enum": [
              "tiktok",
              "instagram",
              "youtube"
            ]
          },
          "handle": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "last_snapshot_at": {
            "type": "string",
            "description": "null when no snapshot exists (rare — only if a persistence race happened)"
          },
          "snapshot_count": {
            "type": "number"
          },
          "is_active": {
            "type": "boolean"
          }
        }
      }
    },
    "total": {
      "type": "number"
    }
  }
}

Score a TikTok, Reels, or Shorts hook against proven viral patterns. Returns a 0-100 score, percentile rank, matched pattern, strengths, weaknesses, and three improved hook variations. Use when the user has a draft hook to validate, wants to compare alternatives, or needs feedback before publishing.

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "The hook to score (3-200 chars typical)"
    },
    "platform": {
      "type": "string",
      "enum": [
        "tiktok",
        "reels",
        "shorts"
      ],
      "description": "Target platform — affects pattern matching"
    },
    "niche": {
      "type": "string",
      "description": "Optional niche context (e.g. \"Beauty & Skincare\", \"Finance & Business\")"
    }
  },
  "required": [
    "text",
    "platform"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "score": {
      "type": "number",
      "description": "Hook quality score (0-100)"
    },
    "percentile": {
      "type": "number",
      "description": "Percentile rank vs all scored hooks"
    },
    "pattern_match": {
      "type": "string",
      "description": "Matched viral pattern name"
    },
    "rewrites": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Three rewritten versions at higher quality"
    },
    "why": {
      "type": "string",
      "description": "One-sentence verdict explaining the score"
    },
    "breakdown": {
      "type": "object",
      "properties": {
        "curiosity": {
          "type": "number"
        },
        "specificity": {
          "type": "number"
        },
        "urgency": {
          "type": "number"
        },
        "emotional_pull": {
          "type": "number"
        },
        "pattern_alignment": {
          "type": "number"
        }
      },
      "description": "Sub-scores (0-100) for five quality dimensions"
    },
    "strengths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "What the hook does well"
    },
    "weaknesses": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "What could be improved"
    },
    "credits_remaining": {
      "type": "number",
      "description": "Credits remaining after this call"
    },
    "from_subscription": {
      "type": "boolean",
      "description": "Whether credits came from subscription"
    },
    "from_payg": {
      "type": "boolean",
      "description": "Whether credits came from pay-as-you-go balance"
    }
  }
}

Take a viral video and produce a fresh script that mirrors its structure and energy pattern for a new topic. Returns the extracted formula, scene-by-scene script with voiceover and visuals, camera directions, and text overlays. Use when the user finds a video they want to replicate the structure of. Pass either a video URL (TikTok, YouTube, or Instagram) or a transcript directly. When promoting a specific product, ALWAYS pass target_product + verified_product_facts so the generator does not fabricate product details.

{
  "type": "object",
  "properties": {
    "source_url": {
      "type": "string",
      "description": "TikTok/YouTube/Instagram URL — transcript will be auto-extracted"
    },
    "transcript": {
      "type": "string",
      "description": "Pre-extracted transcript (alternative to source_url, faster)"
    },
    "target_topic": {
      "type": "string",
      "description": "What the remix should be about. Default: same niche as original."
    },
    "my_topic": {
      "type": "string",
      "description": "DEPRECATED alias for target_topic. Legacy clients only. Normalized internally."
    },
    "niche": {
      "type": "string",
      "description": "Optional niche hint"
    },
    "platform": {
      "type": "string",
      "enum": [
        "tiktok",
        "reels",
        "shorts"
      ],
      "description": "Target platform for the remix. Adjusts pacing and CTA style if provided."
    },
    "target_product": {
      "type": "string",
      "description": "The product the remix should promote. When provided, the generator will NOT invent product names, prices, timelines, features, or customer stories. Combined with verified_product_facts, this forces on-topic + grounded output."
    },
    "verified_product_facts": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Facts the generator is allowed to cite about target_product (e.g. \"runs inside ChatGPT and Claude\", \"12 tools for viral research\"). Every specific product claim in the generated script is checked against this list — unsupported claims populate unsupported_claims[] and downgrade quality. If target_product is passed WITHOUT verified_product_facts, the response will land at degraded quality (generation cannot be grounded)."
    }
  },
  "anyOf": [
    {
      "required": [
        "source_url"
      ]
    },
    {
      "required": [
        "transcript"
      ]
    }
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "extracted_formula": {
      "type": "string",
      "description": "The viral DNA formula extracted from the source"
    },
    "fresh_script": {
      "type": "object",
      "properties": {
        "hook": {
          "type": "string",
          "description": "Opening hook line"
        },
        "scenes": {
          "type": "array",
          "items": {
            "type": "object"
          },
          "description": "Scene-by-scene script with voiceover, visuals, and timing"
        },
        "cta": {
          "type": "string",
          "description": "Call-to-action closing"
        }
      },
      "description": "Complete scene-by-scene script mirroring the source structure"
    },
    "camera_shots": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Phone-native camera direction per scene"
    },
    "overlays": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Text overlay suggestions per scene"
    },
    "ugc_authenticity": {
      "type": "object",
      "properties": {
        "level": {
          "type": "string",
          "enum": [
            "native",
            "ad_leaning"
          ],
          "description": "Honest signal of whether the generator drifted ad-ward"
        },
        "reasons": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of detected drift reasons (e.g. \"hook is 22 words\", \"CTA is comment-gate\")"
        }
      },
      "description": "Tripwire for ad-shaped drift. Detected via regex on the produced script, not the model self-grade. If level=ad_leaning, surface to the user before shipping."
    },
    "cta_archetype": {
      "type": "string",
      "enum": [
        "result_close",
        "soft_bio_pointer",
        "genuine_question",
        "pinned_comment",
        "comment_gate"
      ],
      "description": "Which CTA archetype the generator picked. Comment_gate is the failure-mode default for AI script generators; rotation tells you whether the prompt is working."
    },
    "structural_skeleton": {
      "type": "string",
      "description": "Which structural skeleton the generator used (confession_to_result, mistake_to_correction, etc). Surfaces rotation across the fleet."
    },
    "verify_hook": {
      "type": "object",
      "description": "The hook plus a suggested follow-up: the caller may pass it to score_hook for a structurally-independent score (the script generator deliberately does NOT self-rate). Informational only, not an instruction to call anything."
    },
    "credits_remaining": {
      "type": "number",
      "description": "Credits remaining after this call"
    },
    "from_subscription": {
      "type": "boolean",
      "description": "Whether credits came from subscription"
    },
    "from_payg": {
      "type": "boolean",
      "description": "Whether credits came from pay-as-you-go balance"
    }
  }
}

Research what is currently gaining traction in short-form content for a specific niche. Returns rising opportunities (formats, hooks, styles, topics) with growth signals, data sources, and saturated patterns to avoid. Use when the user asks what to post about, what's trending in a niche, or needs to validate a content idea against current trends. Supports 17 niches and optional region filtering.

{
  "type": "object",
  "properties": {
    "niche": {
      "type": "string",
      "description": "One of the 17 supported niches. Loose names like \"travel\" or \"fitness\" are accepted but pass the canonical form when possible. Omit for broadly applicable trends.",
      "enum": [
        "Beauty & Skincare",
        "Fitness & Health",
        "Food & Cooking",
        "Fashion & Style",
        "Tech & Gadgets",
        "Finance & Business",
        "Education & Learning",
        "Travel & Adventure",
        "Comedy & Entertainment",
        "Gaming",
        "Lifestyle & Wellness",
        "Parenting & Family",
        "DIY & Crafts",
        "Music & Dance",
        "Pets & Animals",
        "Sports",
        "Motivation & Self-Help",
        "SaaS & AI Tools"
      ]
    },
    "region": {
      "type": "string",
      "description": "Optional 2-letter ISO country code (US, GB, BR, JP, IN, PH, etc.). Threads to Google Trends geo + YouTube regionCode. Defaults to US when omitted. Reddit signals are global and ignore this param."
    },
    "deadline_hours": {
      "type": "integer",
      "description": "Optional (2026-07-06 magic-genie ritual): how many hours until the video posts. When set, each rising trend gets a trend_status (up-slope | plateau | fading | unknown) AND a deadline_verdict (safe | risky | no-go) so managers can answer \"will this trend still be alive when the video posts?\" without eyeballing the growth label. Use this on every brief-just-landed call — it turns trend_pulse from \"what's trending\" into \"what's SAFE to bet on for MY post window.\"",
      "minimum": 1,
      "maximum": 168
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "niche": {
      "type": "string",
      "description": "The niche these trends apply to"
    },
    "rising": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "growth": {
            "type": "string",
            "description": "Qualitative growth label (\"Rising\", \"Early signal\", \"Accelerating\"). NOT a numeric percentage — the upstream does not compute \"+178%\"-style rates. Use signal_strength as the quantitative anchor."
          },
          "suggestion": {
            "type": "string"
          }
        }
      },
      "description": "Rising opportunities (format/hook/style) with qualitative growth labels + signal_strength numeric anchor (0-1) + suggestions"
    },
    "saturated": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "description": "Saturated patterns to avoid"
    },
    "credits_remaining": {
      "type": "number",
      "description": "Credits remaining after this call"
    },
    "from_subscription": {
      "type": "boolean",
      "description": "Whether credits came from subscription"
    },
    "from_payg": {
      "type": "boolean",
      "description": "Whether credits came from pay-as-you-go balance"
    }
  }
}

Find proven viral templates in a niche with example videos. Returns templates ranked by performance, including hook patterns, format structures, average views, and example URLs. Use when the user asks what's working in a niche or wants concrete copyable structures. Supports 17 niches with optional angle narrowing via query parameter for more specific results (e.g., "postpartum strength" within Fitness).

{
  "type": "object",
  "properties": {
    "niche": {
      "type": "string",
      "description": "One of the 17 supported niches. Loose names like \"travel\" or \"fitness\" are accepted but pass the canonical form when possible.",
      "enum": [
        "Beauty & Skincare",
        "Fitness & Health",
        "Food & Cooking",
        "Fashion & Style",
        "Tech & Gadgets",
        "Finance & Business",
        "Education & Learning",
        "Travel & Adventure",
        "Comedy & Entertainment",
        "Gaming",
        "Lifestyle & Wellness",
        "Parenting & Family",
        "DIY & Crafts",
        "Music & Dance",
        "Pets & Animals",
        "Sports",
        "Motivation & Self-Help",
        "SaaS & AI Tools"
      ]
    },
    "query": {
      "type": "string",
      "description": "Optional angle narrowing within the niche. E.g. niche=\"Fitness & Health\" + query=\"postpartum strength\" returns only postpartum-strength templates, not generic gym. Templates are scored by query-token match against title+description+hashtags; zero-match templates are dropped. Leave empty for niche-wide top templates."
    },
    "min_views": {
      "type": "integer",
      "minimum": 0,
      "description": "Optional filter — only return examples above this view count"
    },
    "window": {
      "type": "string",
      "enum": [
        "24h",
        "7d",
        "30d",
        "90d",
        "this-month"
      ],
      "description": "Recency filter. Drops example videos older than the window. Note: TikTok hashtag-corpus rows often lack timestamps and are excluded when window is set — surfaces as a quality warning so callers can decide whether to broaden."
    },
    "region": {
      "type": "string",
      "description": "Optional 2-letter ISO country code (US, GB, BR, JP, IN, PH, etc.). Threads to YouTube Search regionCode + TikTok niche query. Reddit niche signals are global and ignore this param. Pass when the user wants templates that resonate with a specific local audience."
    },
    "platform": {
      "type": "string",
      "enum": [
        "tiktok",
        "instagram"
      ],
      "description": "Platform to source templates from. \"tiktok\" (default) uses the full niche-aggregator (YouTube + Reddit + TikTok hashtags). \"instagram\" (2026-07-06) is keyword-search-only — the Instagram niche-aggregator isn't plumbed yet, so `query` becomes REQUIRED on IG. Output rubric_version signals which path ran: find_viral_template.v1 (main), .v2-keyword-fallback (TikTok fallback), .v3-instagram-keyword-only (IG-only path)."
    }
  },
  "required": [
    "niche"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "niche": {
      "type": "string",
      "description": "The niche searched"
    },
    "templates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "hook_pattern": {
            "type": "string"
          },
          "format": {
            "type": "string"
          },
          "avg_views": {
            "type": "number"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "description": "Ranked viral templates with hook patterns and example URLs"
    },
    "credits_remaining": {
      "type": "number",
      "description": "Credits remaining after this call"
    },
    "from_subscription": {
      "type": "boolean",
      "description": "Whether credits came from subscription"
    },
    "from_payg": {
      "type": "boolean",
      "description": "Whether credits came from pay-as-you-go balance"
    }
  }
}

Search for short-form videos by keyword across TikTok or Instagram. Returns up to 20 videos ranked by engagement, with view counts, likes, shares, comments, hashtags, author info, and URLs. Use when the user asks to find videos about a topic or keyword. Supports optional filters for niche, minimum views, recency window, and region.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Free-text search term. Examples: \"morning routine\", \"iphone case\", \"passive income\"."
    },
    "niche": {
      "type": "string",
      "description": "Optional — only return videos whose description contains niche-related tokens. Loose niche strings work (\"fitness\", \"Beauty & Skincare\")."
    },
    "min_views": {
      "type": "integer",
      "minimum": 0,
      "description": "Optional view-count floor. Default 0."
    },
    "window": {
      "type": "string",
      "enum": [
        "24h",
        "7d",
        "30d",
        "this-month"
      ],
      "description": "Recency filter. Maps to the closest ScrapeCreators date bucket AND applies a client-side cutoff for defense-in-depth."
    },
    "region": {
      "type": "string",
      "description": "ISO country code (US, GB, BR, PH, JP, etc.). Note: corpus coverage varies by region — small regions may return zero results and a degraded quality flag."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "Max videos to return after filtering. Default 12, max 20."
    },
    "platform": {
      "type": "string",
      "enum": [
        "tiktok",
        "instagram"
      ],
      "description": "Which platform to search. \"tiktok\" (default) hits ScrapeCreators TikTok keyword search. \"instagram\" (2026-07-06) hits Instagram Reels search — note IG upstream ignores region/date_posted params, so region enforcement is client-side only (region_verified_count in the response tells you how many results verifiably matched)."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "videos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "thumbnail": {
            "type": "string"
          },
          "views": {
            "type": "number"
          },
          "likes": {
            "type": "number"
          },
          "shares": {
            "type": "number"
          },
          "saves": {
            "type": "number"
          },
          "comments": {
            "type": "number"
          },
          "duration": {
            "type": "number"
          },
          "engagement_score": {
            "type": "number"
          },
          "hashtags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "posted_at": {
            "type": "string"
          },
          "author": {
            "type": "object",
            "properties": {
              "username": {
                "type": "string"
              },
              "nickname": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "upstream_count": {
      "type": "number",
      "description": "Videos returned by upstream before any filtering"
    },
    "filtered_count": {
      "type": "number",
      "description": "Videos returned after filtering + cap"
    },
    "applied": {
      "type": "object",
      "description": "Echo of the filters actually applied — useful for debugging when results look surprising"
    },
    "quality": {
      "type": "object",
      "properties": {
        "level": {
          "type": "string",
          "enum": [
            "full",
            "partial",
            "degraded"
          ]
        },
        "reason": {
          "type": "string"
        }
      }
    },
    "credits_remaining": {
      "type": "number",
      "description": "Credits remaining after this call"
    },
    "from_subscription": {
      "type": "boolean"
    },
    "from_payg": {
      "type": "boolean"
    }
  }
}

Extract a creator's voice DNA from reference samples and rewrite a draft in their style. Requires at least 3 reference samples (video URLs or text). Returns voice profile (energy, humor, vocabulary, signature phrases), reusable prompt instructions, and the rewritten draft. Use when the user wants to write in another creator's style or match a specific voice.

{
  "type": "object",
  "properties": {
    "draft": {
      "type": "string",
      "description": "The text to rewrite"
    },
    "reference_samples": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 3,
      "description": "At least 3 reference samples — TikTok/YouTube/Instagram URLs or raw text"
    }
  },
  "required": [
    "draft",
    "reference_samples"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "voice_profile": {
      "type": "object",
      "properties": {
        "energy": {
          "type": "string"
        },
        "humor": {
          "type": "string"
        },
        "vocabulary": {
          "type": "string"
        },
        "signatures": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Signature phrases and moves"
        }
      },
      "description": "Extracted voice DNA profile"
    },
    "prompt_instructions": {
      "type": "string",
      "description": "Reusable prompt to replicate this voice"
    },
    "rewritten_draft": {
      "type": "string",
      "description": "The input draft rewritten in the matched voice"
    },
    "credits_remaining": {
      "type": "number",
      "description": "Credits remaining after this call"
    },
    "from_subscription": {
      "type": "boolean",
      "description": "Whether credits came from subscription"
    },
    "from_payg": {
      "type": "boolean",
      "description": "Whether credits came from pay-as-you-go balance"
    }
  }
}

Score a draft script for viral potential with adversarial verification. Returns a virality score, recommendation (ship/rework/no-go), viral DNA breakdown with evidence, attack vectors analysis, and calibration metrics. Use when the user has a finished draft and wants pre-publish verification. Pass either a script string or a video URL.

{
  "type": "object",
  "properties": {
    "script": {
      "type": "string",
      "description": "The draft script to predict on (or a video URL — auto-extracts transcript)"
    },
    "niche": {
      "type": "string",
      "description": "Niche context"
    }
  },
  "required": [
    "script"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "virality_score": {
      "type": "number",
      "description": "Overall virality prediction (0-100)"
    },
    "viral_dna": {
      "type": "object",
      "description": "Hook type, structure, emotional triggers breakdown"
    },
    "blueprint": {
      "type": "object",
      "description": "Retention diagnosis with weak seconds identified"
    },
    "target_emotion": {
      "type": "string",
      "description": "Primary emotion the content targets"
    },
    "share_reason": {
      "type": "string",
      "description": "Why viewers would share this content"
    },
    "credits_remaining": {
      "type": "number",
      "description": "Credits remaining after this call"
    },
    "from_subscription": {
      "type": "boolean",
      "description": "Whether credits came from subscription"
    },
    "from_payg": {
      "type": "boolean",
      "description": "Whether credits came from pay-as-you-go balance"
    }
  }
}

Turn a brand brief that just landed into a one-page creative blueprint the manager can forward to the creator and to the brand contact — hook + template + hashtag combo + trend-velocity check + shoot instructions, in one call. Use when a brand sends a product and needs content on a tight turnaround (e.g. "product arrived, need content in 48 hours") and the manager needs a defensible direction with no research time. Chains find_viral_template + trend_pulse + score_hook + predict_virality upstream but exposes them as one MCP tool so agents don't stitch them manually. Cost 7 credits (bundle discount vs firing the chain manually). Returns a blueprint object with verdict (GO | NEEDS_MORE_DATA | NO_GO) and verdict_reason, a hook (text + trend_still_alive: up-slope | plateau | fading | unknown), script, hashtags, shoot notes, risk flags, and manager talking points, plus a quality object (level + reason) describing completeness; when quality.level is not "full", or verdict is NEEDS_MORE_DATA or NO_GO, the blueprint is a starting point rather than a shippable direction.

{
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "description": "What the brand sent (name + one line, e.g. \"Athletic Greens AG1 travel packs — 30-count individual sachets for travel\")"
    },
    "product_category": {
      "type": "string",
      "description": "Umbrella category (e.g. \"greens powder\", \"sunscreen\", \"protein bar\")"
    },
    "niche": {
      "type": "string",
      "description": "One of the 17 supported niches. Loose names like \"beauty\" or \"fitness\" are auto-mapped.",
      "enum": [
        "Beauty & Skincare",
        "Fitness & Health",
        "Food & Cooking",
        "Fashion & Style",
        "Tech & Gadgets",
        "Finance & Business",
        "Education & Learning",
        "Travel & Adventure",
        "Comedy & Entertainment",
        "Gaming",
        "Lifestyle & Wellness",
        "Parenting & Family",
        "DIY & Crafts",
        "Music & Dance",
        "Pets & Animals",
        "Sports",
        "Motivation & Self-Help",
        "SaaS & AI Tools"
      ]
    },
    "deadline_hours": {
      "type": "integer",
      "description": "How many hours until the video must be posted. Default 48. Affects trend-still-alive scoring — a 24-hour deadline needs a trend on the up-slope, not one that just plateaued.",
      "minimum": 1,
      "maximum": 168
    },
    "creator_handle": {
      "type": "string",
      "description": "Optional creator handle (with or without @). If provided, the blueprint hook and script match THEIR voice patterns from recent videos. Highly recommended — a blueprint without creator context is generic."
    },
    "platform": {
      "type": "string",
      "description": "Target platform. Both TikTok and Instagram Reels supported (shipped 2026-07-06). When set to \"instagram\", the product-corpus lookup runs against Instagram Reels via ScrapeCreators, and the creator context (if creator_handle passed) fetches Instagram reels. Default: tiktok.",
      "enum": [
        "tiktok",
        "instagram"
      ]
    },
    "region": {
      "type": "string",
      "description": "Optional 2-letter ISO country code (US, GB, CA, etc.). Threads to niche + trend upstreams."
    }
  },
  "required": [
    "product",
    "product_category",
    "niche"
  ]
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "blueprint": {
      "type": "object",
      "properties": {
        "verdict": {
          "type": "string",
          "enum": [
            "GO",
            "NEEDS_MORE_DATA",
            "NO_GO"
          ]
        },
        "verdict_reason": {
          "type": "string"
        },
        "hook": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string"
            },
            "pattern": {
              "type": "string"
            },
            "why_this_hook": {
              "type": "string"
            },
            "trend_still_alive": {
              "type": "string",
              "enum": [
                "up-slope",
                "plateau",
                "fading",
                "unknown"
              ]
            }
          }
        },
        "script": {
          "type": "object"
        },
        "hashtags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "shoot_notes": {
          "type": "object"
        },
        "why_this_will_land": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "risk_flags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "manager_talking_points": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "applied": {
      "type": "object",
      "description": "Echo of parameters resolved after canonicalization"
    },
    "stats": {
      "type": "object",
      "properties": {
        "niche_templates": {
          "type": "integer"
        },
        "rising_trends": {
          "type": "integer"
        },
        "product_videos": {
          "type": "integer"
        },
        "creator_context_available": {
          "type": "boolean"
        }
      }
    },
    "quality": {
      "type": "object",
      "properties": {
        "level": {
          "type": "string",
          "enum": [
            "full",
            "partial",
            "degraded"
          ]
        },
        "reason": {
          "type": "string"
        }
      }
    },
    "provenance": {
      "type": "object"
    },
    "as_of": {
      "type": "string"
    },
    "credits_remaining": {
      "type": "object",
      "properties": {
        "subscription": {
          "type": "number"
        },
        "payg": {
          "type": "number"
        },
        "total": {
          "type": "number"
        }
      }
    }
  }
}