hooklayer

analyze_account

Idempotent

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).

Input Schema

TableJSON Schema

Name	Required	Description
`since`	No	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.
`handle`	Yes	Creator handle (with or without @ prefix) or YouTube channel ID. Examples: "@mrbeast", "mrbeast", "UCX6OQ3DkcsbYNE6H8uQQuVA".
`window`	No	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.
`platform`	No	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.
`recent_only`	No	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.

Output Schema

TableJSON Schema

Name	Required	Description
`profile`	No	Creator profile (handle, bio, followers, following, total_likes, total_videos)
`from_payg`	No	Whether credits came from pay-as-you-go balance
`steal_map`	No	Actionable elements to replicate from this creator
`viral_dna`	No	Five viral DNA scores (0-100 each)
`content_gaps`	No	Untapped content opportunities the creator is missing
`recent_videos`	No	Top recent videos with view counts, transcripts, and engagement
`headline_insight`	No	The largest quantified performance gap for this creator, plus its implication. Presentation-neutral data — the caller decides whether and how to surface it.
`pattern_analysis`	No	Content pattern breakdown (posting cadence, topic clusters)
`credits_remaining`	No	Credits remaining after this call
`from_subscription`	No	Whether credits came from subscription
`recommended_chain`	No	Suggested next tool calls with pre-filled parameters — advisory only, agent decides whether to execute
`format_fingerprint`	No	Dominant content format patterns (durations, styles, edit types)

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 4, 2026

changedOutput schema / properties / recommended_chain / items / properties / side_effects / description

Previous value: -"Always \"none\" — all tools are read-only"New value: +"Service-side effects this step would cause, stated honestly. HookLayer never modifies TikTok, Instagram, YouTube or TikTok Shop accounts or content. It DOES change internal HookLayer state: every billable tool debits the credit balance and writes a usage record, watch_account persists a creator watch, and get_changes / product_scout persist snapshots and history. Use \"none\" only for a tool that charges nothing and writes nothing (list_watches)."

Changed1 schema field changedJul 31, 2026

addedOutput schema / properties / headline_insight

Added value: +{
+  "description": "The largest quantified performance gap for this creator, plus its implication. Presentation-neutral data — the caller decides whether and how to surface it.",
+  "properties": {
+    "confidence": {
+      "description": "Confidence in the headline insight; lower on thin (<8 videos) or stale (>30 days) samples.",
+      "enum": [
+        "high",
+        "medium",
+        "low"
+      ],
+      "type": "string"
+    },
+    "so_what": {
+      "description": "The one concrete change the wow gap implies, stated in a single line.",
+      "type": "string"
+    },
+    "wow": {
+      "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.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

Changed2 schema fields changedJul 7, 2026

changedInput schema / properties / platform / description

Previous value: -"Platform to analyze. \"tiktok\" (default) returns full pipeline with transcripts. \"youtube\" analyzes the channel's recent Shorts via YouTube Data API + Innertube caption extraction (v1.1, 2026-06-10) — videos with captions disabled or geoblocked resolve to transcript: null and the response flags how many were extracted. Instagram ships in v1.2."New value: +"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."

changedInput schema / properties / platform / enum

Previous value: -[
-  "tiktok",
-  "youtube"
-]New value: +[
+  "tiktok",
+  "youtube",
+  "instagram"
+]

Changed1 schema field changedJun 10, 2026

changedInput schema / properties / platform / description

Previous value: -"Platform to analyze. \"tiktok\" (default) returns full pipeline with transcripts. \"youtube\" analyzes the channel's recent Shorts via YouTube Data API; transcript extraction ships in v1.1 — meta-analysis still runs on titles, durations, hashtags, and engagement stats. Instagram ships in v1.2."New value: +"Platform to analyze. \"tiktok\" (default) returns full pipeline with transcripts. \"youtube\" analyzes the channel's recent Shorts via YouTube Data API + Innertube caption extraction (v1.1, 2026-06-10) — videos with captions disabled or geoblocked resolve to transcript: null and the response flags how many were extracted. Instagram ships in v1.2."

Changed3 schema fields changedJun 10, 2026

addedInput schema / properties / recent_only

Added value: +{
+  "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.",
+  "type": "boolean"
+}

addedInput schema / properties / since

Added value: +{
+  "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.",
+  "type": "string"
+}

addedInput schema / properties / window

Added value: +{
+  "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.",
+  "enum": [
+    "24h",
+    "7d",
+    "30d",
+    "90d",
+    "6m",
+    "12m",
+    "this-month"
+  ],
+  "type": "string"
+}

Changed3 schema fields changedMay 27, 2026

changedInput schema / properties / handle / description

Previous value: -"TikTok handle, with or without @ prefix (e.g. \"@mrbeast\" or \"mrbeast\")"New value: +"Creator handle (with or without @ prefix) or YouTube channel ID. Examples: \"@mrbeast\", \"mrbeast\", \"UCX6OQ3DkcsbYNE6H8uQQuVA\"."

changedInput schema / properties / platform / description

Previous value: -"Platform — currently only \"tiktok\" is supported"New value: +"Platform to analyze. \"tiktok\" (default) returns full pipeline with transcripts. \"youtube\" analyzes the channel's recent Shorts via YouTube Data API; transcript extraction ships in v1.1 — meta-analysis still runs on titles, durations, hashtags, and engagement stats. Instagram ships in v1.2."

addedInput schema / properties / platform / enum
```
Added value: +[
+  "tiktok",
+  "youtube"
+]
```

Changed1 schema field changedMay 15, 2026

addedOutput schema / properties / recommended_chain / items / properties / action_class

Added value: +{
+  "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.",
+  "enum": [
+    "research",
+    "synthesize",
+    "draft",
+    "publish",
+    "account"
+  ],
+  "type": "string"
+}

Changed2 schema fields changedMay 14, 2026

changedOutput schema / properties / recommended_chain / description

Previous value: -"Pre-filled next tool calls (match_voice, trend_pulse, viral_remix)"New value: +"Suggested next tool calls with pre-filled parameters — advisory only, agent decides whether to execute"

addedOutput schema / properties / recommended_chain / items / properties

Added value: +{
+  "confidence": {
+    "description": "Signal-derived confidence that this step will produce useful results",
+    "enum": [
+      "high",
+      "medium",
+      "low"
+    ],
+    "type": "string"
+  },
+  "cost": {
+    "description": "Credit cost for this tool call",
+    "type": "number"
+  },
+  "expected_output": {
+    "description": "One-line summary of what this tool returns",
+    "type": "string"
+  },
+  "params": {
+    "description": "Pre-filled parameters for the tool",
+    "type": "object"
+  },
+  "reason": {
+    "description": "Why this step is recommended",
+    "type": "string"
+  },
+  "side_effects": {
+    "description": "Always \"none\" — all tools are read-only",
+    "type": "string"
+  },
+  "tool": {
+    "description": "Exact tool name to call",
+    "type": "string"
+  }
+}

Changed1 schema field changedMay 14, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "content_gaps": {
+      "description": "Untapped content opportunities the creator is missing",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "credits_remaining": {
+      "description": "Credits remaining after this call",
+      "type": "number"
+    },
+    "format_fingerprint": {
+      "description": "Dominant content format patterns (durations, styles, edit types)",
+      "type": "object"
+    },
+    "from_payg": {
+      "description": "Whether credits came from pay-as-you-go balance",
+      "type": "boolean"
+    },
+    "from_subscription": {
+      "description": "Whether credits came from subscription",
+      "type": "boolean"
+    },
+    "pattern_analysis": {
+      "description": "Content pattern breakdown (posting cadence, topic clusters)",
+      "type": "object"
+    },
+    "profile": {
+      "description": "Creator profile (handle, bio, followers, following, total_likes, total_videos)",
+      "type": "object"
+    },
+    "recent_videos": {
+      "description": "Top recent videos with view counts, transcripts, and engagement",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "recommended_chain": {
+      "description": "Pre-filled next tool calls (match_voice, trend_pulse, viral_remix)",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "steal_map": {
+      "description": "Actionable elements to replicate from this creator",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "viral_dna": {
+      "description": "Five viral DNA scores (0-100 each)",
+      "properties": {
+        "audience_fatigue": {
+          "type": "number"
+        },
+        "consistency_score": {
+          "type": "number"
+        },
+        "originality_score": {
+          "type": "number"
+        },
+        "replicability_score": {
+          "type": "number"
+        },
+        "viral_dna_score": {
+          "type": "number"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

First observedMay 14, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: YouTube videos with captions disabled or geoblocked resolve to transcript: null, Instagram lacks lifetime totalLikes so it defaults to 0, and an empty filter match returns a warning with no credits charged. It does not explain the general credit cost implied by readOnlyHint=false, so it falls short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but well front-loaded: purpose and return payload come first, then usage trigger, then platform support. Platform capabilities are stated twice (opening sentence and closing sentence), which is mild redundancy, but every sentence carries substantive information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't enumerate return values, and it covers usage, platform scope, and platform-specific limitations, so an agent has enough to call it correctly. Minor gaps remain around credit cost and when to choose this over watch_account, but nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents handle, since, window, platform, and recent_only in detail, including the since/window mutual exclusion. The description only restates that input is a handle or channel ID and describes per-platform behavior rather than adding parameter-level meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (analyze) and resource (creator account by handle or channel ID) and enumerates the concrete outputs (viral DNA scores, format fingerprint, headline_insight). It clearly separates itself from siblings like watch_account or predict_virality by scoping to one-shot account analysis across three named platforms.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use when the user asks to analyze a creator, account, channel, or competitor,' which gives the agent a clear trigger condition. However, it never names an alternative or exclusion — for example, when to prefer watch_account for ongoing monitoring versus this one-shot analysis — so routing among siblings is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All hooklayer tools Inspect

Try in Browser

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

analyze_account

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources