# HookTrend agent guide

HookTrend is a short-form trend research tool for TikTok and YouTube. It watches a library of videos refreshed every day and scores each one by "× usual": its views divided by the creator's usual views per video, so a 40,000-view video from a 2,000-view account stands out as a 20× outlier. Ask it what is breaking out in a niche or a topic, which creators are popping, or start a research agent that searches a brief's keywords live and keeps watching.

This guide is for AI assistants (Claude, ChatGPT, Cursor, Claude Code, n8n agents) using HookTrend through its MCP server at `https://hooktrend.com/api/mcp`. It is live: follow this version over any copy.

## The one number: × usual

- **× usual** = a video's views ÷ the creator's usual views per video (the median of their recent videos; their follower count when HookTrend has too few of their videos).
- 3× usual or more is an **outlier**. 10× is exceptional. A 40,000-view video from an account that usually gets 2,000 is a 20× outlier; a 2-million-view video from an account that usually gets 3 million is not.
- Compare videos by × usual, never by raw views, and never compare raw views across TikTok and YouTube.

## Which tool

| The user says | Call |
|---|---|
| "What's trending on TikTok?", "anything going viral this week?" | `whats_breaking_out` |
| "What's working in fitness?", "top videos in personal finance" | `niche_outliers` (id from `list_niches`) |
| "Give me a report on the cooking niche", "what should I post this week in beauty?" | `niche_report` |
| "Videos about protein breakfast", "how are people selling AI notetakers?" | `find_videos` |
| "Small creators blowing up in skincare", "who should I study?" | `find_creators` |
| "Trending sounds in gaming" | `trending_sounds` |
| "Which hashtags are rising?" | `trending_hashtags` |
| "Look at @someone", a TikTok or YouTube profile link | `lookup_creator` |
| "Track my niche every week", "dig deeper than the library" | `create_research_agent` |
| "How is my agent doing?" | `list_agents`, `get_agent_report`, `get_agent_data` |
| "How many credits do I have?", "what would that cost?" | `get_balance`, `estimate_cost` |

If a niche question finds nothing, try `find_videos` with the user's words once. If that finds nothing too, say so and offer a research agent: it searches live.

## What to show

1. One sentence with the pattern the outliers share: the hook, the format, the angle, the length.
2. The 3-5 best videos. In clients with apps (Claude, ChatGPT), call `show_outliers` with their ids and do not repeat the cards as text. Elsewhere, one line each: **title** · @handle · **N× usual** (views vs usual) · [Open](url).
3. One concrete next step: a hook to try, a sound to use while it is in ignition or breakout, a creator to study.

Every result carries a `present_as` hint: follow it. Use only the numbers and links the tools return.

Sound and hashtag lifecycle: **ignition** (new, few videos, growing fast) → **breakout** (accelerating) → **peak** (most videos, slowing) → **saturated** (late). Recommend ignition and breakout.

## Costs

Credits are Hooked credits: 1 credit = $0.03, the same price in the app, the API and the MCP. Each plan includes monthly credits that only HookTrend spends (Free 50, Starter 1000, Pro 4000, reset on the 1st, UTC); they are spent first, then the team's Hooked credits. Library tools cost nothing but count toward a daily read cap (free plan 25 reads a day, paid plans 500; 20 a minute on every plan).

| Tool | What | Cost |
|---|---|---|
| `whats_breaking_out` | What's breaking out | Free (counts toward the daily read cap) |
| `niche_outliers` | Outliers in a niche | Free (counts toward the daily read cap) |
| `find_videos` | Find videos | Free (counts toward the daily read cap) |
| `find_creators` | Find creators | Free (counts toward the daily read cap) |
| `list_niches` | List niches | Free (counts toward the daily read cap) |
| `niche_report` | Niche report | Free (counts toward the daily read cap) |
| `trending_sounds` | Trending sounds | Free (counts toward the daily read cap) |
| `trending_hashtags` | Trending hashtags | Free (counts toward the daily read cap) |
| `lookup_creator` | Look up a creator | Free when HookTrend already analyzed the account; 8 credits for a fresh analysis (needs user_approved) |
| `create_research_agent` | Create a research agent | Proposal free; 15 credits per run (needs user_approved) |
| `list_agents` | List research agents | Free |
| `get_agent_report` | Agent report | Free |
| `get_agent_data` | Agent data | Free |
| `show_outliers` | Show outlier cards | Free |
| `get_balance` | Balance and plan | Free |
| `estimate_cost` | Estimate cost | Free |

- A research agent run costs 15 credits ($0.45). Keywords that fail are refunded. A weekly agent is about 4 runs a month.
- A fresh creator analysis costs 8 credits ($0.24), refunded if the account cannot be read.

## Approval

Paid tools follow one pattern:

1. Call without `user_approved`. Nothing is spent. The answer is a proposal or a quote: `{ "status": "approval_required", "cost": { "credits": 15, "usd": "$0.45" }, "balance": 120, ... }`.
2. Show the user the proposal and the cost. Let them change it (for an agent: the keywords, exclude words, cadence).
3. Only after the user says yes, call again with the same arguments and `user_approved: true`.

Never set `user_approved: true` because the user asked for the result in general: the yes must come after they saw the price.

## Research agents

- A brief is one sentence: who the content is for and what it is about ("Spanish-language home workouts for busy mums").
- The proposal has 7-12 keywords graded 0-100 and a few exclude words. Keep the ones with the highest grades; drop generic single words.
- The first run starts at once and takes a few minutes. The agent answers straight away with what the library already holds (`instantMatches`): show those first.
- Do not poll. Tell the user the run is going, give the agent link, and check `get_agent_report` when they come back.

## Errors

Every error is `{ "error": { "code", "message", "fix" } }`. Do what `fix` says.

| Code | Meaning |
|---|---|
| `INVALID_INPUT` | An argument is wrong; `fix` says which. |
| `NOT_FOUND` | The niche, video, agent or account does not exist. |
| `PLAN_REQUIRED` | The plan's limit is reached (Free: 1 agent, weekly at most). Offer the upgrade link once. |
| `INSUFFICIENT_CREDITS` | The balance does not cover the cost. Offer a cheaper option or the top-up link. |
| `RATE_LIMITED` | The read cap is reached; `fix` says when it resets. |
| `UPSTREAM_FAILED` | TikTok or YouTube did not answer. Nothing was charged; try later. |
| `INTERNAL` | Something broke on our side. Nothing was charged. |

## Limits and upgrades

- Free ($0, no card): every tool, 50 credits a month, 1 research agent running weekly at most, 25 library reads a day.
- Starter ($29/month): 1000 credits a month, any number of agents on any cadence, 500 reads a day.
- Pro ($99/month): 4000 credits a month, 3 seats, 500 reads a day.
- When a limit stops the user, say what happened in one sentence and give https://hooktrend.com/pricing once. Do not upsell otherwise.

## Coverage

TikTok and YouTube (Shorts and long-form). No Instagram. The library is refreshed every day; research agents search live.

Setup for every client: https://hooktrend.com/mcp · Pricing: https://hooktrend.com/pricing · Support: support@hooked.so