# Virlo API — Intent Cookbook

`intent` is the single highest-leverage field on a Content Research Agent. Keywords cast the net; intent decides what stays. This cookbook is grounded in production agents that returned hundreds to thousands of on-topic videos.

REST: intent is required on POST /v1/agents.
MCP: intent is required on search_keywords / create_niche_monitor.
Prefer drafting keywords with free POST /v1/agents/suggest-keywords (MCP: suggest_keywords) using the SAME intent string.

Human docs: https://dev.virlo.ai/docs/intent-cookbook

## What intent does

| Layer | When | What it does |
|---|---|---|
| Collection filter | Every run | Drops off-topic videos → run metric intent_filtered |
| intent_match | Only with data_intelligence_enabled: true | Post-analysis AI judgment per video → filter ?intent_match=true |

A sharp intent + 6–10 multi-word keywords is the production sweet spot (median ~280–330 videos linked with a healthy 10–35% filter rate). Vague intents either over-filter (near-zero results) or under-filter (junk).

## The formula

Write one concrete sentence (about 40–250 characters) that covers:

1. Goal — find / monitor / extract hooks / surface outliers
2. Niche — specific topic, not a single bare word
3. Content type — GRWM, tutorials, UGC ads, carousels, fight highlights…
4. Boundary — who/what to exclude when it matters

Template:
[Find/Monitor] [content type] about [niche] for [use case], [not / exclude X].

## Good intents (from production)

Specific goal + format + audience:
- Find GRWM / beginner morning skincare routines and honest drugstore product reviews that show a simple everyday glow-up — not dermatologist lectures or brand-only ads.
- Find top viral auto detailing videos and extract hooks and topics for short-form scripts.
- Find outlier creators making JavaScript and web-dev education content — proven hooks, formats, and visual styles to adapt for faceless carousel tutorials.

Commercial / app-download angle (tight exclusions):
- Find viral Gen Z creator videos that sell a photo, video, or AI-image mobile app and push a download: before/after, app demo, screen recording, "this app is called" reveals. Exclude desktop-software tutorials, generic photography tips, and posts that never name an app.

Funnel / ICP research:
- Find outlier short-form content for marketing operators Virlo sells to: agencies, DTC marketers, UGC creators, indie builders. Surface formats and hooks in marketing/creator-business niches — not consumer product niches.

Pedagogy / adjacent niches:
- Study outlier content in teaching-heavy niches that make complex topics engaging, so we can borrow pedagogy and format patterns for coding education.

Recurring monitor with a clear "why":
- Monitor UFC / MMA highlight and betting-prediction content to track which fight-night hooks and formats keep winning week over week.

What these share: a verb, a content shape, a niche, and (when needed) an exclude. Keywords then cover synonyms of the SAME concept (6–10 phrases), not a random keyword salad.

## Bad intents (avoid these)

| Anti-pattern | Example | Why it fails |
|---|---|---|
| Keyword dump | Keyword research: jeep, fitness, gym | Restates keywords; gives the filter nothing new to judge |
| Monitor dump | Monitor niche: handmade, crafts, diy | Same problem on recurring agents |
| Too vague | I want to find viral video | No niche, no format → empty or random |
| Keyword list as intent | skin / curly hair / good hooks / viral video | Not a sentence; filter can't reason |
| Over-constrained + thin keywords | Long precise intent + only 1–3 generic keywords | Filter rate → 100%, zero linked videos |
| Topic ≠ language | English intent + english_only: false without target-language keywords | Little or nothing returns |

Never invent intent from keywords. If you only have keywords, write a real sentence first (or call suggest_keywords / POST /v1/agents/suggest-keywords), then create the agent. Synthesized intents like "Keyword research: a, b, c" are the weak pattern we see in production.

## MCP / assistant workflow

1. Draft intent with the user (use the formula above).
2. suggest_keywords (free) with that intent → check quality.passes. If false, sharpen intent and retry.
3. search_keywords or create_niche_monitor with the SAME intent + returned keywords / exclude_keywords.
4. After the run, read intent_filtered vs videos_linked. With Data Intelligence on, filter intent_match=true on videos.

suggest_keywords({ intent })  →  free, sync
search_keywords({ intent, keywords, … })  →  paid CRA run

## How to tell it worked

| Signal | Healthy | Unhealthy |
|---|---|---|
| videos_linked | Hundreds+ for a normal niche | 0–20 with broad keywords |
| intent_filtered / (linked + filtered) | ~10–40% | 0% (intent ignored) or >70% (too tight / bad keywords) |
| intent_match (DI on) | Meaningful true/false split | All null → DI off or intent missing |

If quality is poor: sharpen intent first, then refresh keywords with suggest_keywords (mode: "refresh") — don't just add more single-word keywords.

See also: https://dev.virlo.ai/docs/agents · https://dev.virlo.ai/docs/intelligence · https://dev.virlo.ai/agent-playbook.txt · https://dev.virlo.ai/docs/mcp