Heista

Top Google search queries by clicks or impressions from first-party Search Console data, optionally filtered to pages containing a path (e.g. "/decode"). The core tool for briefing programmatic SEO. Hard cap 50 rows, max window 28 days. Read-only.

Canonical Ad Intelligence corpus counts — the single source of truth that kills number drift across marketing surfaces. Returns decoded ads published (THE number to quote publicly), total corpus size, live brand/category/weekly report counts, live categories and verticals, and the last publish timestamp. Use this BEFORE citing any corpus number in content, outreach, or briefs. Free, read-only, no parameters.

List live brand-level Ad Intelligence reports (the public /decode/brand pages). Optional brand-name filter, paginated, hard cap 50 rows. Returns identifiers + ad counts + public URLs; use fleet_get_brand_report for a full report. Read-only.

List live intelligence articles — the weekly and per-vertical category report system behind the public intelligence surfaces. Filter by kind (weekly/category) or vertical. Note: individual static deep-dive articles are not DB rows and are not listed here. Hard cap 50 rows. Read-only.

List issues on the Heista Linear board (team HEI) — the read-only window into what the dev agents are working on, what's broken, and what's shipped. Filter by workflow state ("Backlog"/"Todo"/"In Progress"/"In Review"/"Done"), label ("Bug"/"Security"/"SEO"/"In-App Feedback"/…), or a title search. Returns identifier + state + priority + assignee + labels; use fleet_get_issue for the full description + comments. Hard cap 100 rows. Read-only — the fleet cannot create, edit, or close tickets.

The signup -> trial -> paid funnel as COUNTS ONLY, with no customer PII scope required: signups, trials active, trials expired unconverted, converted to paid, onboarding completed, plus the conversion rate. Aggregated in the database — no identifiers are read or returned. Definitions mirror fleet_product_funnel_summary exactly so the two never disagree. Cohorts below 5 signups have their breakdown SUPPRESSED, because at that size a conversion count identifies an individual; widen the window instead. This is the product funnel (signup onward) — the marketing funnel before it (views, engaged, CTA) is fleet_analytics_overview.

Aggregate conversion/drop-off stats for a signup cohort (last N days, max 90): trial active vs expired-unconverted vs converted-to-paid, conversion rate, never-spent-a-credit rate, onboarding completion rate, and the most-installed Heists. Answers "where is the funnel leaking" in one call instead of aggregating individual summaries. Requires mcp:fleet:customer_pii. Every call is audit-logged. Read-only.

List recent signups (last N days, hard cap 50 rows) with the same product-backend shape as fleet_product_user_summary — trial/credits/plan/onboarding/Heists per user. Use to see the newest cohort at a glance before drilling into individuals. Requires mcp:fleet:customer_pii. Every call is audit-logged. Read-only.

Look up ONE customer's product-backend state by email: trial status, credit balance, workspace plan, installed Heists, onboarding completion, plus PostHog attribution/engagement signals (source, 30d activity, page journey). This is the data PostHog structurally cannot see — whether they actually have active credits, are on a paid plan, or installed anything. Requires mcp:fleet:customer_pii (a separate, PII-adjacent scope — see Docs/systems/fleet-access.md). Every call is audit-logged. Read-only.

Search the published Ad Intelligence corpus (the public decode gallery). Filter by free-text (name/tagline/brand), brand, category, vertical, or platform. Returns list rows with public URLs — never the full structural payload (use fleet_get_decoded_ad for that). Hard cap 50 rows per call; paginate with offset. Read-only.

One-row verification scorecard for the indexing-recovery plan (internal-linking-spec-v2): site-wide + /decode-specific orphan counts (200 but zero internal inlinks) from the latest crawl, Googlebot vs other-bot crawl activity over a window (default 7 days, max 180), and Google Search Console impressions/clicks/avg-position over the trailing 28 days — each figure compared against the pre-fix baseline (1,521 orphans, 7 Googlebot pages/wk, 2 GSC impressions). Use this to confirm PR-A/B/C landed and is moving the needle, not just that the code shipped. Read-only.

One-row health scoreboard from the weekly full-site crawl: total pages, OK/redirect/error counts, ORPHAN pages (200 but zero internal inlinks — the primary indexing-recovery target), thin pages, missing meta/titles, total internal links, last crawl time. Start here before drilling into fleet_site_pages. Read-only.

Internal links for one page: direction "in" = who links TO it (zero inlinks = orphan), "out" = what it links to. Link data comes from the first render of sitemap-listed pages (pagination-only links are not observed — which mirrors crawler discovery). Hard cap 200 rows. Read-only.

Filterable inventory of every sitemap-listed page with SEO facts (title, meta description, canonical, h1, word count, JSON-LD) and internal inlink/outlink counts from the weekly crawl. Filters: path_contains, orphans_only (zero inlinks), max_word_count (thin content), status, missing_meta. Sorted fewest-inlinks first — the pages Google cannot discover float to the top. Hard cap 100 rows. Read-only.

Generate direct-response video ad scripts by fusing a proven structural source (decoded ad or formula) with a brand's PowerSource. Output is feed-native ad copy for paid social (Meta, TikTok, Reels) in the brand's voice — hook, beat-by-beat body, CTA close, plus visual direction per beat. Takes source_id (from adformula_intelligence, decoder_intelligence, or decode_ad), source_type ("formula" or "decode"), powersource_id (from any create_powersource_*), and tunable params: count (1-5 variants, tensions and selling points auto-rotated across variants), script_mode ("blueprint" preserves source structure exactly, "remix" preserves psychology but writes original copy), duration (target seconds), audience, tension override, selling_points override, voice_mode ("creator" for UGC default, "brand" for owned channels), and idempotency_key. Use this when the user says "write me a script", "I need a TikTok script", "write an ad based on this", or wants shell-faithful replication of a proven winner in their own brand voice. REQUIRES both a structural source AND a powersource — guide the user through creating either if missing. Metered pricing — typically 2-5 credits per script (~2 credits for 15s, ~5 credits for 60s). Pre-flight reserves a 17-credit ceiling and refunds the difference after measurement. Do NOT use to discover sources — use decoder_intelligence or adformula_intelligence first. Do NOT use to extract brand intel — use create_powersource_url first.

Get one ad formulas preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get a brand's full canonical record — name, domain, voice (tone_of_voice), story, visual identity (logo, primary color, visual assets), and counts. Use to inspect what a brand carries before deciding which Heist context to run, or to read the brand voice directly when writing copy. Free, read-only.

Get one saved cards preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get one creative agents preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get one creative agent skills preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get one creative director playbooks preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Retrieve the full decode bundle for a previously-submitted ad, or poll the status of a running decode job. Takes a single job_id (UUID returned by decode_ad). Returns either status="processing" (call again in 15s) or the completed payload — exact transcripts per beat, director's read, per-cut visual data (shot_breakdown), visual psychology, behaviour biases, beat structure, hook classification, and runtime fields (active days on Meta Ad Library when the source supports it). Use this immediately after decode_ad and every 15 seconds until the job completes. Also use this to re-fetch a decode any time you need the full bundle for script writing (Path B) or as the source_id for generate_adscript (source_type="decode"). Free — billing happens at decode_ad submit time, not on retrieval. Do NOT use to discover or list decodes — use decoder_intelligence for browsing. Do NOT use to start a new decode — call decode_ad first.

Get one decoded ads preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get the current status of a specialist dispatch job started via dispatch_<specialist>_async. Returns { status: queued|running|completed|failed, result_text?, error_text?, error_class?, retry_count, elapsed_seconds, wait_ms_hint }. Call this repeatedly after a dispatch_*_async returns a job_id. Sleep wait_ms_hint milliseconds between calls. When status === "completed", read result_text as the specialist's full synthesis. When status === "failed", error_class tells you whether to retry (transient/scope/routing) or give up and synthesize around (permanent) per the fleet resilience pattern.

Read-only walk of a fleet session tree. Given any session_id in the tree (root, Head, Mastermind, or specialist sub-node) returns the full breakdown: every session row with depth + parent + agent_kind + node_label, the cost_events recorded against each, per-node self_cost_cents, total raw compute, tier markup estimate, and (after close_session_tree has run) the authoritative credits_charged + credits_refunded. Org-scoped: only sessions belonging to your org return data. Free — no compute cost. Use to render cost breakdown UIs, audit fleet spend, or verify a session's tree topology.

Browse proven hook patterns from Heista's corpus of decoded winning Meta/TikTok ads. Takes optional filters: vertical (e.g. BEAUTY_SKINCARE, SUPPLEMENTS, APPAREL), hook_type (e.g. CURIOSITY_SPIKE, CONTRADICTION, CALLOUT), and marketing_angle. Returns hook examples (the real opener lines from successful ads), pattern templates, the psychological mechanism behind why each one stops the scroll within the first 1.5 seconds, and runtime performance data (active days on Meta when available). Free, read-only, idempotent — no credits consumed. Use this when the user asks "what hooks stop the scroll", "give me hook ideas", "how should I open this ad", "show me hooks for [vertical]", or needs scroll-stopping openers grounded in proven patterns rather than guessed copy. Useful before writing a script — pair with adformula_intelligence or decoder_intelligence for the full beat structure. Do NOT use to decode a specific ad URL — use decode_ad. Do NOT use to generate finished scripts — use generate_adscript. Hooks here are pattern intelligence, not finished copy.

Get one static ads preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get one outfits preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Retrieve the full creative intelligence profile for a previously-submitted PowerSource scan, or poll the status of a running scan. Takes a job_id (UUID returned by any create_powersource_* tool) plus an optional include_raw flag (admin-only). Returns either status="processing" with partial progress or the completed bundle: brand identity, offer, 12 selling points, brand voice rules, buyer profile, 12 buyer tensions, angles, emotional arcs, ctas, proof, narrative. Use this immediately after any create_powersource_* call and every 3-5 seconds until status is "completed". During synthesis, partial intelligence appears progressively (buyer archetype first, then tensions, then angles) — inspect each poll response, useful signal arrives early. Also use this to re-fetch a finished PowerSource any time you need the brand layer for downstream work. Free — billing happens at submit time. Do NOT use to start a new scan — call create_powersource_url, _docs, or _full first. Do NOT use to retrieve a video decode — use get_decode.

Fetch one saved asset by id. Returns the full row including category, format, tags, body_text/html, signed media_url (if private storage), metadata, creator, brand, and timestamps. Use AFTER list_saved_assets to load the full record when the list projection is too sparse.

Fetch up to 50 saved assets by id in one round-trip. Use when an agent needs to pull a pre-selected set — e.g. resolving a saved_asset_picker context input on a Heist that requires N pinned assets. Missing or cross-workspace ids are silently dropped; compare returned items vs requested ids to detect drops.

Get one saved visual ideas preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Read a creative strategy in full by its powersource_id. Returns the same brand-merged bundle shape as get_powersource(data) — buyer profile, 12 behavioral tensions, angles, narrative direction, tone of voice, selling points, CTAs, proof, brand story, homepage data, offering — projected through the public PowerSource API serializer. Use this when you already have a powersource_id (from list_strategies) and want the full strategy payload in one call, without the job_id round-trip that get_powersource needs. Archived strategies are excluded by default (parity with list_strategies). Pass include_archived=true to read archived strategies. Read-only, free, account-scoped.

Get one models preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get one visuals preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Get one visual styles preset by id, including its full body payload (framework, agent config, etc.). Call the matching list tool first to discover ids. Free, read-only.

Cluster-level structural formulas derived from decoded ads. Heista-curated; served as a generation parameter. Read-only, free. Filter scope with only_workspace / only_official (mutually exclusive — same toggle as the in-app library lens). Page with limit + offset.

List images for a brand. Filter by PowerSource (this scan only, via powersource_id), by on-pack product_name (the vision tagger's read), by type (logo, product, product_cutout, hero, lifestyle, ingredient, packaging, certification, before_after, infographic, screenshot, video, general), or by is_primary_product. Use this BEFORE generating any image-based output so you pick from the brand's real assets, not generic stock. Returns asset_id, signed url, type, detected_product_name, is_primary_product, sources. Free, read-only. Paginated via cursor.

List indexed brand documents for a brand. Each row carries the indexed signals (doc_type, summary, key_topics, classification_confidence, indexing_status) plus mime_type and size_bytes from the underlying file. Filter by doc_type (one of 19 values incl. voice_tone_doc, brand_guidelines, strategy_memo, customer_interview, pitch_deck, general_reference) or by indexing_status (pending, running, indexed, error). Use BEFORE read_brand_document to discover what context exists for a brand without paying the read cost. Free, read-only. Paginated via cursor.

List every brand in this workspace. Use this BEFORE creating a PowerSource to avoid creating duplicate brand records (pass the matching brand_id to create_powersource_*), and to discover brands the user can pivot a Heist to. Each row carries the brand_id (persistent identity), name, domain, asset_count, strategy_count, and brand status. Use this when the user asks "what brands do I have", "show me my brands", or before any image-led work where you need to know which brand owns assets. Free, read-only. Distinguish Brand (persistent, brand_id) from PowerSource (a scan, powersource_id). A brand has many PowerSources; pick the brand first, then narrow to a strategy with list_strategies.

Cards the user bookmarked from Creative Director chat — directions, concepts, executions, brand platforms, art directions, visual sets. Surfaces in /library + the chat-side tray. Saves happen through the dedicated /api/creative-director/bookmarks route (NOT through /api/library), so is_savable is false here — the library surface is read-only. Read-only, free. Filter scope with only_workspace / only_official (mutually exclusive — same toggle as the in-app library lens). Page with limit + offset.

Reusable creative agents the Heist can pick as a handoff target — picked from the UI, callable as an MCP tool from Managed Agents. Workspace = private agents in the org. Official = public_template agents in any org. Read-only, free. Filter scope with only_workspace / only_official (mutually exclusive — same toggle as the in-app library lens). Page with limit + offset.

Portable craft skills (frameworks + method + worked examples) a Creative Agent loads ON TOP of its worldview — additive and stackable, never substitutive (unlike a creative_director_playbook, which replaces the agent for a session). Pinned per character on creative_agent_versions.skill_ids. Workspace = org-authored private skills; official = the Heista-curated starter library. Read-only, free. Filter scope with only_workspace / only_official (mutually exclusive — same toggle as the in-app library lens). Page with limit + offset.

Seven-section creative-mechanism lenses the Creative Director chat picks at session start. The picked playbook substitutes Layers 3 + 4 of the system prompt — voice + foundation — for the session (the lens IS who the agent is). Workspace = private playbooks; official = the Heista-curated catalog. Read-only, free. Filter scope with only_workspace / only_official (mutually exclusive — same toggle as the in-app library lens). Page with limit + offset.

Structural references for script-led Heists. Workspace decodes (your video_sources scans joined with their video_scan_frameworks) + Heista-curated decoded ads from official_ad_heists. Read-only, free. Filter scope with only_workspace / only_official (mutually exclusive — same toggle as the in-app library lens). Page with limit + offset.

Static-ad references for image-led Heists. Workspace static scans + Heista-curated image ad heists. Read-only, free. Filter scope with only_workspace / only_official (mutually exclusive — same toggle as the in-app library lens). Page with limit + offset.

Styled outfits — a talent dressed in a full look, saved as one composite sheet (turnaround + wardrobe detail crops) with structured refs to the product images that built it. The Outfits Heist saves them on click; future image/video Heists pick one to lock model + wardrobe in a single pick. Workspace = your saved outfits. Official = Heista-curated drops across casual, streetwear, activewear, business, evening, swim & resort, loungewear, and outerwear. Read-only, free. Filter scope with only_workspace / only_official (mutually exclusive — same toggle as the in-app library lens). Page with limit + offset.

List all projects (campaign folders) for a brand. A project groups strategies, documents, client assets, and outputs under one campaign. Returns project_id (pass as project_id to list_strategies / list_brand_documents / list_brand_assets to scope those reads to this project), name, status, start_date, target_date, and per-type counts. Free, read-only.

List saved assets in the workspace. Filter by category (STRATEGY, IDEAS, COPY, VISUALS, MOTION, BRIEFS), by one or more formats inside the category (e.g. COPY + formats=["ad-script","hook"]), by tags (any/all), by brand_id, by brief_id (PowerSource), by created_by ("me" resolves to caller via OAuth), or favorites_only. Returns the unified view that backs the /assets page — BRIEFS rows come from creator_briefs with share URLs; other categories come from saved_assets. Use BEFORE asking the user what to pull into a Heist. Free, read-only, paginated.

Visual ideas you saved from prior generations. Workspace-only. Read-only, free. Filter scope with only_workspace / only_official (mutually exclusive — same toggle as the in-app library lens). Page with limit + offset.