Intent Cookbook

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

REST: intent is required on POST /v1/agents. MCP: 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.

For AI assistants: load the MCP resource virlo://docs/intent-cookbook, or fetch the plain-text copy at /intent-cookbook.txt — same content without site chrome.

What intent does

Intent works at two layers:

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:

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

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

Good intents (from production)

These patterns came from agents with high link volume and useful filter rates (enough drops to prove the filter is working, not so many that the niche is empty).

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 (MCP used to synthesize this)	`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 workflow

Recommended path for assistants:

Draft intent with the user (use the formula above).
suggest_keywords (free) with that intent → check quality.passes. If false, sharpen intent and retry.
search_keywords or create_niche_monitor with the same intent + returned keywords / exclude_keywords.
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.