co.heista/api

Tools

• add_brand_asset

  Upload an image to a brand by URL. The pipeline downloads it, runs the vision tagger (classifies type, detects product name, flags is_primary_product), stores it in the brand-assets bucket, and inserts a brand_assets row. Paid (vision tag credit). If vision tagging fails, the asset is still saved with type=general and can be retried via retag_brand_asset.

  shallow
• adformula_intelligence

  Browse proven ad formula blueprints — structural patterns clustered from 3-10+ winning ads that independently converged on the same beat architecture while Meta kept rewarding them with sustained spend. Takes optional filters: vertical, creative_format (e.g. TALKING_HEAD, UGC, FOUNDER_STORY), marketing_angle, algo_intent, hook_type, and limit (1-10, default 5). Each formula returns: source ad count, average active days (runtime proof), confidence score, 6-layer beat blueprint, per-beat visual direction, marketing angle, psychology mission. Free, read-only, idempotent. Use this when the user asks "what's working in [category]", "show me formulas for talking-head ads", "what scripts work in my vertical", or wants category-level pattern discovery before committing to a single ad. Pass the returned formula id to generate_adscript with source_type="formula" for synthesis. When choosing among results: prioritise (1) avg_active_days as primary proof, (2) marketing_angle alignment with the brand's buyer tension, (3) source_ad_count for cluster robustness, (4) confidence_score as tiebreaker. Do NOT use when the user names a specific ad — decode that ad with decode_ad. Do NOT use for sentence-level transcript fidelity — formulas abstract the structure, not exact copy.

  shallow
• call_creative_agent_preset

  Invoke a Creative Agent (character) preset. Every preset is a purpose-built character the workspace has authored or the Heista catalog has published — copy voice, art direction, strategy, creative direction, etc. ONE-SHOT: give the character a message, get its response back as text. Discover callable presets via list_creative_agent_presets. Workspace-authored presets are only callable inside their owning org; official templates (visibility=public_template) are callable from any authenticated org. INPUTS: agent_id (UUID from list_creative_agent_presets), message (the turn text), optional brand_id (server-loads multi-strategy brand summary for character context), optional working_context (light labels the character reads as IN SCOPE — pinned brand + strategies + documents + playbook), optional thread_id (continuity id), optional idempotency_key (5-minute retry safety). Returns the character's response as plain text plus a structured envelope with usage, model, provider, thread_id. Metered — cost depends on character model + context size, typically 2-10 credits per turn. Charged after success on real token usage.

  shallow
• call_creative_worlds

  Heista's creative direction engine — same engine the Creative Director specialist runs internally, exposed over MCP. ONE-SHOT: give a brief, get N finished creative outputs. For back-and-forth refinement, or output shapes the `medium` enum below does not cover, use chat_with_creative_worlds instead. OUTPUT SHAPE switches on the `medium` arg: • omitted → N territory cards (default exploration). Each card sits on different psychology / craft / feel / world axis coordinates so the set spans the creative space rather than orbiting one insight. Card has: name, campaign line, 5-8 sentence pitch, one-sentence strategic bet, resolved axis state names, creative-director rationale. • `tvc` → N TVC scripts (15-90s — hook, arc, resolve, sound design, end line). • `billboard` / `ooh` / `print` → N out-of-home concepts (visual concept + line + placement rationale). • `social` → N social-video concepts (hook + format type + middle beat + payoff, optimised for Reels / TikTok / Shorts). • `activation` / `experiential` → N activation concepts (space design + user journey + peak moment + takeaway artifact). • `audio` → N sonic / radio concepts (sonic scene + voice + audio arc). • `campaign` → N full campaign platforms (insight → big idea → strategy → visual world → production roadmap). The engine can also produce manifesto / copy, naming, packaging, PR stunts, content series, brand positioning, partnerships — these output shapes are NOT in the medium enum, so use chat_with_creative_worlds when the user wants one of those. USE WHEN: user says "give me ideas / options / directions / territories", "what angles work for...", "show me three / five ways to...", "write a TVC for...", "draft billboard concepts for...", "I need fresh thinking on...". DO NOT USE to refine one existing direction (use chat tool), to critique work, for OKRs / internal docs / strategy decks, or anything outside advertising creative direction. INPUTS: brief (the creative problem, free text), count (2-6 concepts), optional brand_id (from list_brands or any create_powersource_* — when provided the engine grounds output in the brand's buyer tensions, voice, and selling points), optional medium (above), optional lens_hint (apply a playbook or signature move as a creative constraint), idempotency_key (safely retryable for 5 minutes). Returns the finished creative output as narrative text PLUS a structured array of resolved axis coordinates for programmatic use. Metered — typically 3-15 credits per call depending on count and brand context size. Charged after success on actual token usage.

  shallow
• chat_with_creative_worlds

  Multi-turn conversation with Heista's creative direction engine — a real chat where the agent decides each turn what to produce based on what you ask for. Use whenever the work needs more than one round, OR when you want an output shape not covered by call_creative_worlds' `medium` enum. WHAT YOU CAN ASK FOR (any of these, turn 1 or any turn after): • Territories — "give me five directions for X", "what angles work here" • A TVC script — "write a 30-second TVC for Cowboys" • Billboard concepts — "three billboards under a quiet-authority lens" • A campaign platform — "build #2 into a full campaign with the big idea" • A manifesto or copy — "draft the manifesto in the brand voice" • Naming — "name this product, five options with rationale" • A PR stunt — "what's the newsworthy version of this" • A content series — "20 episode ideas for a brand podcast" • Packaging, sonic branding, partnerships, social systems • Refinement — "make #2 darker", "extend that into a tagline", "summarise" • Pivots — "forget the soft-drink angle, try the late-night insomnia one" SESSION: omit session_id on turn 1; the response returns a fresh session_id you pass on every subsequent turn — that is how the conversation persists. brand_id is only honoured on turn 1 of a new session (continuing sessions keep their original brand context). USE WHEN: user wants back-and-forth, OR wants an output shape outside the medium enum (manifesto, naming, press release, content series, packaging, etc.). Prefer call_creative_worlds when the user wants "three options, done" with no follow-up. WON'T DO: write OKRs / internal docs / strategy decks; behave as a general assistant. It is a creative director with creative-director taste — anti-cliché, specificity test, will push back on vague briefs. Metered — typically 2-10 credits per turn depending on tool use and context size. Charged after each turn on actual token usage.

  shallow
• check_balance

  Check the calling user's Heista API credit balance, month-to-date usage broken down by operation, lifetime spend, and the current pricing for every paid tool. Takes no inputs. Returns balance in cents, lifetime spend in cents, month-to-date call counts per tool (decode_ad, create_powersource_*, generate_adscript), per-tool unit pricing, and a top-up link the user can follow to add credits. Free, read-only, idempotent. Use this whenever the user asks about credits, balance, usage, how much they've spent, top-ups, pricing, "what does this cost", or "how many credits do I have". This is also the ONLY surface where dollar amounts are legitimate to report in conversation — everywhere else, cost should be referenced in credits, not currency. Do NOT use to add credits or change billing — only to read state. Do NOT call this on every turn — invoke once when the user explicitly asks about account state.

  shallow
• create_powersource_docs

  Build a complete creative intelligence profile from internal brand documents — creative briefs, brand guidelines, product specs, customer research, competitive analysis. Takes any mix of file_ids (from a previous upload), document_urls (public PDF/DOCX/TXT/MD links, up to 10), or documents_inline (base64-encoded files with filename), plus an optional context_url for layering live brand context (colors, fonts, current messaging) and optional idempotency_key. Returns a job_id; poll with get_powersource. Output shape is identical to create_powersource_url: identity, offer, selling points, voice, buyer profile, tensions, angles, emotional arcs, ctas, narrative. Use this when the user says "I have a brief", "here's my brand guidelines", "use this document", drops a PDF / DOCX / strategy deck, or when the truth lives in internal materials rather than the public website. The pipeline reads text only — convert PDFs to markdown before submitting via documents_inline when possible. Costs 100 credits. Do NOT use for URL-only scans — use create_powersource_url. For URL + docs combined (highest fidelity, triangulates public messaging against internal strategy), use create_powersource_full.

  shallow
• create_powersource_full

  Build the highest-fidelity creative intelligence profile by combining a brand's public website URL with their internal documents. Takes a required website URL plus at least one document — file_ids from previous upload, public document_urls (PDF/DOCX/TXT/MD, up to 10), or documents_inline (base64-encoded). Optional idempotency_key for safe retry. Returns a job_id; poll with get_powersource. Same response shape as create_powersource_url, but the synthesis cross-checks how the brand presents publicly against what the team actually believes internally, producing stronger conviction on voice, positioning, proof, and tension architecture than either input alone. Use this when the user has both a public site AND a brief / brand guidelines / strategy deck and wants the deepest possible profile — the kind of intelligence a senior strategist produces over a week. Default recommendation when both inputs are available. Costs 200 credits. Do NOT use for URL-only scans — use create_powersource_url (100 credits). Do NOT use for docs-only scans — use create_powersource_docs (100 credits).

  shallow
• create_powersource_url

  Build a complete creative intelligence profile of a brand from a single website URL. Takes a website URL (homepage, PDP, landing page) plus optional idempotency_key, force_refresh, and webhook_url. Returns a job_id immediately; poll with get_powersource every 3-5s (typically 60-90s total). The final payload contains 14 structured sections: identity, offer, selling_points, brand_story, brand_style, brand_assets, brand_voice, buyer_profile, 12 buyer tensions, marketing angles, emotional_arcs, ctas, proof_assets, and strategic narrative. Use this when the user says "analyse my brand", "load my brand", "build a strategy from my site", "what should my ads say", "decode this website", or pastes a homepage / competitor URL and wants a brand profile (not an ad decode). Also use this as the brand layer before calling generate_adscript — pass the returned powersource_id. Costs 100 credits. Re-scanning the same URL within your org returns the cached result free. Do NOT use for internal docs / PDFs / brand guidelines — use create_powersource_docs. For URL + docs combined (highest fidelity), use create_powersource_full. Do NOT use to decode a video ad — use decode_ad.

  shallow
• creative_delete_draft

  Permanently delete a Creative Library draft that has NEVER been published. Refused for any article with publication history — use creative_unpublish_article to take a live page down instead, which keeps the draft. Use this only to clear test or abandoned drafts.

  shallow
• creative_get_authoring_contract

  Read the canonical shelves, taxonomy, relationship Lego, safe content rules, and positional slots for every publishable Creative Library format. Call this before authoring.

  shallow
• creative_get_draft

  Read one Creative Library draft so it can be reviewed before explicit publication.

  shallow
• creative_get_shelf

  Read one shelf hub as an object: its public URL, what it covers, what it deliberately does NOT cover (and which shelf owns each of those instead), and every article on it with status and live URL. Use it to check placement before drafting.

  shallow
• creative_list_articles

  List Creative Library drafts and publication state. Returns editorial metadata only, not customer data.

  shallow
• creative_publish_article

  Publish only the exact reviewed draft revision. If the draft changed after review, publication fails and the new revision must be reviewed.

  shallow
• creative_save_draft

  Validate and save a complete Creative Library draft using the canonical taxonomy and format-specific content slots. An identical retry is a no-op. It cannot replace published content or publish a page.

  shallow
• creative_unpublish_article

  Take a live Creative Library article down. It stops being public and leaves the sitemap immediately. The draft is preserved and can be re-published after review. Use this to reverse a publication.

  shallow
• creative_update_slug

  Change an article slug and 301 the old URL at the new one. Never leaves two live URLs. Refuses a new slug ending in a year, a slug already in use, and any article whose draft is ahead of what is published (renaming republishes). Use this instead of saving a second article under a new slug.

  shallow
• decode_ad

  Decode a specific video ad URL into its full structural formula — beat-by-beat breakdown, hook classification, behavioral psychology stack, creative format, runtime performance signals (active days on Meta Ad Library when available), and per-cut visual data. Takes one video URL plus an optional idempotency_key. Returns a job_id immediately; poll with get_decode every 15s until status is "completed" (typically 45-60s end-to-end). Use this when the user pastes an ad URL, names a specific competitor ad, asks "decode this" or "break down this ad" or "what makes this ad work", or wants sentence-level fidelity to one specific winner before writing a script with generate_adscript. Supports Facebook Ad Library, TikTok, Instagram Reels, YouTube Shorts, and direct .mp4 URLs. Costs 15 credits for videos ≤60s, 20 credits for 61-120s. Do NOT use to browse the corpus or find ads by category — use decoder_intelligence or adformula_intelligence (both free) for discovery. Do NOT use for image ads or static creative.

  shallow
• decoder_intelligence

  Browse individual decoded ads from Heista's corpus of real winning Meta/TikTok creative. Takes optional filters: vertical, creative_format, marketing_angle, hook_type, algo_intent, brand (partial name match), and limit (1-10, default 5). Each result returns beat timeline, classification, psychology, runtime performance signals (active days on Meta when available), and a decode id you can pass into generate_adscript with source_type="decode" to write a fresh script on that exact structure. Free, read-only, idempotent — no credits consumed. Use this when the user wants a specific ad as a script template (not an averaged formula), asks "show me winning ads in [vertical]", "what are [brand]'s top ads", or wants to see examples before committing to a generation. Source discovery surface — the response is the spine; for the full bundle with transcripts and director's read, call get_decode by id afterwards. Do NOT use to decode a NEW ad from a URL — use decode_ad (paid). Do NOT use for category-level patterns abstracted across multiple ads — use adformula_intelligence. Do NOT use to write the script itself — use generate_adscript or write directly from the bundle.

  shallow
• delete_brand_asset

  Delete one brand asset by asset_id. Removes the brand_assets row and (when the asset was uploaded rather than scanned) the storage object. Destructive — confirm with the user before calling. Use list_brand_assets first to find the asset_id.

  shallow
• delete_saved_asset

  Delete one saved asset by id. Destructive — confirm with the user before calling. OAuth callers can only delete saves they created themselves (Linear model — see /assets UI for org-admin override). API-key callers are treated as org-trusted and can delete on behalf of any creator in the workspace. Cleans up the storage object for private VISUALS/MOTION saves.

  shallow
• dispatch_desk_researcher

  Dispatch to the DESK RESEARCHER — source-grounded synthesis on a topic landscape. Use for: "what is known about X / give me the landscape of Y / fact-check Z / synthesize the published evidence on W". Multi-source FACT/INFERENCE extraction with citation discipline. Vertical and geography agnostic. Returns: BRIEF restatement + NOT IN SCOPE + findings with FACT/INFERENCE/SPECULATION labels + [n] citations + Sources block. NOT for: trajectory questions (use dispatch_trend_researcher) / entity teardowns (use dispatch_market_analyst) / numerical effect sizes (use dispatch_quantitative_researcher) / community quotes (use dispatch_qualitative_researcher).

  shallow
• dispatch_desk_researcher_async

  Dispatch to the DESK RESEARCHER — source-grounded synthesis on a topic landscape. Use for: "what is known about X / give me the landscape of Y / fact-check Z / synthesize the published evidence on W". Multi-source FACT/INFERENCE extraction with citation discipline. Vertical and geography agnostic. Returns: BRIEF restatement + NOT IN SCOPE + findings with FACT/INFERENCE/SPECULATION labels + [n] citations + Sources block. NOT for: trajectory questions (use dispatch_trend_researcher) / entity teardowns (use dispatch_market_analyst) / numerical effect sizes (use dispatch_quantitative_researcher) / community quotes (use dispatch_qualitative_researcher). ASYNC version: returns { job_id } immediately, the specialist runs durably on a Vercel Workflow (no 300s timeout). Use this version when the specialist is expected to take >90s. Call get_dispatch_result(job_id) periodically (respect wait_ms_hint in the response) until status === 'completed' or 'failed'. Idempotent: same brief + same org reuses the same job_id, so retries don't fan out duplicate runs.

  shallow
• dispatch_head_of_research

  Run a full research workflow via the Head of Research agent. The Head decomposes your brief into specialist sub-questions, dispatches the right combination of 6 specialists (desk, trend, market, quant, qual, social) in parallel via async dispatch, polls them to completion, judges output quality, and returns a structured synthesis. Use for: any source-grounded research request — fact-checking, vendor teardowns, trend assessment, quantitative effect-size analysis, qualitative theme extraction, cross-platform discourse mapping, or any combination. Wall time: 2-5 min typical. Returns: { synthesis, head_session_id, status, event_count, tool_uses, elapsed_ms }. NOT for: non-research requests (writing, coding, casual chat) — respond directly without calling this. Cost: $0.20-1.50 per call depending on brief complexity (specialist token spend + Anthropic session-runtime at $0.08/hr).

  shallow
• dispatch_market_analyst

  Dispatch to the MARKET ANALYST — entity-deep teardown of a named brand or vendor. Use for: "what is brand X / how does company Y work / decode competitor Z / teardown vendor W". Multi-axis extraction grounded in multi-class sourcing, plus defensible MOAT and credible GAP theses. Vertical and geography agnostic. Returns: 8-axis extraction (positioning / offer / audience / voice / pricing / distribution / proof / trajectory) + MOAT thesis + GAP thesis + Sources. NOT for: topic landscapes without a named entity (use dispatch_desk_researcher) / trajectory questions about a category (use dispatch_trend_researcher).

  shallow
• dispatch_market_analyst_async

  Dispatch to the MARKET ANALYST — entity-deep teardown of a named brand or vendor. Use for: "what is brand X / how does company Y work / decode competitor Z / teardown vendor W". Multi-axis extraction grounded in multi-class sourcing, plus defensible MOAT and credible GAP theses. Vertical and geography agnostic. Returns: 8-axis extraction (positioning / offer / audience / voice / pricing / distribution / proof / trajectory) + MOAT thesis + GAP thesis + Sources. NOT for: topic landscapes without a named entity (use dispatch_desk_researcher) / trajectory questions about a category (use dispatch_trend_researcher). ASYNC version: returns { job_id } immediately, the specialist runs durably on a Vercel Workflow (no 300s timeout). Use this version when the specialist is expected to take >90s. Call get_dispatch_result(job_id) periodically (respect wait_ms_hint in the response) until status === 'completed' or 'failed'. Idempotent: same brief + same org reuses the same job_id, so retries don't fan out duplicate runs.

  shallow
• dispatch_qualitative_researcher

  Dispatch to the QUALITATIVE RESEARCHER — thematic synthesis from unstructured text (interviews, reviews, forum threads, customer language). Use for: "what are the 2-3 recurring themes in how D2C founders talk about X / what language is being used around Y / what are the patterns in customer reviews of Z". Every theme carries evidence count, triangulation status, ≥1 verbatim quote, outlier-check note. SOLVES the Reddit/X/Substack named-operator voice retrieval gap that legacy search tools could not fill. Returns: Corpus + Sampling + Coding methodology + 4-axis Themes table + Theme synthesis + Outlier voices + Saturation assessment + Sources. NOT for: quantitative effect sizes (use dispatch_quantitative_researcher) / multi-platform discourse mapping (use dispatch_social_listening_researcher).

  shallow
• dispatch_qualitative_researcher_async

  Dispatch to the QUALITATIVE RESEARCHER — thematic synthesis from unstructured text (interviews, reviews, forum threads, customer language). Use for: "what are the 2-3 recurring themes in how D2C founders talk about X / what language is being used around Y / what are the patterns in customer reviews of Z". Every theme carries evidence count, triangulation status, ≥1 verbatim quote, outlier-check note. SOLVES the Reddit/X/Substack named-operator voice retrieval gap that legacy search tools could not fill. Returns: Corpus + Sampling + Coding methodology + 4-axis Themes table + Theme synthesis + Outlier voices + Saturation assessment + Sources. NOT for: quantitative effect sizes (use dispatch_quantitative_researcher) / multi-platform discourse mapping (use dispatch_social_listening_researcher). ASYNC version: returns { job_id } immediately, the specialist runs durably on a Vercel Workflow (no 300s timeout). Use this version when the specialist is expected to take >90s. Call get_dispatch_result(job_id) periodically (respect wait_ms_hint in the response) until status === 'completed' or 'failed'. Idempotent: same brief + same org reuses the same job_id, so retries don't fan out duplicate runs.

  shallow
• dispatch_quantitative_researcher

  Dispatch to the QUANTITATIVE RESEARCHER — numerical analysis with full methodology context. Use for: briefs that turn on numbers done rigorously — "what is the documented effect size of X / what does the data say about Y / quantify the impact of Z". Every load-bearing number carries sample frame, sample size, measurement instrument, time window. Often answers with insufficient-evidence when underlying data is thin (negative findings are deliverable). Returns: 4-axis Quantitative summary (Value / Methodology rigor / Effect size / Robustness) + Numerical findings table + Methodology gaps + Sources. NOT for: topic landscapes (use dispatch_desk_researcher) / community language patterns (use dispatch_qualitative_researcher).

  shallow
• dispatch_quantitative_researcher_async

  Dispatch to the QUANTITATIVE RESEARCHER — numerical analysis with full methodology context. Use for: briefs that turn on numbers done rigorously — "what is the documented effect size of X / what does the data say about Y / quantify the impact of Z". Every load-bearing number carries sample frame, sample size, measurement instrument, time window. Often answers with insufficient-evidence when underlying data is thin (negative findings are deliverable). Returns: 4-axis Quantitative summary (Value / Methodology rigor / Effect size / Robustness) + Numerical findings table + Methodology gaps + Sources. NOT for: topic landscapes (use dispatch_desk_researcher) / community language patterns (use dispatch_qualitative_researcher). ASYNC version: returns { job_id } immediately, the specialist runs durably on a Vercel Workflow (no 300s timeout). Use this version when the specialist is expected to take >90s. Call get_dispatch_result(job_id) periodically (respect wait_ms_hint in the response) until status === 'completed' or 'failed'. Idempotent: same brief + same org reuses the same job_id, so retries don't fan out duplicate runs.

  shallow
• dispatch_social_listening_researcher

  Dispatch to the SOCIAL LISTENING RESEARCHER — multi-platform community-signal interpretation. Use for: "what are practitioners saying about X across platforms / what jargon is emerging in field Y / what is the cross-platform discourse around brand/topic Z". Treats T3 community sources as primary data, distinguishes cross-platform patterns from single-platform noise. ≥3 platforms sampled per brief. Returns: Signal map (Signal / Platforms / Volume / Sentiment + recency) + Per-platform evidence trail + Cross-platform vs single-platform classification + Confidence flag + Sources. NOT for: single-source thematic work (use dispatch_qualitative_researcher) / numerical sentiment effect sizes (use dispatch_quantitative_researcher).

  shallow
• dispatch_social_listening_researcher_async

  Dispatch to the SOCIAL LISTENING RESEARCHER — multi-platform community-signal interpretation. Use for: "what are practitioners saying about X across platforms / what jargon is emerging in field Y / what is the cross-platform discourse around brand/topic Z". Treats T3 community sources as primary data, distinguishes cross-platform patterns from single-platform noise. ≥3 platforms sampled per brief. Returns: Signal map (Signal / Platforms / Volume / Sentiment + recency) + Per-platform evidence trail + Cross-platform vs single-platform classification + Confidence flag + Sources. NOT for: single-source thematic work (use dispatch_qualitative_researcher) / numerical sentiment effect sizes (use dispatch_quantitative_researcher). ASYNC version: returns { job_id } immediately, the specialist runs durably on a Vercel Workflow (no 300s timeout). Use this version when the specialist is expected to take >90s. Call get_dispatch_result(job_id) periodically (respect wait_ms_hint in the response) until status === 'completed' or 'failed'. Idempotent: same brief + same org reuses the same job_id, so retries don't fan out duplicate runs.

  shallow
• dispatch_trend_researcher

  Dispatch to the TREND RESEARCHER — recency-dominant trajectory investigation. Use for: "is X a real trend / what is happening with X right now / where is X headed / what is driving X". Distinguishes trend from spike, signal from noise, real shift from echo chamber. Commits to falsifying conditions before searching. Returns: 4-axis Trend assessment (Reality / Magnitude / Direction / Horizon) + Current state + Baseline + trajectory + Drivers + Counter-signals + Sources. NOT for: static landscape questions (use dispatch_desk_researcher) / entity teardowns (use dispatch_market_analyst) / numerical analysis (use dispatch_quantitative_researcher).

  shallow
• dispatch_trend_researcher_async

  Dispatch to the TREND RESEARCHER — recency-dominant trajectory investigation. Use for: "is X a real trend / what is happening with X right now / where is X headed / what is driving X". Distinguishes trend from spike, signal from noise, real shift from echo chamber. Commits to falsifying conditions before searching. Returns: 4-axis Trend assessment (Reality / Magnitude / Direction / Horizon) + Current state + Baseline + trajectory + Drivers + Counter-signals + Sources. NOT for: static landscape questions (use dispatch_desk_researcher) / entity teardowns (use dispatch_market_analyst) / numerical analysis (use dispatch_quantitative_researcher). ASYNC version: returns { job_id } immediately, the specialist runs durably on a Vercel Workflow (no 300s timeout). Use this version when the specialist is expected to take >90s. Call get_dispatch_result(job_id) periodically (respect wait_ms_hint in the response) until status === 'completed' or 'failed'. Idempotent: same brief + same org reuses the same job_id, so retries don't fan out duplicate runs.

  shallow
• favorite_saved_asset

  Toggle the favorite flag on a saved asset. Pass is_favorite=true to favorite, false to unfavorite. favorited_at is set/cleared in lockstep so the Favorites tab sorts correctly. Not destructive.

  shallow
• fetch_url

  Drill into a specific URL after search surfaces it. Returns the extracted text content plus metadata. Internal routing: PDFs hit Anthropic Files API for OCR + structured extraction; HTML pages are fetched + text-extracted via readability-style stripping. Use for: verifying a verbatim quote from a Reddit thread, reading a primary source in full (earnings transcript, research paper), drilling into a vendor product page after search surfaced the URL. NOT for: discovering new URLs — use search/search_community/search_research first. This tool takes a known URL only. Optional max_chars 100-50000, default 8000. SSRF-protected: private IPs + localhost blocked.

  shallow
• fleet_analytics_overview

  Aggregate marketing analytics for the last 7/28/90 days: pageviews, visitors, sessions, AI-search-referred sessions, the view→engaged→CTA→signup→trial funnel, and top pages. Aggregates only — never person-level data. FUNNEL EVENTS, so you know what each step counts: views = $pageview; engaged = pseo_session_summary with properties.engaged (scroll ≥25% or dwell); CTA = pseo_session_summary with properties.cta_clicks_count > 0, where a CTA is a click on a link to /auth/signup, /auth/login, /book-demo, /pricing or /workspace, or any element marked data-cta; signup = signup_completed; trial = trial.started. CTA auto-detection and Creative Library session tracking both began 2026-08-24 — a CTA step that rises from ~0 across that date is instrumentation landing, not a conversion change, and library figures before it were never measured. Any step that exceeds its 25s deadline reports TIMED OUT and is NOT a zero. Returns an error result if product analytics is not configured. Read-only.

  shallow
• fleet_analytics_top_pages

  Top marketing pages by views for the last 7/28/90 days, optionally filtered to a path prefix (e.g. "/decode", "/intelligence", "/brands"). Includes engagement signals where captured. Aggregates only, hard cap 50 rows. Read-only.

  shallow
• fleet_analytics_trend

  Daily pageview series for the last 7/28/90 days, split by traffic source category (ai_search / organic / social / direct / referral). Use to measure launch weeks and content momentum. Aggregates only. Read-only.

  shallow
• fleet_crawler_hits

  Server-logged crawler fetches: which AI engines (GPTBot, ClaudeBot, PerplexityBot, OAI-SearchBot, …) and search crawlers (Googlebot, Bingbot) fetched which heista.co pages, and when. This signal is invisible to page analytics — crawlers never run the tracking script. Group by bot, page, or date; filter by bot or path. Logging began 2026-07-23 (no earlier history exists). 180-day retention. Read-only.

  shallow
• fleet_create_issue

  File an issue on the Heista HEI board: title, markdown description, optional labels (Bug, Feature, Improvement, Security, SEO, Tech Debt, Upstream, In-App Support, In-App Feedback) and priority (0 none - 4 low, default 3). Unknown label names are dropped with a warning rather than failing the write. Locked to team HEI. Use it to record a real defect or a piece of work, not to take notes.

  shallow
• fleet_get_brand_report

  Read one live brand report in full by slug, including the creative intelligence payload used on the public brand page — proof points for outreach and positioning. Read-only.

  shallow
• fleet_get_decoded_ad

  Read one published decode in full by id or slug, including its public structural payload (beats, classification, patterns — the same data rendered on the public decode page). Use for proof points, content briefs, and pattern citations. Not for customer workspace decodes — only the published corpus. Read-only.

  shallow
• fleet_get_issue

  Read one Heista Linear issue in full by identifier (e.g. "HEI-14") or UUID: title, state, priority, assignee, labels, full description, and recent comments (including the automated scope/fix notes agents leave). Locked to team HEI. Read-only.

  shallow
• fleet_gsc_inspect_url

  Google URL Inspection for one heista.co URL: index verdict, coverage state ("Submitted and indexed" / "Crawled - currently not indexed" / "URL is unknown to Google"), last crawl time, robots state, and canonical resolution. THE tool for diagnosing why a page has no impressions. Quota ~2,000 inspections/day — batch thoughtfully. Read-only (requesting indexing is not possible via API).

  shallow
• fleet_gsc_query

  LIVE Google Search Analytics query — group by any dimensions (date, page, query, country, device, searchAppearance; up to 3) with page/query filters over up to 16 months of history. Richer than the snapshot tools: use this for ad-hoc analysis. NOTE: including the "query" dimension omits anonymized rare queries — use ["date"] or ["page"] for complete totals on low-traffic sites. Hard cap 100 rows. Read-only.

  shallow
• fleet_gsc_sitemaps

  Sitemaps registered on the Search Console property with submitted vs indexed counts, last-download time, warnings and errors. The indexing-progress scoreboard — as of Jul 2026 the main sitemap had 2,432 submitted / 0 indexed. Track this as SEO fixes land. No parameters. Read-only.

  shallow
• fleet_gsc_summary

  Google Search performance totals from first-party Search Console data (synced 6-hourly): clicks, impressions, CTR, impression-weighted average position, distinct queries and pages. Optional page-path filter. Data lags real traffic by ~2-3 days; max window 28 days. Read-only.

  shallow
• fleet_gsc_top_pages

  Top pages by Google search clicks or impressions from first-party Search Console data, optionally filtered to queries containing a term. Use to find which pSEO pages earn search demand. Hard cap 50 rows, max window 28 days. Read-only.

  shallow
• fleet_gsc_top_queries

  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.

  shallow
• fleet_intel_stats

  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.

  shallow
• fleet_list_brand_reports

  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.

  shallow
• fleet_list_intelligence_articles

  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.

  shallow
• fleet_list_issues

  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.

  shallow
• fleet_product_funnel_counts

  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.

  shallow
• fleet_product_funnel_summary

  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.

  shallow
• fleet_product_signups_recent

  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.

  shallow
• fleet_product_user_summary

  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.

  shallow
• fleet_search_decoded_ads

  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.

  shallow
• fleet_seo_recovery

  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.

  shallow
• fleet_site_audit_summary

  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.

  shallow
• fleet_site_links

  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.

  shallow
• fleet_site_pages

  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.

  shallow
• generate_adscript

  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.

  shallow
• get_ad_formula_preset

  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.

  shallow
• get_brand

  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.

  shallow
• get_cd_card_bookmark_preset

  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.

  shallow
• get_creative_agent_preset

  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.

  shallow
• get_creative_agent_skill_preset

  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.

  shallow
• get_creative_director_playbook_preset

  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.

  shallow
• get_decode

  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.

  shallow
• get_decoded_ad_preset

  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.

  shallow
• get_dispatch_result

  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.

  shallow
• get_fleet_cost

  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.

  shallow
• get_hook_intelligence

  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.

  shallow
• get_image_ad_scan_preset

  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.

  shallow
• get_outfit_preset

  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.

  shallow
• get_powersource

  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.

  shallow
• get_saved_asset

  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.

  shallow
• get_saved_assets_batch

  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.

  shallow
• get_saved_visual_idea_preset

  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.

  shallow
• get_strategy

  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.

  shallow
• get_talent_model_preset

  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.

  shallow
• get_visual_preset_preset

  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.

  shallow
• get_visual_style_preset

  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.

  shallow
• list_ad_formula_presets

  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.

  shallow
• list_brand_assets

  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.

  shallow
• list_brand_documents

  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.

  shallow
• list_brands

  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.

  shallow
• list_cd_card_bookmark_presets

  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.

  shallow
• list_creative_agent_presets

  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.

  shallow
• list_creative_agent_skill_presets

  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.

  shallow
• list_creative_director_playbook_presets

  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.

  shallow
• list_decoded_ad_presets

  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.

  shallow
• list_image_ad_scan_presets

  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.

  shallow
• list_outfit_presets

  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.

  shallow
• list_projects

  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.

  shallow
• list_saved_assets

  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.

  shallow
• list_saved_visual_idea_presets

  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.

  shallow
• list_skills

  List skills available in the Heista skill library. Returns name, description, domain (shared / image / video / research / strategy / copy / creative / generation), type (foundation / registers / models / methodologies), version, and source_folder (managed-agents / chat-agent). Returns frontmatter only — no body content (use load_skill for that). Filter by domain, type, or source_folder. Use BEFORE load_skill to discover what craft knowledge is available without paying the body-read cost. Free, read-only.

  shallow
• list_strategies

  List all PowerSource strategies (scans) for a brand. A brand has many strategies — one per scanned URL. Product-page strategies carry product_name and is_product_page=true; use these to label them in conversation or to pick the right one for a product-focused generation. Returns powersource_id (use as the brief/PowerSource id everywhere else), product_name, scanned_at, source_url, is_pinned. Free, read-only. Paginated via cursor.

  shallow
• list_strategy_audiences

  List audience archetypes for a strategy (PowerSource). Returns the Buyer Decoder archetype (source="buyer_profile", one entry max) plus up to 3 offering primary_audience segments (source="primary_audience"). Use this to pick which audience to target before generating copy / scripts / hooks — the UI picker reads the same projection. Distinct from list_strategies (which lists scans for a brand): this lists audiences INSIDE one strategy.

  shallow
• list_strategy_tones

  List tone profiles for a strategy. Today returns at most one entry — the tone_of_voice synthesized by the Tone of Voice Synthesis agent (POWER-mode bundles only). The shape is list-stable so future multi-tone bundles plug in without changing the contract. Use this to align generation with the brand-tied voice DNA before writing copy, hooks, or scripts.

  shallow
• list_talent_model_presets

  Saved casting talent — a person you can re-use across Heists. The Models Heist saves them on click; future Heists can pick one as a brand-aware talent reference. Workspace = your saved castings. Official = Heista-curated drops across fashion, lifestyle, everyday, character, and creator buckets. Read-only, free. Filter scope with only_workspace / only_official (mutually exclusive — same toggle as the in-app library lens). Page with limit + offset.

  shallow
• list_visual_preset_presets

  Visual presets (style reference sets) backed by visual_heists. Dual scope since 2026-07-14: workspace rows saved from the Visual Preset builder + the Heista-curated official 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.

  shallow
• list_visual_style_presets

  Saved style configs picked into image-led Heists. Workspace = org-owned styles. Official = canonical Heista catalog (org_id IS NULL, is_canonical=true). Read-only, free. Filter scope with only_workspace / only_official (mutually exclusive — same toggle as the in-app library lens). Page with limit + offset.

  shallow
• load_skill

  Load the full SKILL.md body for one skill by canonical dot-notation name (e.g. "research.foundation", "research.methodologies.desk-synthesis", "shared.registers.cinema-mode"). Returns frontmatter + body + content_hash. Verifies content_hash against the registry and surfaces drift if the registry is out of sync with disk. Use AFTER list_skills to pick the right skill. For register-type skills with references/ folders, follow with load_skill_reference to pull specific references. Free, read-only.

  shallow
• load_skill_reference

  Load one reference file from a register-type skill's references/ folder (e.g. "m1-narrative.md" from "shared.registers.cinema-mode"). Only register-type skills have references/ — foundations and methodologies are inline content only. Find valid reference filenames in the parent SKILL.md's router table. Path-traversal protected. Free, read-only.

  shallow
• perplexity_search

  Web-grounded search via Perplexity Sonar Pro. Returns synthesized answer text plus a structured sources[] array (url + title) the caller can evaluate per the research.foundation four-tier source ladder. Optional recency_filter (hour/day/week/month/year) for fast-decay topics. Optional search_domain_filter (up to 10 domains) for triangulating against known-authoritative sources. Use this whenever a specialist needs current, web-grounded information — landscape scans, trend research, evidence queries, counter-evidence checks, named-entity lookups. Pair with the research.foundation skill (always-on craft baseline) and the research.methodologies.desk-synthesis skill (6-phase workflow) for production-grade output. The agent decomposes the brief into sub-questions BEFORE calling this — one focused query per call, not a multi-question batch. Cost is real (~$0.005-0.015 per query); the agent should budget calls per research.foundation §6 (fact-check 1-3, single comparison 3-8, landscape scan 8-20).

  shallow
• read_brand_document

  Read one indexed brand document. Returns the indexed metadata (doc_type, summary, key_topics, entities, key_quotes) plus the document body as plain text in content.text — every mime (PDF, DOCX, PPTX, XLSX, markdown, CSV, plain text). No file ids, no attaching anything on a later turn: the text is in this response. When content is null the body could not be extracted — error_code says why, and you should tell the user rather than infer contents from the title. Use AFTER list_brand_documents to pick the right document. Free, read-only.

  shallow
• reclassify_brand_assets

  Batch re-run the vision tagger against every asset in a brand that hasn't been reviewed yet (vision_classified=false). Recovers rows the scan-time tagger dropped because of CDN blocks (Shopify hotlink, Cloudflare bot gates) or transient failures. Skips videos and rows already marked not_asset. Processes up to 24 assets per call — if more remain, the response returns { remaining > 0 } and the caller can invoke again. Paid (batched vision tag credit, typically < $0.01 per invocation).

  shallow
• retag_brand_asset

  Re-run the vision tagger on one brand asset. Reads the stored object when present (uploaded assets) or the original URL (scan-sourced assets), then updates type, detected_product_name, is_primary_product, description, and the other vision fields. Useful when the original tagger run missed or misclassified an image. Paid (vision tag credit).

  shallow
• save_asset

  Persist a new saved asset to the workspace. category MUST be one of STRATEGY, IDEAS, COPY, VISUALS, MOTION (BRIEFS lives in creator_briefs and is not saveable through this tool). format MUST match the per-category enum (see input description). title is required. body_text + metadata are recommended. Source attribution (heist_slug, session_id, pattern) lets the user trace the save back to its origin in the /assets timeline. Brand and brief_id link the save to a PowerSource for downstream filtering. Returns the inserted asset row.

  shallow
• search

  General-purpose web grounding via parallel.ai (Vercel AI Gateway). Returns synthesized text excerpts plus structured sources[] with direct URLs. Use for: topic landscapes, entity-deep teardowns, recency-sharp queries, named-vendor lookups, general fact retrieval. NOT for: Reddit/X/community discourse → use search_community. NOT for: numerical effect sizes or methodology-heavy fact-check → use search_research. The agent decomposes the brief into sub-questions BEFORE calling — one focused query per call. Optional after_date (ISO YYYY-MM-DD) for fast-decay topics. Optional max_results 1-20, default 10.

  shallow
• search_community

  Community-discourse search via parallel.ai with optional platform filtering. Returns synthesized text excerpts plus direct URLs to real Reddit threads, X posts from named operators, Substack essays, LinkedIn posts, Facebook posts. Use for: "what are practitioners saying about X", recurring themes in founder voice, multi-platform discourse mapping, verbatim quotes from named individuals. Per Phase 3.5 empirical A/B (Docs/solutions/architecture-decisions/search-backend-architecture-jun04.md): this tool SOLVES the Reddit/X retrieval gap that perplexity_search fundamentally couldn't fill. Optional platforms[] to restrict (e.g. ["reddit","x","substack"]). Per social-listening-synthesis §3 sample ≥3 platforms per brief.

  shallow
• search_research

  Structured fact-check + numerical research via Perplexity Sonar Reasoning Pro (Gateway-routed). Returns synthesized answer text plus structured sources[] with direct URLs to primary sources. Use for: specific numerical claims with methodology context, fact-check against primary sources, effect sizes + confidence intervals, earnings transcripts / SEC filings / research papers. Per Phase 3.5 empirical A/B: 2-3× cheaper than sonar-pro with comparable or better quality on structured research. Real Meta IR press releases + earnings transcripts on Desk. 17 cites on Quant. NOT for: Reddit/X/community → use search_community. NOT for: broad topic landscapes → use search.

  shallow
• search_skills

  Find skills across EVERY Heista skill library at once — image craft, fleet foundations and model briefings, Heista DNA creative playbooks, creative agents, and agent skills. Describe the SITUATION you need a skill for in your own words (a brief, a job, a problem) rather than a keyword — results are ranked by how well each skill fits that situation. Optionally restrict to specific libraries. Use this BEFORE load_skill (for disk-backed image/fleet skills) or the get_*_preset tools (for database-backed playbooks, agents and agent skills). Free, read-only.

  shallow

Embed this server’s score

Tool count and median score across every tool in this server’s corpus — honest in a way a single cherry-picked tool’s badge wouldn’t be.

[![Vouch score](https://vouch.tools/api/servers/f2236c76-e733-46e2-ac00-791b61385cb6/badge.svg)](https://vouch.tools/servers/f2236c76-e733-46e2-ac00-791b61385cb6)