> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videngineer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discovery

> Public teardown search (find_teardowns) and semantic recommend mode on find_analyses. Cold-start and library shortlists for agents.

Discovery tools answer: **what should I study?** — either from the **public study library** or from **your own analyses** via semantic recommend.

Parent: [Connector API](/agents/connector-api). Both tools are **`mcp:read`**, free.

***

## Status notes (read first)

| Surface                                  | State                                                                                                                                                |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `find_teardowns`                         | Live against the published catalog. Ranked shortlist + analyze affordance.                                                                           |
| `find_analyses` keyword filters          | Live (query / hook / format / sort / limit).                                                                                                         |
| `find_analyses` **`intent` (recommend)** | Mechanism live; production **`reference_index` empty until labeler backfill** (Mark-gated). Expect honest empty: `recommendation: true`, `count: 0`. |

The connector is **live on every paid plan** — one-click hosted connect or a local API key. See the intro page.

***

## `find_teardowns`

Find **public study-library** teardowns to reference. Free read-only search over the published catalog (**not** your private library). Returns a ranked shortlist with permalinks and `analyze.source_url` when available. Pass that URL to `analyze_video()` to run a full teardown into your own library.

Filters combine with **AND**. `tags` accepts canonical keys from any of the seven tag dimensions (storytelling approach, opening hook, production style, techniques to study, job of the video, length, platform) — call [`list_teardown_tags`](#list_teardown_tags) for the vocabulary. `hook_type` is a real filter: it is the same thing as the matching `hook-*` tag and joins the AND-set. Length and platform tags (`under-30s`, `youtube`, …) are derived from the teardown itself, so they always work.

**Charges:** read-only, 0 credits. **Scope:** `mcp:read`. Annotation title: *Find public teardowns to study*.

**Byte budget:** `limit ≤ 5` — full projection, per-item ≤ **650 B**, response ≤ **4,096 B** compact. `limit > 5` — every item switches to the **compact projection** (`slug, title, category, tags, views, duration_s, permalink`), response ≤ **12,288 B** (titles clip before anything else drops), and the envelope reports `projection: "compact"`. Open any compact item with `get_teardown(slug)`.

### Parameters

| Name        | Type        | Allowed / notes                                                                                                                                                                                            | Default |
| ----------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `goal`      | string      | Free-text goal (cleaned, max **100** chars); bag match over title/category/brand/industry/channel/facets/keywords/tag labels                                                                               | `""`    |
| `format`    | string      | Facet slug whitelist: `ads`, `launch`, `documentary`, `tutorial`, `ugc`, `animation`, `motion-graphics`, `kids`, `cinematic`, `manifesto`, `comedy`, `founder-led`, `hero-ads`. Unknown → no format filter | `""`    |
| `tags`      | string\[]   | Canonical tag keys; every tag must match (AND). Unknown key → empty result (never silently dropped)                                                                                                        | `[]`    |
| `hook_type` | string enum | `""` or one of: `promise`, `contradiction`, `big_claim`, `question`, `cold_open`, `story_open`, `reveal`, `pattern_interrupt`. Maps to the `hook-*` tag. Unknown value → ignored                           | `""`    |
| `quality`   | string      | `viral` (≥1M views), `hot` (250k–1M), `new`, `4k`. Unknown → no quality filter                                                                                                                             | `""`    |
| `limit`     | int         | Clamped 1–**25**; above 5 the response is compact                                                                                                                                                          | `5`     |
| `offset`    | int         | Clamped 0–**200**; pages the same ranked order; echoed in the envelope when > 0                                                                                                                            | `0`     |

Zero matches relax: drop `quality` → drop `format` → keep `goal`; `tags` and `hook_type` are never relaxed. The response may report `relaxed: [...]`. A `hook_type` that contradicts a selected `hook-*` tag is an honest empty (exclusive dimension).

### Example call

```text theme={null}
find_teardowns(goal="launch video", quality="viral", limit=5)
```

### Example response (trimmed — real cold-start result)

Measured: 5 of 6 matches; top ranks Apple MacBook Neo, Notion AI, Gala Film, MacBook Pro M5, Google Vids. Structure from the live tool + E2E transcript:

```json theme={null}
{
  "total_matched": 6,
  "returned": 5,
  "limit": 5,
  "note": "Ranked public study library — curated teardowns, not your analyses.",
  "teardowns": [
    {
      "slug": "apple-hello-macbook-neo-launch-film-teardown",
      "title": "Hello, MacBook Neo",
      "category": "Launch videos",
      "brand": "Apple",
      "quality_labels": ["viral"],
      "metrics": { "views": 34813265 },
      "permalink": "/teardowns/…",
      "reason": "34.8M-view launch video · viral · matches “launch”",
      "analyze": {
        "tool": "analyze_video",
        "source_url": "https://www.youtube.com/watch?v=…",
        "ref_slug": "apple-hello-macbook-neo-launch-film-teardown"
      }
    }
  ],
  "affordance": {
    "prompt": "Want me to analyze one like this?",
    "call": "analyze_video(teardowns[i].analyze.source_url)",
    "fallback": "no source_url → hand the user the permalink; signup CTA /signup?next=/app#new?ref=<slug>&format=<facet>"
  }
}
```

*(Full five-item payload omitted above — response is marked trimmed. Real wire size \~5.2 KB.)*

### Growth loop

```text theme={null}
find_teardowns(goal, quality)
  → pick teardowns[i]
  → analyze_video(teardowns[i].analyze.source_url)
  → get_report(job_id) / list_cuts / get_cut / …
```

No automatic analyze. The agent (and user) choose which reference to pull into the private library.

***

## `list_teardown_tags`

Discover the vocabulary for `find_teardowns`: the seven dimensions, canonical tag keys, labels, one-line definitions, aliases, and how many **published** teardowns carry each tag. Also returns `formats` (facet slug → label), `quality` keys, `hook_type_values` (enum → `hook-*` tag), and `semantics` (`tags: AND`, `exclusive_dimensions`, `derived_dimensions`).

**Charges:** read-only, 0 credits. **Scope:** `mcp:read`. Annotation title: *Discover teardown tags and filters*. **Byte budget:** response ≤ **12,288 B** compact (≈9.1 KB for the full registry with counts).

| Name             | Type   | Allowed / notes                                                                                                     | Default |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------- | ------- |
| `dimension`      | string | `approach`, `hook`, `production`, `technique`, `intent`, `length`, `platform` — narrows to one group; unknown → all | `""`    |
| `include_counts` | bool   | Per-tag published counts                                                                                            | `true`  |

```text theme={null}
list_teardown_tags(dimension="hook")
```

## Tag schema

**The full filter vocabulary.** Every tag `find_teardowns` accepts, grouped by dimension. Pass a tag's **key** (the code value); tags combine with **AND**. `list_teardown_tags` returns this same list live with per-tag published counts — treat the tool as the source of truth if this table and it ever differ. Tags are a study-and-reference lens on the public library, layered on top of `format` (which owns the permalink). Every tag is populated from what the teardown already is; **length** and **platform** are read straight from the video, so they always filter, while the richer dimensions fill in as the library is reviewed.

### Storytelling approach — *how the video makes its case*

| Tag                | Key                   | What it means                                                                        |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------ |
| Founder-led        | `founder-led`         | A founder is visibly present or is the narrative voice.                              |
| Product demo       | `product-demo`        | The product is shown in use or walked through.                                       |
| Product-led        | `product-led`         | Product behavior or proof carries the story.                                         |
| Vlog               | `vlog`                | Diary, build-in-public, day-in-life, or episodic personal format.                    |
| YouTubers          | `youtubers`           | Creator-led YouTube production patterns useful to founders and teams.                |
| Problem → solution | `problem-to-solution` | Opens on a pain or frustration, then reveals the product as the fix. Study the turn. |
| Testimonial        | `testimonial`         | A customer or user speaks for the product; proof comes from their voice.             |
| Comparison         | `comparison`          | Sets the product against an alternative, an old way, or a competitor side by side.   |
| Montage-led        | `montage-led`         | Rhythm and accumulation of shots carry the message more than any single scene.       |

### Opening hook — *the device the first seconds use to earn attention* · one per video

| Tag               | Key                      | What it means                                                     |
| ----------------- | ------------------------ | ----------------------------------------------------------------- |
| Cold open         | `hook-cold-open`         | Drops you into action or a scene with no setup.                   |
| Big claim         | `hook-big-claim`         | Leads with a bold statement the rest of the video has to back up. |
| Contradiction     | `hook-contradiction`     | Opens by breaking an expectation or a "you'd think…" assumption.  |
| Question          | `hook-question`          | Opens on a question the viewer wants answered.                    |
| Story open        | `hook-story-open`        | Opens on a character or situation and lets narrative pull you in. |
| Promise           | `hook-promise`           | Tells you what you'll get if you keep watching.                   |
| Reveal            | `hook-reveal`            | Opens by unveiling the product or a result.                       |
| Pattern interrupt | `hook-pattern-interrupt` | Opens with something visually or sonically out of place.          |

`hook_type` on `find_teardowns` is the same thing as the matching `hook-*` tag — either one filters this dimension.

### Production style — *how it was made; what your team would need*

| Tag              | Key                | What it means                                                              |
| ---------------- | ------------------ | -------------------------------------------------------------------------- |
| Live action      | `live-action`      | Shot footage carries the piece; graphics are supporting.                   |
| Animated         | `animated`         | 2D/3D or illustrated animation carries the piece.                          |
| Mixed media      | `mixed-media`      | Live footage blended with motion graphics or UI animation.                 |
| Screen capture   | `screen-capture`   | The interface itself is the footage for a large share of the runtime.      |
| No voiceover     | `no-voiceover`     | Music, sound and on-screen text do the talking — no narration or dialogue. |
| Generative video | `generative-video` | Footage is largely generated rather than shot or animated by hand.         |

### Techniques to study — *craft moves you can point your editor at*

| Tag               | Key                 | What it means                                                                     |
| ----------------- | ------------------- | --------------------------------------------------------------------------------- |
| Split screen      | `split-screen`      | Two or more frames share the screen to compare, multitask or build rhythm.        |
| Match cuts        | `match-cuts`        | Shapes or motion carry across cuts so scenes feel continuous.                     |
| Kinetic type      | `kinetic-type`      | Animated typography is a primary storytelling layer.                              |
| Product hero shot | `product-hero-shot` | The product gets a staged, lit, centerpiece moment.                               |
| Direct to camera  | `direct-to-camera`  | Someone talks straight to the lens — talking head, confessional, piece to camera. |
| Macro inserts     | `macro-inserts`     | Extreme close-up details punctuate the edit.                                      |
| Reaction shots    | `reaction-shots`    | Cutaways to faces reacting carry the comedy or the stakes.                        |

### Job of the video — *what the video was built to do* · one per video

| Tag                | Key                  | What it means                                          |
| ------------------ | -------------------- | ------------------------------------------------------ |
| Built to sell      | `built-to-sell`      | Drives a signup, purchase or install.                  |
| Built to teach     | `built-to-teach`     | Explains how something works or how to do it.          |
| Built to entertain | `built-to-entertain` | Earns the watch with comedy, spectacle or story first. |
| Built to inspire   | `built-to-inspire`   | Brand belief, manifesto or mood; the ask is emotional. |

### Length — *runtime band, read from the video* · one per video, automatic

| Tag       | Key          | What it means                |
| --------- | ------------ | ---------------------------- |
| Under 30s | `under-30s`  | Runs under 30 seconds.       |
| 30–60s    | `30-60s`     | Runs 30 to 60 seconds.       |
| 1–2 min   | `1-2-min`    | Runs one to two minutes.     |
| 2–5 min   | `2-5-min`    | Runs two to five minutes.    |
| 5+ min    | `5-min-plus` | Runs five minutes or longer. |

### Where it ran — *source platform, read from the public link* · one per video, automatic

| Tag         | Key         | What it means                      |
| ----------- | ----------- | ---------------------------------- |
| YouTube     | `youtube`   | Published on YouTube.              |
| X (Twitter) | `x-twitter` | Published on X (formerly Twitter). |

## `get_teardown`

Open one public teardown's study detail by slug (from `find_teardowns`). Fixed envelope: `slug, title, category, format, brand, industry, logline, tags_by_dimension, tags, quality_labels, metrics, duration_s, platform, permalink, source_url, study, related, analyze, note`. `study` is a bounded projection of the same report layers the public page renders — `hook {type, text, strength}`, up to 6 `beats`, up to 4 `insights`, `stats`, `blueprint`, `music`, `no_voiceover` — and is `null` (with `note: "study detail unavailable"`) when artifacts cannot be read. `related` = up to three same-format-first teardowns. Unknown and unpublished slugs return the same `{"error": "Teardown not found"}` body.

**Charges:** read-only, 0 credits. **Scope:** `mcp:read`. Annotation title: *Open one public teardown's study detail*. **Byte budget:** ≤ **3,072 B** compact (shrink order: insights → beats → logline → related; permalink / analyze / tags never drop).

```text theme={null}
get_teardown("coinbase-break-the-cycle-manifesto-teardown")
```

## `find_analyses` — recommend mode (`intent`)

Full parameter table for the keyword path lives on [Analyses → find\_analyses](/agents/api-analyses). This section documents **only** the semantic path.

When `intent` is non-empty, the server takes the recommendation path: up to five semantically relevant references from **your** library with inspectable scores — when the index has rows.

**Charges:** read-only, 0 credits.

**Byte budget:** empty envelope **58 B compact** / \~177 B wire (measured). Filled shortlists stay small by design (top-5).

### Parameters (intent path)

| Name            | Type   | Allowed / notes                                                                              | Default |
| --------------- | ------ | -------------------------------------------------------------------------------------------- | ------- |
| `intent`        | string | Natural-language goal (max **500** chars on the wire). Presence switches to recommend        | `""`    |
| (other filters) | —      | Still accepted on the tool; recommend envelope is the response when `recommendation` is true | —       |

### Example call

```text theme={null}
find_analyses(intent="launch video")
```

### Example response (production today — honest empty)

```json theme={null}
{"recommendation": true, "count": 0, "analyses": [], "bytes": 58}
```

This is expected until Mark runs the **labeler / `reference_index` backfill**. Do not invent ranks. Keyword search still works:

```text theme={null}
find_analyses(query="launch", sort="viral", limit=5)
```

***

## When to use which

| User has                  | Ask                                       | Tool                                                |
| ------------------------- | ----------------------------------------- | --------------------------------------------------- |
| Empty library             | “Any viral launch videos I should study?” | `find_teardowns`                                    |
| Many own analyses         | “Which of mine matter for a launch?”      | `find_analyses` keyword, or `intent` after backfill |
| A public permalink chosen | “Analyze this one into my library”        | `analyze_video` with `analyze.source_url`           |
| Need a cut inside one job | after analyze / pick job                  | [Cuts](/agents/api-cuts)                            |

***

## Scopes (hosted OAuth)

| Scope         | Tools on this page                                                             |
| ------------- | ------------------------------------------------------------------------------ |
| `mcp:read`    | `find_teardowns`, `list_teardown_tags`, `get_teardown`, `find_analyses`        |
| `mcp:analyze` | (next step) `analyze_video` — not a discovery tool, but the growth-loop target |