Heista

Official76 tools

by Heista-co

Decode video ads, load brand intelligence, generate ad scripts.

co.heista/api MCP Server

The co.heista/api MCP server provides capabilities to decode video ad content, load brand intelligence, and generate ad scripts from within any MCP-compatible client. It exposes an MCP endpoint via Streamable HTTP and uses OAuth 2.1 or an API key for authentication.

🛠️ Key Features

Decode video ads
Load brand intelligence
Generate ad scripts
Toolset: 76 tools (per provided data)
Readme excerpt references decode_ad for decoding a video ad URL

🚀 Use Cases

Converting a video ad URL into a structural formula
Producing ad scripts based on brand intelligence

⚡ Developer Benefits

MCP-compatible access from clients such as Claude, ChatGPT, Cursor, and VS Code (as stated in the readme excerpt)
Streamable HTTP transport for the MCP protocol endpoint

⚠️ Limitations

Only a decode_ad tool entry is explicitly shown in the provided excerpt; additional tools beyond toolCount are not described here.

Captured live from the server via tools/list.

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.

Parameters2

url	string	required	Video URL to decode. Supports: Facebook Ad Library, TikTok, Instagram Reels, YouTube Shorts, or direct .mp4 URL.
idempotency_key	string	optional	Optional unique key to make this call safely retryable. If the same key + org repeats, the original result is returned without re-charging.

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Video URL to decode. Supports: Facebook Ad Library, TikTok, Instagram Reels, YouTube Shorts, or direct .mp4 URL."
    },
    "idempotency_key": {
      "description": "Optional unique key to make this call safely retryable. If the same key + org repeats, the original result is returned without re-charging.",
      "type": "string",
      "maxLength": 128
    }
  },
  "required": [
    "url"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

job_id

string

required

Job ID returned by decode_ad. Call this tool to poll status or retrieve completed results.

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Job ID returned by decode_ad. Call this tool to poll status or retrieve completed results."
    }
  },
  "required": [
    "job_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

url	string	required	Website URL to analyze. Supports any public website (e.g., gymshark.com, notion.so). Bare domains auto-resolve to https.
brand_id	string	optional	Optional Brand to attach this scan to. Get from list_brands. When omitted, the pipeline auto-resolves a brand by the scanned domain (creating one if needed) — the addendum D6 default. Pass this when you have an existing brand_id (e.g. from a prior list_brands call) and want to guarantee linkage rather than relying on domain match.
idempotency_key	string	optional	Optional unique key to make this call safely retryable. If the same key + org repeats, the original result is returned without re-charging.
force_refresh	boolean	optional	Force re-extraction of brand data even if cached. Use when a brand has rebranded or updated their website.
webhook_url	string	optional	HTTPS URL to receive a POST notification when the scan completes or fails. Eliminates need for polling.

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Website URL to analyze. Supports any public website (e.g., gymshark.com, notion.so). Bare domains auto-resolve to https."
    },
    "brand_id": {
      "description": "Optional Brand to attach this scan to. Get from list_brands. When omitted, the pipeline auto-resolves a brand by the scanned domain (creating one if needed) — the addendum D6 default. Pass this when you have an existing brand_id (e.g. from a prior list_brands call) and want to guarantee linkage rather than relying on domain match.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "idempotency_key": {
      "description": "Optional unique key to make this call safely retryable. If the same key + org repeats, the original result is returned without re-charging.",
      "type": "string",
      "maxLength": 128
    },
    "force_refresh": {
      "description": "Force re-extraction of brand data even if cached. Use when a brand has rebranded or updated their website.",
      "type": "boolean"
    },
    "webhook_url": {
      "description": "HTTPS URL to receive a POST notification when the scan completes or fails. Eliminates need for polling.",
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "url"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

job_id	string	required	Job ID returned by any create_powersource_* call. Use this to poll status or retrieve completed results.
include_raw	boolean	optional	Internal-only. When true and the caller holds mcp:internal_admin, returns the un-merged brief bundle alongside the merged response. Silently ignored for non-admin callers — no error is raised.

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Job ID returned by any create_powersource_* call. Use this to poll status or retrieve completed results."
    },
    "include_raw": {
      "description": "Internal-only. When true and the caller holds mcp:internal_admin, returns the un-merged brief bundle alongside the merged response. Silently ignored for non-admin callers — no error is raised.",
      "type": "boolean"
    }
  },
  "required": [
    "job_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters6

brand_id	string	optional	Optional Brand to attach this scan to. Get from list_brands. When omitted, the pipeline auto-resolves a brand by the context_url domain (if provided) or creates a standalone scan with no brand link.
file_ids	array	optional	Array of file IDs from a previous upload. Up to 10 files.
document_urls	array	optional	Array of public URLs pointing to documents (PDF, DOCX, TXT, MD). Up to 10 URLs.
documents_inline	array	optional	Inline documents as base64. Use when the user has uploaded a file into chat and no public URL exists. IMPORTANT: The synthesis pipeline reads TEXT ONLY — it ignores images, diagrams, and visual layout. For any PDF or DOCX the user drops into chat: (1) read the file using your file-reading tools, (2) extract the text content preserving section headers and structure, (3) save as a clean .md or .txt file, (4) base64-encode the text file and submit here. Do NOT base64-encode the original PDF — extract text first. This keeps payloads small (a 50-page brief extracts to ~50KB of text vs 5MB of PDF) and produces better results because the pipeline gets clean structured text instead of OCR-extracted noise from embedded images. Max 5MB per file, 10 files total across all input types.
context_url	string	optional	Optional website URL to layer live brand context on top of the documents (colors, fonts, current messaging).
idempotency_key	string	optional	Optional unique key to make this call safely retryable. If the same key + org repeats, the original result is returned without re-charging.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "description": "Optional Brand to attach this scan to. Get from list_brands. When omitted, the pipeline auto-resolves a brand by the context_url domain (if provided) or creates a standalone scan with no brand link.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "file_ids": {
      "description": "Array of file IDs from a previous upload. Up to 10 files.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "document_urls": {
      "description": "Array of public URLs pointing to documents (PDF, DOCX, TXT, MD). Up to 10 URLs.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      }
    },
    "documents_inline": {
      "description": "Inline documents as base64. Use when the user has uploaded a file into chat and no public URL exists. IMPORTANT: The synthesis pipeline reads TEXT ONLY — it ignores images, diagrams, and visual layout. For any PDF or DOCX the user drops into chat: (1) read the file using your file-reading tools, (2) extract the text content preserving section headers and structure, (3) save as a clean .md or .txt file, (4) base64-encode the text file and submit here. Do NOT base64-encode the original PDF — extract text first. This keeps payloads small (a 50-page brief extracts to ~50KB of text vs 5MB of PDF) and produces better results because the pipeline gets clean structured text instead of OCR-extracted noise from embedded images. Max 5MB per file, 10 files total across all input types.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "Filename with extension (e.g., \"brand-brief.md\"). Use .md or .txt — the pipeline reads text only."
          },
          "content_base64": {
            "type": "string",
            "description": "Base64-encoded file content. Max 5MB per file."
          }
        },
        "required": [
          "filename",
          "content_base64"
        ]
      }
    },
    "context_url": {
      "description": "Optional website URL to layer live brand context on top of the documents (colors, fonts, current messaging).",
      "type": "string"
    },
    "idempotency_key": {
      "description": "Optional unique key to make this call safely retryable. If the same key + org repeats, the original result is returned without re-charging.",
      "type": "string",
      "maxLength": 128
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters6

url	string	required	Website URL to analyze. Supports any public website. REQUIRED.
brand_id	string	optional	Optional Brand to attach this scan to. Get from list_brands. When omitted, the pipeline auto-resolves a brand by the URL domain (creating one if needed).
file_ids	array	optional	Array of file IDs from a previous upload. Up to 10 files.
document_urls	array	optional	Array of public URLs pointing to documents (PDF, DOCX, TXT, MD). Up to 10 URLs.
documents_inline	array	optional	Inline documents as base64. The pipeline reads TEXT ONLY — for any PDF or DOCX, extract the text content first using your file-reading tools, save as .md or .txt, then base64-encode and submit here. Supported formats: PDF, DOCX, TXT, MD. Max 5MB per file.
idempotency_key	string	optional	Optional unique key to make this call safely retryable.

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "minLength": 1,
      "description": "Website URL to analyze. Supports any public website. REQUIRED."
    },
    "brand_id": {
      "description": "Optional Brand to attach this scan to. Get from list_brands. When omitted, the pipeline auto-resolves a brand by the URL domain (creating one if needed).",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "file_ids": {
      "description": "Array of file IDs from a previous upload. Up to 10 files.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "document_urls": {
      "description": "Array of public URLs pointing to documents (PDF, DOCX, TXT, MD). Up to 10 URLs.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      }
    },
    "documents_inline": {
      "description": "Inline documents as base64. The pipeline reads TEXT ONLY — for any PDF or DOCX, extract the text content first using your file-reading tools, save as .md or .txt, then base64-encode and submit here. Supported formats: PDF, DOCX, TXT, MD. Max 5MB per file.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "Filename with extension. Use .md or .txt — the pipeline reads text only."
          },
          "content_base64": {
            "type": "string",
            "description": "Base64-encoded file content. Max 5MB per file."
          }
        },
        "required": [
          "filename",
          "content_base64"
        ]
      }
    },
    "idempotency_key": {
      "description": "Optional unique key to make this call safely retryable.",
      "type": "string",
      "maxLength": 128
    }
  },
  "required": [
    "url"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters3

vertical	string	optional	Industry vertical to filter corpus patterns. Examples: BEAUTY_SKINCARE, HEALTH_SUPPLEMENTS, FITNESS, FOOD_BEVERAGE, FASHION_APPAREL, SAAS_SOFTWARE, FINANCE_FINTECH, INFO_PRODUCTS, TECH_GADGETS. Omit for all verticals.
hook_type	string	optional	Specific hook type to retrieve patterns for. Examples: CURIOSITY_SPIKE, OPEN_LOOP_STATEMENT, HIDDEN_TRUTH_REVEAL, IDENTITY_HOOK, CONTRADICTION_HOOK, PROVOCATION, STORY_START, DIRECT_QUESTION_HOOK, CHALLENGE_INTRO, CONTRAST_SETUP. Omit to get the top performing types for the vertical.
marketing_angle	string	optional	Marketing angle to filter by. Examples: PROBLEM_SOLUTION, SOCIAL_PROOF_RESULTS, HOW_TO_TUTORIAL, OFFER_URGENCY, ASPIRATIONAL_IDENTITY, VALUE_STACK. Omit for all angles.

Raw schema

{
  "type": "object",
  "properties": {
    "vertical": {
      "description": "Industry vertical to filter corpus patterns. Examples: BEAUTY_SKINCARE, HEALTH_SUPPLEMENTS, FITNESS, FOOD_BEVERAGE, FASHION_APPAREL, SAAS_SOFTWARE, FINANCE_FINTECH, INFO_PRODUCTS, TECH_GADGETS. Omit for all verticals.",
      "type": "string"
    },
    "hook_type": {
      "description": "Specific hook type to retrieve patterns for. Examples: CURIOSITY_SPIKE, OPEN_LOOP_STATEMENT, HIDDEN_TRUTH_REVEAL, IDENTITY_HOOK, CONTRADICTION_HOOK, PROVOCATION, STORY_START, DIRECT_QUESTION_HOOK, CHALLENGE_INTRO, CONTRAST_SETUP. Omit to get the top performing types for the vertical.",
      "type": "string"
    },
    "marketing_angle": {
      "description": "Marketing angle to filter by. Examples: PROBLEM_SOLUTION, SOCIAL_PROOF_RESULTS, HOW_TO_TUTORIAL, OFFER_URGENCY, ASPIRATIONAL_IDENTITY, VALUE_STACK. Omit for all angles.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters6

vertical	string	optional	Industry vertical to filter formulas. Examples: BEAUTY_SKINCARE, HEALTH_SUPPLEMENTS, FITNESS, FOOD_BEVERAGE, FASHION_APPAREL, SAAS_SOFTWARE, FINANCE_FINTECH, INFO_PRODUCTS, TECH_GADGETS. Omit for all verticals.
creative_format	string	optional	Creative format to filter by. Examples: TALKING_HEAD_BROLL, VOICEOVER_BROLL, UGC_TESTIMONIAL, PRODUCT_DEMO, SLIDESHOW_OVERLAY, INFLUENCER. Omit for all formats.
marketing_angle	string	optional	Marketing angle to filter by. Examples: PROBLEM_SOLUTION, SOCIAL_PROOF_RESULTS, HOW_TO_TUTORIAL, INGREDIENT_SCIENCE, ASPIRATIONAL_IDENTITY, VALUE_STACK. Omit for all angles.
algo_intent	string	optional	Structural engine to filter by. Examples: PROBLEM_AGITATE_SOLVE, MECHANISM_REVEAL, TRANSFORMATION_ARC, SOCIAL_PROOF_STACK, COMPARISON_CONTRAST, URGENCY_SCARCITY. Omit for all intents.
hook_type	string	optional	Filter by opening hook subtype. Examples: CURIOSITY_SPIKE, IDENTITY_HOOK, CONTRADICTION_HOOK, DIRECT_QUESTION_HOOK, PAST_SELF_OPEN, DATA_POINT_START, PROVOCATION. Omit for all hook types.
limit	integer	optional	Max formulas to return (1-10, default 5).

Raw schema

{
  "type": "object",
  "properties": {
    "vertical": {
      "description": "Industry vertical to filter formulas. Examples: BEAUTY_SKINCARE, HEALTH_SUPPLEMENTS, FITNESS, FOOD_BEVERAGE, FASHION_APPAREL, SAAS_SOFTWARE, FINANCE_FINTECH, INFO_PRODUCTS, TECH_GADGETS. Omit for all verticals.",
      "type": "string"
    },
    "creative_format": {
      "description": "Creative format to filter by. Examples: TALKING_HEAD_BROLL, VOICEOVER_BROLL, UGC_TESTIMONIAL, PRODUCT_DEMO, SLIDESHOW_OVERLAY, INFLUENCER. Omit for all formats.",
      "type": "string"
    },
    "marketing_angle": {
      "description": "Marketing angle to filter by. Examples: PROBLEM_SOLUTION, SOCIAL_PROOF_RESULTS, HOW_TO_TUTORIAL, INGREDIENT_SCIENCE, ASPIRATIONAL_IDENTITY, VALUE_STACK. Omit for all angles.",
      "type": "string"
    },
    "algo_intent": {
      "description": "Structural engine to filter by. Examples: PROBLEM_AGITATE_SOLVE, MECHANISM_REVEAL, TRANSFORMATION_ARC, SOCIAL_PROOF_STACK, COMPARISON_CONTRAST, URGENCY_SCARCITY. Omit for all intents.",
      "type": "string"
    },
    "hook_type": {
      "description": "Filter by opening hook subtype. Examples: CURIOSITY_SPIKE, IDENTITY_HOOK, CONTRADICTION_HOOK, DIRECT_QUESTION_HOOK, PAST_SELF_OPEN, DATA_POINT_START, PROVOCATION. Omit for all hook types.",
      "type": "string"
    },
    "limit": {
      "description": "Max formulas to return (1-10, default 5).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters7

vertical	string	optional	Industry vertical to filter decoded ads. Examples: BEAUTY_SKINCARE, HEALTH_SUPPLEMENTS, FITNESS, FOOD_BEVERAGE, FASHION_APPAREL, SAAS_SOFTWARE, FINANCE_FINTECH, INFO_PRODUCTS, TECH_GADGETS. Omit for all verticals.
creative_format	string	optional	Creative format to filter by. Examples: TALKING_HEAD_BROLL, VOICEOVER_BROLL, UGC_TESTIMONIAL, PRODUCT_DEMO, SLIDESHOW_OVERLAY, INFLUENCER. Omit for all formats.
marketing_angle	string	optional	Marketing angle to filter by. Examples: PROBLEM_SOLUTION, SOCIAL_PROOF_RESULTS, HOW_TO_TUTORIAL, INGREDIENT_SCIENCE, ASPIRATIONAL_IDENTITY, VALUE_STACK. Omit for all angles.
hook_type	string	optional	Filter by opening hook type. Examples: CURIOSITY_SPIKE, IDENTITY_HOOK, CONTRADICTION_HOOK, PROVOCATION, STORY_START, DIRECT_QUESTION_HOOK. Omit for all hook types.
algo_intent	string	optional	Structural engine to filter by. Examples: PROBLEM_AGITATE_SOLVE, MECHANISM_REVEAL, TRANSFORMATION_ARC, SOCIAL_PROOF_STACK, COMPARISON_CONTRAST, URGENCY_SCARCITY. Omit for all intents.
brand	string	optional	Filter by brand name (case-insensitive partial match). Examples: "Gymshark", "AG1", "Huel". Omit for all brands.
limit	integer	optional	Max decoded ads to return (1-10, default 5).

Raw schema

{
  "type": "object",
  "properties": {
    "vertical": {
      "description": "Industry vertical to filter decoded ads. Examples: BEAUTY_SKINCARE, HEALTH_SUPPLEMENTS, FITNESS, FOOD_BEVERAGE, FASHION_APPAREL, SAAS_SOFTWARE, FINANCE_FINTECH, INFO_PRODUCTS, TECH_GADGETS. Omit for all verticals.",
      "type": "string"
    },
    "creative_format": {
      "description": "Creative format to filter by. Examples: TALKING_HEAD_BROLL, VOICEOVER_BROLL, UGC_TESTIMONIAL, PRODUCT_DEMO, SLIDESHOW_OVERLAY, INFLUENCER. Omit for all formats.",
      "type": "string"
    },
    "marketing_angle": {
      "description": "Marketing angle to filter by. Examples: PROBLEM_SOLUTION, SOCIAL_PROOF_RESULTS, HOW_TO_TUTORIAL, INGREDIENT_SCIENCE, ASPIRATIONAL_IDENTITY, VALUE_STACK. Omit for all angles.",
      "type": "string"
    },
    "hook_type": {
      "description": "Filter by opening hook type. Examples: CURIOSITY_SPIKE, IDENTITY_HOOK, CONTRADICTION_HOOK, PROVOCATION, STORY_START, DIRECT_QUESTION_HOOK. Omit for all hook types.",
      "type": "string"
    },
    "algo_intent": {
      "description": "Structural engine to filter by. Examples: PROBLEM_AGITATE_SOLVE, MECHANISM_REVEAL, TRANSFORMATION_ARC, SOCIAL_PROOF_STACK, COMPARISON_CONTRAST, URGENCY_SCARCITY. Omit for all intents.",
      "type": "string"
    },
    "brand": {
      "description": "Filter by brand name (case-insensitive partial match). Examples: \"Gymshark\", \"AG1\", \"Huel\". Omit for all brands.",
      "type": "string",
      "maxLength": 100
    },
    "limit": {
      "description": "Max decoded ads to return (1-10, default 5).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters11

source_id	string	required	The ID of the structural source to write from. For source_type="decode": either a job_id from your own decode_ad call OR an id from decoder_intelligence (corpus ad). For source_type="formula": a formula id from adformula_intelligence.
source_type	string	required	Type of structural source. "decode" = a single decoded ad (your own or from the corpus). "formula" = a clustered blueprint built from multiple winning ads.
powersource_id	string	required	Identifier for the brand PowerSource that supplies voice, selling points, tensions, and audience. Accepts either a job_id from create_powersource_* or a brief_id from get_powersource — both work.
count	integer	optional	Number of scripts to generate (1-5, default 1). Each script uses a different tension and selling point combination for variety.
script_mode	string	optional	Script mode. "blueprint" (default) follows the source formula exactly — same beat structure, same timing. "remix" uses the psychological architecture but writes original copy.
duration	integer	optional	Target duration in seconds (remix mode only, 10-120). Blueprint mode locks to the source duration.
audience	string	optional	Audience segment from the PowerSource. "buyer_profile" (default) uses the composite buyer. "audience_0", "audience_1", etc. target specific segments.
tension	string	optional	Lock to a specific behavioral tension from the PowerSource (e.g., "Frustration → Relief"). Omit to let the system select the best match.
selling_points	array	optional	Lock to specific selling points from the PowerSource (max 5). Omit to let the system select the best match for each beat.
voice_mode	string	optional	Voice register for the script. "creator" (default) = authentic creator voice for UGC, PowerSource locks facts/tensions/selling points but NOT voice register. "brand" = full PowerSource brand voice for brand-owned content (website, OOH, brand films). Most ad scripts should use "creator".
idempotency_key	string	optional	Optional unique key to make this call safely retryable. If the same key + org repeats, the original result is returned without re-charging.

Raw schema

{
  "type": "object",
  "properties": {
    "source_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "The ID of the structural source to write from. For source_type=\"decode\": either a job_id from your own decode_ad call OR an id from decoder_intelligence (corpus ad). For source_type=\"formula\": a formula id from adformula_intelligence."
    },
    "source_type": {
      "type": "string",
      "enum": [
        "decode",
        "formula"
      ],
      "description": "Type of structural source. \"decode\" = a single decoded ad (your own or from the corpus). \"formula\" = a clustered blueprint built from multiple winning ads."
    },
    "powersource_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Identifier for the brand PowerSource that supplies voice, selling points, tensions, and audience. Accepts either a job_id from create_powersource_* or a brief_id from get_powersource — both work."
    },
    "count": {
      "description": "Number of scripts to generate (1-5, default 1). Each script uses a different tension and selling point combination for variety.",
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "script_mode": {
      "description": "Script mode. \"blueprint\" (default) follows the source formula exactly — same beat structure, same timing. \"remix\" uses the psychological architecture but writes original copy.",
      "type": "string",
      "enum": [
        "blueprint",
        "remix"
      ]
    },
    "duration": {
      "description": "Target duration in seconds (remix mode only, 10-120). Blueprint mode locks to the source duration.",
      "type": "integer",
      "minimum": 10,
      "maximum": 120
    },
    "audience": {
      "description": "Audience segment from the PowerSource. \"buyer_profile\" (default) uses the composite buyer. \"audience_0\", \"audience_1\", etc. target specific segments.",
      "type": "string",
      "maxLength": 128
    },
    "tension": {
      "description": "Lock to a specific behavioral tension from the PowerSource (e.g., \"Frustration → Relief\"). Omit to let the system select the best match.",
      "type": "string",
      "maxLength": 256
    },
    "selling_points": {
      "description": "Lock to specific selling points from the PowerSource (max 5). Omit to let the system select the best match for each beat.",
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 512
      }
    },
    "voice_mode": {
      "description": "Voice register for the script. \"creator\" (default) = authentic creator voice for UGC, PowerSource locks facts/tensions/selling points but NOT voice register. \"brand\" = full PowerSource brand voice for brand-owned content (website, OOH, brand films). Most ad scripts should use \"creator\".",
      "type": "string",
      "enum": [
        "creator",
        "brand"
      ]
    },
    "idempotency_key": {
      "description": "Optional unique key to make this call safely retryable. If the same key + org repeats, the original result is returned without re-charging.",
      "type": "string",
      "maxLength": 128
    }
  },
  "required": [
    "source_id",
    "source_type",
    "powersource_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters6

brief	string	required	The creative brief — what you want territory directions for. One sentence or short paragraph. Example: "Hero campaign for a sparkling water brand launching in Australia, positioned against soft drink as the everyday adult alternative".
count	integer	required	How many distinct creative territories to generate. Each will sit on different axis coordinates from the others — different psychology, different feel, different world. 2-6.
brand_id	string	optional	Optional Heista brand id (a.k.a. brief id) to ground the territories in. Get from list_brands or any create_powersource_* call. When provided, the engine pulls the brand intelligence (buyer tensions, voice, selling points) and uses it as the entry point into psychology axes. Omit for an unbranded creative exploration.
medium	string	optional	Optional medium — switches the output shape. Omit → territory cards (default exploration). `tvc` → TVC scripts (hook + arc + resolve + sound + end line). `billboard` / `ooh` / `print` → out-of-home concepts (visual + line + placement). `social` → Reels / TikTok / Shorts concepts. `activation` / `experiential` → activation concepts (space + journey + peak moment + takeaway). `audio` → sonic / radio concepts. `campaign` → full campaign platforms (insight → big idea → strategy → visual world → production roadmap). See the tool description for the full per-shape spec.
lens_hint	object	optional	Optional creative lens to constrain the direction. Applied throughout the ideation as a creative constraint. Use when an agent has already picked a playbook or signature move and wants territories under that lens.
idempotency_key	string	optional	Optional unique key to make this call safely retryable. If the same key + org repeats within 5 minutes, the original result is returned without re-charging.

Raw schema

{
  "type": "object",
  "properties": {
    "brief": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "The creative brief — what you want territory directions for. One sentence or short paragraph. Example: \"Hero campaign for a sparkling water brand launching in Australia, positioned against soft drink as the everyday adult alternative\"."
    },
    "count": {
      "type": "integer",
      "minimum": 2,
      "maximum": 6,
      "description": "How many distinct creative territories to generate. Each will sit on different axis coordinates from the others — different psychology, different feel, different world. 2-6."
    },
    "brand_id": {
      "description": "Optional Heista brand id (a.k.a. brief id) to ground the territories in. Get from list_brands or any create_powersource_* call. When provided, the engine pulls the brand intelligence (buyer tensions, voice, selling points) and uses it as the entry point into psychology axes. Omit for an unbranded creative exploration.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "medium": {
      "description": "Optional medium — switches the output shape. Omit → territory cards (default exploration). `tvc` → TVC scripts (hook + arc + resolve + sound + end line). `billboard` / `ooh` / `print` → out-of-home concepts (visual + line + placement). `social` → Reels / TikTok / Shorts concepts. `activation` / `experiential` → activation concepts (space + journey + peak moment + takeaway). `audio` → sonic / radio concepts. `campaign` → full campaign platforms (insight → big idea → strategy → visual world → production roadmap). See the tool description for the full per-shape spec.",
      "type": "string",
      "enum": [
        "tvc",
        "billboard",
        "ooh",
        "activation",
        "experiential",
        "social",
        "campaign",
        "print",
        "audio"
      ]
    },
    "lens_hint": {
      "description": "Optional creative lens to constrain the direction. Applied throughout the ideation as a creative constraint. Use when an agent has already picked a playbook or signature move and wants territories under that lens.",
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 200,
          "description": "The lens / playbook name (e.g. \"Quiet Authority\")."
        },
        "mechanism": {
          "type": "string",
          "maxLength": 1000,
          "description": "One-paragraph description of how the lens works — its psychological engine."
        },
        "constraints": {
          "description": "Optional list of constraints the lens enforces (e.g. [\"never use celebrity endorsement\", \"always feature the product hero\"]).",
          "maxItems": 8,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 200
          }
        }
      },
      "required": [
        "name",
        "mechanism"
      ]
    },
    "idempotency_key": {
      "description": "Optional unique key to make this call safely retryable. If the same key + org repeats within 5 minutes, the original result is returned without re-charging.",
      "type": "string",
      "maxLength": 128
    }
  },
  "required": [
    "brief",
    "count"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters6

agent_id	string	required	The Creative Agent preset id to call. Discover ids via list_creative_agent_presets. Workspace-authored agents are only callable from within the owning org; official templates (visibility=public_template) are callable from any org.
message	string	required	The user turn — the message the caller wants the character to respond to. One-shot; not persisted as a conversation history unless the caller supplies thread_id continuity.
thread_id	string	optional	Optional continuity id round-tripped on the response. Callers manage their own thread state — the runtime does NOT persist history for library calls (chat surface uses its own session table).
brand_id	string	optional	Optional Heista brand id (a.k.a. brief id). When provided, the runtime server-loads the multi-strategy brand summary via `loadMultiBrandContext` and injects it into the agent's system prompt as BRAND INTELLIGENCE. RLS-scoped read — a brand outside the caller's workspace resolves to no summary (silent fall-through).
working_context	object	optional	Optional Working Context labels — brand pin, pinned strategies, pinned documents, loaded playbook. Rendered into the agent's system prompt as an IN SCOPE bullet block so the agent knows what the workspace has pinned. IDs must reference workspace-owned rows. For deeper brand intelligence, pass `brand_id` (server-resolved).
idempotency_key	string	optional	Optional unique key to make this call safely retryable. If the same key + org repeats within 5 minutes, the cached response returns without re-charging.

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The Creative Agent preset id to call. Discover ids via list_creative_agent_presets. Workspace-authored agents are only callable from within the owning org; official templates (visibility=public_template) are callable from any org."
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "The user turn — the message the caller wants the character to respond to. One-shot; not persisted as a conversation history unless the caller supplies thread_id continuity."
    },
    "thread_id": {
      "description": "Optional continuity id round-tripped on the response. Callers manage their own thread state — the runtime does NOT persist history for library calls (chat surface uses its own session table).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "brand_id": {
      "description": "Optional Heista brand id (a.k.a. brief id). When provided, the runtime server-loads the multi-strategy brand summary via `loadMultiBrandContext` and injects it into the agent's system prompt as BRAND INTELLIGENCE. RLS-scoped read — a brand outside the caller's workspace resolves to no summary (silent fall-through).",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "working_context": {
      "type": "object",
      "properties": {
        "brand": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid",
                  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                },
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "logo_url": {
                  "anyOf": [
                    {
                      "type": "string",
                      "maxLength": 2000,
                      "format": "uri"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "id",
                "name"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "strategies": {
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "product_name": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 200
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "is_product_page": {
                "type": "boolean"
              },
              "offer_name": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 200
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "id",
              "title"
            ]
          }
        },
        "documents": {
          "maxItems": 20,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 300
              }
            },
            "required": [
              "id",
              "title"
            ]
          }
        },
        "loadedPlaybook": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid",
                  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                },
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "imageUrl": {
                  "anyOf": [
                    {
                      "type": "string",
                      "maxLength": 2000,
                      "format": "uri"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "id",
                "name"
              ]
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "description": "Optional Working Context labels — brand pin, pinned strategies, pinned documents, loaded playbook. Rendered into the agent's system prompt as an IN SCOPE bullet block so the agent knows what the workspace has pinned. IDs must reference workspace-owned rows. For deeper brand intelligence, pass `brand_id` (server-resolved)."
    },
    "idempotency_key": {
      "description": "Optional unique key to make this call safely retryable. If the same key + org repeats within 5 minutes, the cached response returns without re-charging.",
      "type": "string",
      "maxLength": 128
    }
  },
  "required": [
    "agent_id",
    "message"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters3

message	string	required	The principal's message to the Creative Worlds specialist. First turn: a brief or open question. Subsequent turns: refinement ("make #2 darker"), filtering ("summarise that"), extension ("build a tagline off it").
session_id	string	optional	Pass the session_id returned from a previous chat_with_creative_worlds call to continue that conversation. Omit to start a new session — the response will include a fresh session_id you should pass on every subsequent turn.
brand_id	string	optional	Optional Heista brand_id to ground the conversation in. Only honoured on the first turn of a new session (continuing sessions keep their original brand context).

Raw schema

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "The principal's message to the Creative Worlds specialist. First turn: a brief or open question. Subsequent turns: refinement (\"make #2 darker\"), filtering (\"summarise that\"), extension (\"build a tagline off it\")."
    },
    "session_id": {
      "description": "Pass the session_id returned from a previous chat_with_creative_worlds call to continue that conversation. Omit to start a new session — the response will include a fresh session_id you should pass on every subsequent turn.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "brand_id": {
      "description": "Optional Heista brand_id to ground the conversation in. Only honoured on the first turn of a new session (continuing sessions keep their original brand context).",
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "message"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

include_all

boolean

optional

When true, returns transient (status="creating") and signal-less draft brands too. Default false matches the picker dropdown — only confirmed/draft brands with real data.

Raw schema

{
  "type": "object",
  "properties": {
    "include_all": {
      "description": "When true, returns transient (status=\"creating\") and signal-less draft brands too. Default false matches the picker dropdown — only confirmed/draft brands with real data.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

brand_id

string

required

Brand to inspect. Get from list_brands.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Brand to inspect. Get from list_brands."
    }
  },
  "required": [
    "brand_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters4

brand_id	string	required	Brand to list strategies for. Get from list_brands.
include_archived	boolean	optional	Include archived strategies. Default false.
limit	integer	optional	Page size. Default 20, max 100.
cursor	string	optional	Pagination cursor returned as next_cursor on the previous page.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Brand to list strategies for. Get from list_brands."
    },
    "include_archived": {
      "description": "Include archived strategies. Default false.",
      "type": "boolean"
    },
    "limit": {
      "description": "Page size. Default 20, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "description": "Pagination cursor returned as next_cursor on the previous page.",
      "type": "string"
    }
  },
  "required": [
    "brand_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters7

brand_id	string	required	Brand to list assets for. Get from list_brands.
powersource_id	string	optional	Filter to assets discovered during this PowerSource scan.
product_name	string	optional	Filter to assets the vision tagger read as this on-pack product name.
type	string	optional	Filter by image type: logo, product, product_cutout, hero, lifestyle, ingredient, packaging, certification, before_after, infographic, screenshot, video, general.
is_primary_product	boolean	optional	Filter to only the scanned product's images (or its absence with false).
limit	integer	optional	Page size. Default 50, max 200.
cursor	string	optional	Pagination cursor returned as next_cursor on the previous page.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Brand to list assets for. Get from list_brands."
    },
    "powersource_id": {
      "description": "Filter to assets discovered during this PowerSource scan.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "product_name": {
      "description": "Filter to assets the vision tagger read as this on-pack product name.",
      "type": "string"
    },
    "type": {
      "description": "Filter by image type: logo, product, product_cutout, hero, lifestyle, ingredient, packaging, certification, before_after, infographic, screenshot, video, general.",
      "type": "string",
      "enum": [
        "product",
        "product_cutout",
        "lifestyle",
        "hero",
        "ingredient",
        "packaging",
        "certification",
        "before_after",
        "logo",
        "infographic",
        "screenshot",
        "video",
        "general",
        "retailer_badge",
        "press_badge",
        "partner_logo"
      ]
    },
    "is_primary_product": {
      "description": "Filter to only the scanned product's images (or its absence with false).",
      "type": "boolean"
    },
    "limit": {
      "description": "Page size. Default 50, max 200.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "cursor": {
      "description": "Pagination cursor returned as next_cursor on the previous page.",
      "type": "string"
    }
  },
  "required": [
    "brand_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

brand_id	string	required	Brand to add the asset to. Get from list_brands.
image_url	string	required	Public HTTPS URL to fetch. The pipeline downloads, vision-tags, stores in the brand-assets bucket, and inserts a row.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Brand to add the asset to. Get from list_brands."
    },
    "image_url": {
      "type": "string",
      "format": "uri",
      "description": "Public HTTPS URL to fetch. The pipeline downloads, vision-tags, stores in the brand-assets bucket, and inserts a row."
    }
  },
  "required": [
    "brand_id",
    "image_url"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

asset_id

string

required

Asset to delete. Get from list_brand_assets.

Raw schema

{
  "type": "object",
  "properties": {
    "asset_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Asset to delete. Get from list_brand_assets."
    }
  },
  "required": [
    "asset_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters1

asset_id

string

required

Asset to re-classify. Get from list_brand_assets.

Raw schema

{
  "type": "object",
  "properties": {
    "asset_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Asset to re-classify. Get from list_brand_assets."
    }
  },
  "required": [
    "asset_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters1

brand_id

string

required

Brand whose unreviewed assets should be re-run through the vision tagger. Only assets with vision_classified=false are processed. Get from list_brands.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Brand whose unreviewed assets should be re-run through the vision tagger. Only assets with vision_classified=false are processed. Get from list_brands."
    }
  },
  "required": [
    "brand_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

brand_id	string	required	Brand to list documents for. Get from list_brands.
doc_type	string	optional	Filter by classified document type. One of 19 values: voice_tone_doc, brand_guidelines, strategy_memo, brand_brief, pitch_deck, research_report, campaign_brief, tone_of_voice_synthesis, customer_interview, meeting_notes, press_release, campaign_retrospective, workshop_output, spreadsheet_data, internal_memo, legal_compliance, sales_script, founder_interview, general_reference.
indexing_status	string	optional	Filter by indexing pipeline state. Use "indexed" to only see fully-processed docs ready to read.
limit	integer	optional	Page size. Default 20, max 100.
cursor	string	optional	Pagination cursor returned as next_cursor on the previous page (created_at ISO timestamp).

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Brand to list documents for. Get from list_brands."
    },
    "doc_type": {
      "description": "Filter by classified document type. One of 19 values: voice_tone_doc, brand_guidelines, strategy_memo, brand_brief, pitch_deck, research_report, campaign_brief, tone_of_voice_synthesis, customer_interview, meeting_notes, press_release, campaign_retrospective, workshop_output, spreadsheet_data, internal_memo, legal_compliance, sales_script, founder_interview, general_reference.",
      "type": "string",
      "enum": [
        "voice_tone_doc",
        "brand_guidelines",
        "strategy_memo",
        "brand_brief",
        "pitch_deck",
        "research_report",
        "campaign_brief",
        "tone_of_voice_synthesis",
        "customer_interview",
        "meeting_notes",
        "press_release",
        "campaign_retrospective",
        "workshop_output",
        "spreadsheet_data",
        "internal_memo",
        "legal_compliance",
        "sales_script",
        "founder_interview",
        "general_reference"
      ]
    },
    "indexing_status": {
      "description": "Filter by indexing pipeline state. Use \"indexed\" to only see fully-processed docs ready to read.",
      "type": "string",
      "enum": [
        "pending",
        "running",
        "indexed",
        "error"
      ]
    },
    "limit": {
      "description": "Page size. Default 20, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "description": "Pagination cursor returned as next_cursor on the previous page (created_at ISO timestamp).",
      "type": "string"
    }
  },
  "required": [
    "brand_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

read_brand_document

Read one indexed brand document. Returns the indexed metadata (doc_type, summary, key_topics, entities, key_quotes) plus the document content, routed by mime: text/markdown, text/plain, text/csv are inlined as text; application/pdf and other text-shaped mimes return an Anthropic Files API file_id (attach via document source { type:"file", file_id } on the next turn); DOCX/PPTX/XLSX return a requires_code_execution marker (caller must enable code_execution_20260120 and attach via container_upload). Use AFTER list_brand_documents to pick the right document. Free, read-only.

Parameters1

document_id

string

required

Document to read. Get from list_brand_documents.

Raw schema

{
  "type": "object",
  "properties": {
    "document_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Document to read. Get from list_brand_documents."
    }
  },
  "required": [
    "document_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters3

domain	string	optional	Filter by domain. Use "all" or omit to get every skill. Available domains depend on what has been authored; current live domains include shared, image, video. Authoring will add research, strategy, copy, creative, generation as the fleet grows.
type	string	optional	Filter by skill type. "foundation" = always-on craft baseline per domain. "registers" = router-table over a references/ folder (e.g. cinema-mode, lighting). "methodologies" = how-to skills for specific job types. "models" = per-versioned-model profile (e.g. google-nano-banana-pro).
source_folder	string	optional	Filter by source folder. "managed-agents" = fleet skills (Mastermind, Heads Of, fleet specialists). "chat-agent" = chat-surface lenses. "all" or omit to get everything. Folder is organisation only; any skill can be attached by any agent via skill_id.

Raw schema

{
  "type": "object",
  "properties": {
    "domain": {
      "description": "Filter by domain. Use \"all\" or omit to get every skill. Available domains depend on what has been authored; current live domains include shared, image, video. Authoring will add research, strategy, copy, creative, generation as the fleet grows.",
      "type": "string",
      "enum": [
        "shared",
        "image",
        "video",
        "research",
        "strategy",
        "copy",
        "creative",
        "generation",
        "all"
      ]
    },
    "type": {
      "description": "Filter by skill type. \"foundation\" = always-on craft baseline per domain. \"registers\" = router-table over a references/ folder (e.g. cinema-mode, lighting). \"methodologies\" = how-to skills for specific job types. \"models\" = per-versioned-model profile (e.g. google-nano-banana-pro).",
      "type": "string",
      "enum": [
        "foundation",
        "registers",
        "models",
        "methodologies",
        "all"
      ]
    },
    "source_folder": {
      "description": "Filter by source folder. \"managed-agents\" = fleet skills (Mastermind, Heads Of, fleet specialists). \"chat-agent\" = chat-surface lenses. \"all\" or omit to get everything. Folder is organisation only; any skill can be attached by any agent via skill_id.",
      "type": "string",
      "enum": [
        "managed-agents",
        "chat-agent",
        "all"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

name

string

required

Canonical skill name in dot-notation (e.g. "research.foundation", "research.methodologies.desk-synthesis", "shared.registers.cinema-mode"). Find via list_skills first.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "description": "Canonical skill name in dot-notation (e.g. \"research.foundation\", \"research.methodologies.desk-synthesis\", \"shared.registers.cinema-mode\"). Find via list_skills first."
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

skill_name	string	required	Parent skill name in dot-notation (e.g. "shared.registers.cinema-mode"). Only register-type skills have references/; foundations and methodologies are inline content only.
reference_path	string	required	Reference filename within the skill's references/ folder (e.g. "m1-narrative.md"). Find via the parent SKILL.md router table. Path-traversal protected — must be a plain filename, no "..", no absolute paths.

Raw schema

{
  "type": "object",
  "properties": {
    "skill_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "description": "Parent skill name in dot-notation (e.g. \"shared.registers.cinema-mode\"). Only register-type skills have references/; foundations and methodologies are inline content only."
    },
    "reference_path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "description": "Reference filename within the skill's references/ folder (e.g. \"m1-narrative.md\"). Find via the parent SKILL.md router table. Path-traversal protected — must be a plain filename, no \"..\", no absolute paths."
    }
  },
  "required": [
    "skill_name",
    "reference_path"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters3

query	string	required	Search query. Phrase as a natural-language question or precise topic description. The research agent has already done question decomposition — this is one focused query, not a multi-question batch.
recency_filter	string	optional	Limit results to content published within this window. Use for fast-decay topics (model capabilities, platform algo changes, ad-format performance) per research.foundation §5. Omit for slow-decay topics (buyer psychology, established frameworks).
search_domain_filter	array	optional	Restrict search to these domains (e.g. ["motionapp.com", "about.fb.com"]). Use when triangulating against known-authoritative sources, or when evidence-querying for a specific named brand/publication.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 3,
      "maxLength": 1500,
      "description": "Search query. Phrase as a natural-language question or precise topic description. The research agent has already done question decomposition — this is one focused query, not a multi-question batch."
    },
    "recency_filter": {
      "description": "Limit results to content published within this window. Use for fast-decay topics (model capabilities, platform algo changes, ad-format performance) per research.foundation §5. Omit for slow-decay topics (buyer psychology, established frameworks).",
      "type": "string",
      "enum": [
        "hour",
        "day",
        "week",
        "month",
        "year"
      ]
    },
    "search_domain_filter": {
      "description": "Restrict search to these domains (e.g. [\"motionapp.com\", \"about.fb.com\"]). Use when triangulating against known-authoritative sources, or when evidence-querying for a specific named brand/publication.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters3

query	string	required	Search query. Phrase as a natural-language question or precise topic description. The research agent has already done question decomposition — this is one focused query, not a multi-question batch.
max_results	integer	optional	Maximum number of results to return. Default 10. Higher counts return more sources but cost more in tokens — keep at 10 for general use.
after_date	string	optional	ISO date (YYYY-MM-DD). Restrict results to content published after this date. Use for fast-decay topics (model capabilities, platform algo changes, ad-format performance) per research.foundation §5. Omit for slow-decay topics (buyer psychology, established frameworks).

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 3,
      "maxLength": 1500,
      "description": "Search query. Phrase as a natural-language question or precise topic description. The research agent has already done question decomposition — this is one focused query, not a multi-question batch."
    },
    "max_results": {
      "description": "Maximum number of results to return. Default 10. Higher counts return more sources but cost more in tokens — keep at 10 for general use.",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "after_date": {
      "description": "ISO date (YYYY-MM-DD). Restrict results to content published after this date. Use for fast-decay topics (model capabilities, platform algo changes, ad-format performance) per research.foundation §5. Omit for slow-decay topics (buyer psychology, established frameworks).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters4

query	string	required	Search query. Phrase as natural-language. Focused on what people are SAYING — practitioner voice, named-operator discourse, community reaction. Not a general fact-check query.
platforms	array	optional	Limit search to these platforms. Use ["reddit"] for r/* threads, ["x","twitter"] for X posts, ["substack"] for named essays. Omit to let the search engine choose. Per social-listening-synthesis §3 sample ≥3 platforms per brief — pass at least 3 here for multi-platform discourse mapping.
max_results	integer	optional	Maximum results. Default 10.
after_date	string	optional	ISO date (YYYY-MM-DD). Restrict to content after this date. Use for recency-sharp community signal mapping.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 3,
      "maxLength": 1500,
      "description": "Search query. Phrase as natural-language. Focused on what people are SAYING — practitioner voice, named-operator discourse, community reaction. Not a general fact-check query."
    },
    "platforms": {
      "description": "Limit search to these platforms. Use [\"reddit\"] for r/* threads, [\"x\",\"twitter\"] for X posts, [\"substack\"] for named essays. Omit to let the search engine choose. Per social-listening-synthesis §3 sample ≥3 platforms per brief — pass at least 3 here for multi-platform discourse mapping.",
      "minItems": 1,
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "reddit",
          "twitter",
          "x",
          "linkedin",
          "substack",
          "facebook",
          "youtube",
          "instagram",
          "tiktok",
          "mastodon",
          "threads",
          "discord"
        ]
      }
    },
    "max_results": {
      "description": "Maximum results. Default 10.",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "after_date": {
      "description": "ISO date (YYYY-MM-DD). Restrict to content after this date. Use for recency-sharp community signal mapping.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters3

query	string	required	Research query. Phrase as a precise factual question — what number, what claim, what methodology. The research agent has already decomposed the brief; this is one focused query.
recency_filter	string	optional	Limit results to content published within this window. Use for recent earnings, recent regulatory filings, recent industry reports.
search_domain_filter	array	optional	Restrict to these domains (e.g. ["investor.atmeta.com", "sec.gov"]). Use when triangulating against known T1 sources or specific authoritative publications.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 3,
      "maxLength": 1500,
      "description": "Research query. Phrase as a precise factual question — what number, what claim, what methodology. The research agent has already decomposed the brief; this is one focused query."
    },
    "recency_filter": {
      "description": "Limit results to content published within this window. Use for recent earnings, recent regulatory filings, recent industry reports.",
      "type": "string",
      "enum": [
        "hour",
        "day",
        "week",
        "month",
        "year"
      ]
    },
    "search_domain_filter": {
      "description": "Restrict to these domains (e.g. [\"investor.atmeta.com\", \"sec.gov\"]). Use when triangulating against known T1 sources or specific authoritative publications.",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

url	string	required	Absolute URL to fetch. Used to drill into a specific source after search surfaces it. Must be http:// or https://. Private IPs and localhost are blocked (SSRF protection).
max_chars	integer	optional	Maximum characters of extracted content to return. Default 8000. Higher returns more text but costs more in agent tokens.

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2000,
      "format": "uri",
      "description": "Absolute URL to fetch. Used to drill into a specific source after search surfaces it. Must be http:// or https://. Private IPs and localhost are blocked (SSRF protection)."
    },
    "max_chars": {
      "description": "Maximum characters of extracted content to return. Default 8000. Higher returns more text but costs more in agent tokens.",
      "type": "integer",
      "minimum": 100,
      "maximum": 50000
    }
  },
  "required": [
    "url"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

dispatch_desk_researcher

Parameters5

objective	string	required	One sentence stating what "done" looks like — the specific deliverable the specialist must return. From the four-part delegation contract (agent-authoring §5).
output_format	string	required	The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly (parent may summarize otherwise).
tool_guidance	string	required	How the specialist should approach this — which of its tools to favor, effort budget in tool calls, query angles to prioritize.
boundaries	string	required	In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. "do not spawn further subagents", "only Meta paid social").
priority	string	optional	standard (default) uses the specialist's production model; deep uses its escalation model (per _config/model-assignments.ts).

Raw schema

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "One sentence stating what \"done\" looks like — the specific deliverable the specialist must return. From the four-part delegation contract (agent-authoring §5)."
    },
    "output_format": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly (parent may summarize otherwise)."
    },
    "tool_guidance": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "How the specialist should approach this — which of its tools to favor, effort budget in tool calls, query angles to prioritize."
    },
    "boundaries": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. \"do not spawn further subagents\", \"only Meta paid social\")."
    },
    "priority": {
      "description": "standard (default) uses the specialist's production model; deep uses its escalation model (per _config/model-assignments.ts).",
      "type": "string",
      "enum": [
        "standard",
        "deep"
      ]
    }
  },
  "required": [
    "objective",
    "output_format",
    "tool_guidance",
    "boundaries"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

dispatch_trend_researcher

Parameters5

objective	string	required	One sentence stating what "done" looks like — the specific deliverable the specialist must return. From the four-part delegation contract (agent-authoring §5).
output_format	string	required	The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly (parent may summarize otherwise).
tool_guidance	string	required	How the specialist should approach this — which of its tools to favor, effort budget in tool calls, query angles to prioritize.
boundaries	string	required	In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. "do not spawn further subagents", "only Meta paid social").
priority	string	optional	standard (default) uses the specialist's production model; deep uses its escalation model (per _config/model-assignments.ts).

Raw schema

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "One sentence stating what \"done\" looks like — the specific deliverable the specialist must return. From the four-part delegation contract (agent-authoring §5)."
    },
    "output_format": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly (parent may summarize otherwise)."
    },
    "tool_guidance": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "How the specialist should approach this — which of its tools to favor, effort budget in tool calls, query angles to prioritize."
    },
    "boundaries": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. \"do not spawn further subagents\", \"only Meta paid social\")."
    },
    "priority": {
      "description": "standard (default) uses the specialist's production model; deep uses its escalation model (per _config/model-assignments.ts).",
      "type": "string",
      "enum": [
        "standard",
        "deep"
      ]
    }
  },
  "required": [
    "objective",
    "output_format",
    "tool_guidance",
    "boundaries"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

dispatch_market_analyst

Parameters5

objective	string	required	One sentence stating what "done" looks like — the specific deliverable the specialist must return. From the four-part delegation contract (agent-authoring §5).
output_format	string	required	The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly (parent may summarize otherwise).
tool_guidance	string	required	How the specialist should approach this — which of its tools to favor, effort budget in tool calls, query angles to prioritize.
boundaries	string	required	In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. "do not spawn further subagents", "only Meta paid social").
priority	string	optional	standard (default) uses the specialist's production model; deep uses its escalation model (per _config/model-assignments.ts).

Raw schema

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "One sentence stating what \"done\" looks like — the specific deliverable the specialist must return. From the four-part delegation contract (agent-authoring §5)."
    },
    "output_format": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly (parent may summarize otherwise)."
    },
    "tool_guidance": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "How the specialist should approach this — which of its tools to favor, effort budget in tool calls, query angles to prioritize."
    },
    "boundaries": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. \"do not spawn further subagents\", \"only Meta paid social\")."
    },
    "priority": {
      "description": "standard (default) uses the specialist's production model; deep uses its escalation model (per _config/model-assignments.ts).",
      "type": "string",
      "enum": [
        "standard",
        "deep"
      ]
    }
  },
  "required": [
    "objective",
    "output_format",
    "tool_guidance",
    "boundaries"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

dispatch_quantitative_researcher

Parameters5

objective	string	required	One sentence stating what "done" looks like — the specific deliverable the specialist must return. From the four-part delegation contract (agent-authoring §5).
output_format	string	required	The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly (parent may summarize otherwise).
tool_guidance	string	required	How the specialist should approach this — which of its tools to favor, effort budget in tool calls, query angles to prioritize.
boundaries	string	required	In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. "do not spawn further subagents", "only Meta paid social").
priority	string	optional	standard (default) uses the specialist's production model; deep uses its escalation model (per _config/model-assignments.ts).

Raw schema

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "One sentence stating what \"done\" looks like — the specific deliverable the specialist must return. From the four-part delegation contract (agent-authoring §5)."
    },
    "output_format": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly (parent may summarize otherwise)."
    },
    "tool_guidance": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "How the specialist should approach this — which of its tools to favor, effort budget in tool calls, query angles to prioritize."
    },
    "boundaries": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. \"do not spawn further subagents\", \"only Meta paid social\")."
    },
    "priority": {
      "description": "standard (default) uses the specialist's production model; deep uses its escalation model (per _config/model-assignments.ts).",
      "type": "string",
      "enum": [
        "standard",
        "deep"
      ]
    }
  },
  "required": [
    "objective",
    "output_format",
    "tool_guidance",
    "boundaries"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

dispatch_qualitative_researcher

Parameters5

objective	string	required	One sentence stating what "done" looks like — the specific deliverable the specialist must return. From the four-part delegation contract (agent-authoring §5).
output_format	string	required	The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly (parent may summarize otherwise).
tool_guidance	string	required	How the specialist should approach this — which of its tools to favor, effort budget in tool calls, query angles to prioritize.
boundaries	string	required	In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. "do not spawn further subagents", "only Meta paid social").
priority	string	optional	standard (default) uses the specialist's production model; deep uses its escalation model (per _config/model-assignments.ts).

Raw schema

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "One sentence stating what \"done\" looks like — the specific deliverable the specialist must return. From the four-part delegation contract (agent-authoring §5)."
    },
    "output_format": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly (parent may summarize otherwise)."
    },
    "tool_guidance": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "How the specialist should approach this — which of its tools to favor, effort budget in tool calls, query angles to prioritize."
    },
    "boundaries": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. \"do not spawn further subagents\", \"only Meta paid social\")."
    },
    "priority": {
      "description": "standard (default) uses the specialist's production model; deep uses its escalation model (per _config/model-assignments.ts).",
      "type": "string",
      "enum": [
        "standard",
        "deep"
      ]
    }
  },
  "required": [
    "objective",
    "output_format",
    "tool_guidance",
    "boundaries"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

dispatch_social_listening_researcher

Parameters5

objective	string	required	One sentence stating what "done" looks like — the specific deliverable the specialist must return. From the four-part delegation contract (agent-authoring §5).
output_format	string	required	The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly (parent may summarize otherwise).
tool_guidance	string	required	How the specialist should approach this — which of its tools to favor, effort budget in tool calls, query angles to prioritize.
boundaries	string	required	In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. "do not spawn further subagents", "only Meta paid social").
priority	string	optional	standard (default) uses the specialist's production model; deep uses its escalation model (per _config/model-assignments.ts).

Raw schema

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "One sentence stating what \"done\" looks like — the specific deliverable the specialist must return. From the four-part delegation contract (agent-authoring §5)."
    },
    "output_format": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly (parent may summarize otherwise)."
    },
    "tool_guidance": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "How the specialist should approach this — which of its tools to favor, effort budget in tool calls, query angles to prioritize."
    },
    "boundaries": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. \"do not spawn further subagents\", \"only Meta paid social\")."
    },
    "priority": {
      "description": "standard (default) uses the specialist's production model; deep uses its escalation model (per _config/model-assignments.ts).",
      "type": "string",
      "enum": [
        "standard",
        "deep"
      ]
    }
  },
  "required": [
    "objective",
    "output_format",
    "tool_guidance",
    "boundaries"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

objective	string	required	One sentence stating what "done" looks like — the specific deliverable. From the four-part delegation contract (agent-authoring §5).
output_format	string	required	The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly.
tool_guidance	string	required	How the specialist should approach this — which tools to favor, effort budget in tool calls, query angles to prioritize.
boundaries	string	required	In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. "do not spawn further subagents", "only Meta paid social").
priority	string	optional	standard (default) uses the specialist's production model; deep uses its escalation model.

Raw schema

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "One sentence stating what \"done\" looks like — the specific deliverable. From the four-part delegation contract (agent-authoring §5)."
    },
    "output_format": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly."
    },
    "tool_guidance": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "How the specialist should approach this — which tools to favor, effort budget in tool calls, query angles to prioritize."
    },
    "boundaries": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. \"do not spawn further subagents\", \"only Meta paid social\")."
    },
    "priority": {
      "description": "standard (default) uses the specialist's production model; deep uses its escalation model.",
      "type": "string",
      "enum": [
        "standard",
        "deep"
      ]
    }
  },
  "required": [
    "objective",
    "output_format",
    "tool_guidance",
    "boundaries"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

objective	string	required	One sentence stating what "done" looks like — the specific deliverable. From the four-part delegation contract (agent-authoring §5).
output_format	string	required	The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly.
tool_guidance	string	required	How the specialist should approach this — which tools to favor, effort budget in tool calls, query angles to prioritize.
boundaries	string	required	In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. "do not spawn further subagents", "only Meta paid social").
priority	string	optional	standard (default) uses the specialist's production model; deep uses its escalation model.

Raw schema

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "One sentence stating what \"done\" looks like — the specific deliverable. From the four-part delegation contract (agent-authoring §5)."
    },
    "output_format": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly."
    },
    "tool_guidance": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "How the specialist should approach this — which tools to favor, effort budget in tool calls, query angles to prioritize."
    },
    "boundaries": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. \"do not spawn further subagents\", \"only Meta paid social\")."
    },
    "priority": {
      "description": "standard (default) uses the specialist's production model; deep uses its escalation model.",
      "type": "string",
      "enum": [
        "standard",
        "deep"
      ]
    }
  },
  "required": [
    "objective",
    "output_format",
    "tool_guidance",
    "boundaries"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

objective	string	required	One sentence stating what "done" looks like — the specific deliverable. From the four-part delegation contract (agent-authoring §5).
output_format	string	required	The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly.
tool_guidance	string	required	How the specialist should approach this — which tools to favor, effort budget in tool calls, query angles to prioritize.
boundaries	string	required	In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. "do not spawn further subagents", "only Meta paid social").
priority	string	optional	standard (default) uses the specialist's production model; deep uses its escalation model.

Raw schema

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "One sentence stating what \"done\" looks like — the specific deliverable. From the four-part delegation contract (agent-authoring §5)."
    },
    "output_format": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly."
    },
    "tool_guidance": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "How the specialist should approach this — which tools to favor, effort budget in tool calls, query angles to prioritize."
    },
    "boundaries": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. \"do not spawn further subagents\", \"only Meta paid social\")."
    },
    "priority": {
      "description": "standard (default) uses the specialist's production model; deep uses its escalation model.",
      "type": "string",
      "enum": [
        "standard",
        "deep"
      ]
    }
  },
  "required": [
    "objective",
    "output_format",
    "tool_guidance",
    "boundaries"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

objective	string	required	One sentence stating what "done" looks like — the specific deliverable. From the four-part delegation contract (agent-authoring §5).
output_format	string	required	The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly.
tool_guidance	string	required	How the specialist should approach this — which tools to favor, effort budget in tool calls, query angles to prioritize.
boundaries	string	required	In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. "do not spawn further subagents", "only Meta paid social").
priority	string	optional	standard (default) uses the specialist's production model; deep uses its escalation model.

Raw schema

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "One sentence stating what \"done\" looks like — the specific deliverable. From the four-part delegation contract (agent-authoring §5)."
    },
    "output_format": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly."
    },
    "tool_guidance": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "How the specialist should approach this — which tools to favor, effort budget in tool calls, query angles to prioritize."
    },
    "boundaries": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. \"do not spawn further subagents\", \"only Meta paid social\")."
    },
    "priority": {
      "description": "standard (default) uses the specialist's production model; deep uses its escalation model.",
      "type": "string",
      "enum": [
        "standard",
        "deep"
      ]
    }
  },
  "required": [
    "objective",
    "output_format",
    "tool_guidance",
    "boundaries"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

objective	string	required	One sentence stating what "done" looks like — the specific deliverable. From the four-part delegation contract (agent-authoring §5).
output_format	string	required	The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly.
tool_guidance	string	required	How the specialist should approach this — which tools to favor, effort budget in tool calls, query angles to prioritize.
boundaries	string	required	In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. "do not spawn further subagents", "only Meta paid social").
priority	string	optional	standard (default) uses the specialist's production model; deep uses its escalation model.

Raw schema

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "One sentence stating what \"done\" looks like — the specific deliverable. From the four-part delegation contract (agent-authoring §5)."
    },
    "output_format": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly."
    },
    "tool_guidance": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "How the specialist should approach this — which tools to favor, effort budget in tool calls, query angles to prioritize."
    },
    "boundaries": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. \"do not spawn further subagents\", \"only Meta paid social\")."
    },
    "priority": {
      "description": "standard (default) uses the specialist's production model; deep uses its escalation model.",
      "type": "string",
      "enum": [
        "standard",
        "deep"
      ]
    }
  },
  "required": [
    "objective",
    "output_format",
    "tool_guidance",
    "boundaries"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

objective	string	required	One sentence stating what "done" looks like — the specific deliverable. From the four-part delegation contract (agent-authoring §5).
output_format	string	required	The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly.
tool_guidance	string	required	How the specialist should approach this — which tools to favor, effort budget in tool calls, query angles to prioritize.
boundaries	string	required	In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. "do not spawn further subagents", "only Meta paid social").
priority	string	optional	standard (default) uses the specialist's production model; deep uses its escalation model.

Raw schema

{
  "type": "object",
  "properties": {
    "objective": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "One sentence stating what \"done\" looks like — the specific deliverable. From the four-part delegation contract (agent-authoring §5)."
    },
    "output_format": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "The shape the specialist must return — schema, template, or specific format. If verbatim-return needed, say so explicitly."
    },
    "tool_guidance": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "How the specialist should approach this — which tools to favor, effort budget in tool calls, query angles to prioritize."
    },
    "boundaries": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1500,
      "description": "In scope vs out of scope. Explicit OUT_OF_SCOPE clauses. Constraints (e.g. \"do not spawn further subagents\", \"only Meta paid social\")."
    },
    "priority": {
      "description": "standard (default) uses the specialist's production model; deep uses its escalation model.",
      "type": "string",
      "enum": [
        "standard",
        "deep"
      ]
    }
  },
  "required": [
    "objective",
    "output_format",
    "tool_guidance",
    "boundaries"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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).

Parameters3

brief	string	required	The research brief to send to the Head. Must be self-contained — the Head sees only this string, no conversation history. Include entity, time window, scope, and unit of analysis explicitly. Be concrete: vague briefs produce vague output.
priority	string	optional	standard (default) uses production models in specialists; deep escalates to higher-capability models. Use deep when accuracy matters more than cost.
max_wait_seconds	integer	optional	Hard cap on how long to wait for the Head session to complete. Default 270 (4.5 min). Heads typically complete in 2-5 min; raise this if you expect a deep research brief.

Raw schema

{
  "type": "object",
  "properties": {
    "brief": {
      "type": "string",
      "minLength": 20,
      "maxLength": 8000,
      "description": "The research brief to send to the Head. Must be self-contained — the Head sees only this string, no conversation history. Include entity, time window, scope, and unit of analysis explicitly. Be concrete: vague briefs produce vague output."
    },
    "priority": {
      "description": "standard (default) uses production models in specialists; deep escalates to higher-capability models. Use deep when accuracy matters more than cost.",
      "type": "string",
      "enum": [
        "standard",
        "deep"
      ]
    },
    "max_wait_seconds": {
      "description": "Hard cap on how long to wait for the Head session to complete. Default 270 (4.5 min). Heads typically complete in 2-5 min; raise this if you expect a deep research brief.",
      "type": "integer",
      "minimum": 60,
      "maximum": 900
    }
  },
  "required": [
    "brief"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

job_id

string

required

The job_id returned by a previous dispatch_<specialist>_async call.

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The job_id returned by a previous dispatch_<specialist>_async call."
    }
  },
  "required": [
    "job_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

root_session_id

string

required

A session_id from anywhere in the fleet tree — root, Head, Mastermind, or specialist sub-node. The handler resolves to the actual root and walks the full subtree, so you do not need to know the root id specifically. Org-scoped: only sessions belonging to your org return data.

Raw schema

{
  "type": "object",
  "properties": {
    "root_session_id": {
      "type": "string",
      "minLength": 1,
      "description": "A session_id from anywhere in the fleet tree — root, Head, Mastermind, or specialist sub-node. The handler resolves to the actual root and walks the full subtree, so you do not need to know the root id specifically. Org-scoped: only sessions belonging to your org return data."
    }
  },
  "required": [
    "root_session_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters11

category	string	optional	Tab filter. STRATEGY (positioning, brand platform), IDEAS (hooks, concepts, territories), COPY (ad scripts, hooks, campaign copy), VISUALS (static ads, product, lifestyle imagery), MOTION (talking heads, b-roll, lifestyle video), BRIEFS (creator briefs — backed by a separate table; reads include share URLs). Omit to read every category in one merged stream.
formats	array	optional	Multi-select format pills within a category. e.g. for COPY: ["ad-script","hook"]. See save_asset description for the full per-category enum.
tags	array	optional	Tag filter. Default mode is `any` (OR). Switch to `all` with tags_mode.
tags_mode	string	optional	How to combine tags. Default `any` (overlap). `all` requires every tag.
brand_id	string	optional	Limit to one brand.
brief_id	string	optional	Limit to one PowerSource (brief).
created_by	string	optional	User id or the literal "me". When called via OAuth, "me" resolves to the caller. API-key callers MUST pass an explicit user id (no caller identity).
favorites_only	boolean	optional	Restrict to favorited assets only.
search	string	optional	Full-text search on title + body + tags.
limit	integer	optional	Page size. Default 50, max 200.
cursor	string	optional	Pagination cursor returned as next_cursor on the previous page.

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "description": "Tab filter. STRATEGY (positioning, brand platform), IDEAS (hooks, concepts, territories), COPY (ad scripts, hooks, campaign copy), VISUALS (static ads, product, lifestyle imagery), MOTION (talking heads, b-roll, lifestyle video), BRIEFS (creator briefs — backed by a separate table; reads include share URLs). Omit to read every category in one merged stream.",
      "type": "string",
      "enum": [
        "STRATEGY",
        "IDEAS",
        "COPY",
        "VISUALS",
        "MOTION",
        "BRIEFS"
      ]
    },
    "formats": {
      "description": "Multi-select format pills within a category. e.g. for COPY: [\"ad-script\",\"hook\"]. See save_asset description for the full per-category enum.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tags": {
      "description": "Tag filter. Default mode is `any` (OR). Switch to `all` with tags_mode.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tags_mode": {
      "description": "How to combine tags. Default `any` (overlap). `all` requires every tag.",
      "type": "string",
      "enum": [
        "any",
        "all"
      ]
    },
    "brand_id": {
      "description": "Limit to one brand.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "brief_id": {
      "description": "Limit to one PowerSource (brief).",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "created_by": {
      "description": "User id or the literal \"me\". When called via OAuth, \"me\" resolves to the caller. API-key callers MUST pass an explicit user id (no caller identity).",
      "type": "string"
    },
    "favorites_only": {
      "description": "Restrict to favorited assets only.",
      "type": "boolean"
    },
    "search": {
      "description": "Full-text search on title + body + tags.",
      "type": "string"
    },
    "limit": {
      "description": "Page size. Default 50, max 200.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "cursor": {
      "description": "Pagination cursor returned as next_cursor on the previous page.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

asset_id

string

required

Asset to fetch. Get from list_saved_assets.

Raw schema

{
  "type": "object",
  "properties": {
    "asset_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Asset to fetch. Get from list_saved_assets."
    }
  },
  "required": [
    "asset_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

asset_ids

array

required

Up to 50 asset ids to fetch in one round-trip. Use when an agent needs to pull a pre-selected set of saves (e.g. resolving a saved_asset_picker declaration in a Heist). Missing/cross-workspace ids are silently dropped.

Raw schema

{
  "type": "object",
  "properties": {
    "asset_ids": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      },
      "description": "Up to 50 asset ids to fetch in one round-trip. Use when an agent needs to pull a pre-selected set of saves (e.g. resolving a saved_asset_picker declaration in a Heist). Missing/cross-workspace ids are silently dropped."
    }
  },
  "required": [
    "asset_ids"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters14

category	string	required	One of STRATEGY, IDEAS, COPY, VISUALS, MOTION. BRIEFS is not accepted — briefs live in the creator_briefs table via the briefs API.
format	string	required	Per-category format. STRATEGY: positioning, brand-platform, campaign-strategy, strategic-doc. IDEAS: hook, concept, big-idea, territory. COPY: ad-script, hook, campaign-copy. VISUALS: static-ad, product, lifestyle, hero, moodboard, packaging, logo. MOTION: talking-head, b-roll, product-motion, brand-lifestyle.
tags	array	optional	Free-form tags for filtering and search.
source	object	required	Save attribution.
brand_id	string	optional	Brand the asset is for. Resolved from brief_id when omitted.
brief_id	string	optional	PowerSource (brief) the asset was generated against.
parent_id	string	optional	Parent asset id for variations grouped under one save set.
title	string	required	Card title — what shows in /assets.
body_text	string	optional	Primary text body for STRATEGY / IDEAS / COPY saves.
body_html	string	optional	Rich-text body where the asset carries structured markup.
media_url	string	optional	Direct media URL for VISUALS / MOTION (external host).
media_storage_path	string	optional	Storage path inside the private `saved-assets` bucket. Obtain via the /api/saved-assets/upload-url route (REST only; no MCP upload tool yet).
thumb_url	string	optional	Card thumbnail URL.
metadata	object	optional	Type-specific bag — duration, image dimensions, model used, beat count, etc.

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "STRATEGY",
        "IDEAS",
        "COPY",
        "VISUALS",
        "MOTION"
      ],
      "description": "One of STRATEGY, IDEAS, COPY, VISUALS, MOTION. BRIEFS is not accepted — briefs live in the creator_briefs table via the briefs API."
    },
    "format": {
      "type": "string",
      "description": "Per-category format. STRATEGY: positioning, brand-platform, campaign-strategy, strategic-doc. IDEAS: hook, concept, big-idea, territory. COPY: ad-script, hook, campaign-copy. VISUALS: static-ad, product, lifestyle, hero, moodboard, packaging, logo. MOTION: talking-head, b-roll, product-motion, brand-lifestyle."
    },
    "tags": {
      "description": "Free-form tags for filtering and search.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "source": {
      "type": "object",
      "properties": {
        "heist_slug": {
          "description": "Source Heist slug — e.g. \"adscript\", \"hooks\", \"creative-director\".",
          "type": "string"
        },
        "session_id": {
          "description": "Optional source session id.",
          "type": "string"
        },
        "message_id": {
          "description": "Optional source message id (for highlight-from-chat saves).",
          "type": "string"
        },
        "pattern": {
          "type": "string",
          "enum": [
            "direct",
            "highlight",
            "tool",
            "document"
          ],
          "description": "How the save was created. `direct` for explicit save action."
        }
      },
      "required": [
        "pattern"
      ],
      "description": "Save attribution."
    },
    "brand_id": {
      "description": "Brand the asset is for. Resolved from brief_id when omitted.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "brief_id": {
      "description": "PowerSource (brief) the asset was generated against.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "parent_id": {
      "description": "Parent asset id for variations grouped under one save set.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "title": {
      "type": "string",
      "description": "Card title — what shows in /assets."
    },
    "body_text": {
      "description": "Primary text body for STRATEGY / IDEAS / COPY saves.",
      "type": "string"
    },
    "body_html": {
      "description": "Rich-text body where the asset carries structured markup.",
      "type": "string"
    },
    "media_url": {
      "description": "Direct media URL for VISUALS / MOTION (external host).",
      "type": "string",
      "format": "uri"
    },
    "media_storage_path": {
      "description": "Storage path inside the private `saved-assets` bucket. Obtain via the /api/saved-assets/upload-url route (REST only; no MCP upload tool yet).",
      "type": "string"
    },
    "thumb_url": {
      "description": "Card thumbnail URL.",
      "type": "string",
      "format": "uri"
    },
    "metadata": {
      "description": "Type-specific bag — duration, image dimensions, model used, beat count, etc.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "category",
    "format",
    "source",
    "title"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

asset_id

string

required

Asset to delete. Get from list_saved_assets.

Raw schema

{
  "type": "object",
  "properties": {
    "asset_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Asset to delete. Get from list_saved_assets."
    }
  },
  "required": [
    "asset_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

asset_id	string	required	Asset to favorite or unfavorite.
is_favorite	boolean	required	true to favorite, false to unfavorite. favorited_at is set/cleared in lockstep.

Raw schema

{
  "type": "object",
  "properties": {
    "asset_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Asset to favorite or unfavorite."
    },
    "is_favorite": {
      "type": "boolean",
      "description": "true to favorite, false to unfavorite. favorited_at is set/cleared in lockstep."
    }
  },
  "required": [
    "asset_id",
    "is_favorite"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

powersource_id

string

required

Strategy (PowerSource / brief) id. Get from list_strategies. Returns the buyer-decoder archetype plus up to 3 primary_audience segments.

Raw schema

{
  "type": "object",
  "properties": {
    "powersource_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Strategy (PowerSource / brief) id. Get from list_strategies. Returns the buyer-decoder archetype plus up to 3 primary_audience segments."
    }
  },
  "required": [
    "powersource_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters2

powersource_id	string	required	Strategy (PowerSource / brief) id. Get from list_strategies. Returns the full brand-merged bundle — buyer profile, 12 behavioral tensions, angles, narrative, tone of voice, selling points, CTAs, proof, brand story, homepage data, offering. Same shape as get_powersource(data) but keyed by powersource_id (no job_id needed).
include_archived	boolean	optional	Include archived strategies. Default false (archived strategies are excluded from agent reads — same default as list_strategies).

Raw schema

{
  "type": "object",
  "properties": {
    "powersource_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Strategy (PowerSource / brief) id. Get from list_strategies. Returns the full brand-merged bundle — buyer profile, 12 behavioral tensions, angles, narrative, tone of voice, selling points, CTAs, proof, brand story, homepage data, offering. Same shape as get_powersource(data) but keyed by powersource_id (no job_id needed)."
    },
    "include_archived": {
      "description": "Include archived strategies. Default false (archived strategies are excluded from agent reads — same default as list_strategies).",
      "type": "boolean"
    }
  },
  "required": [
    "powersource_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

powersource_id

string

required

Strategy (PowerSource / brief) id. Get from list_strategies. Returns the synthesized tone-of-voice (at most one entry today; shape is list-stable for future multi-tone bundles).

Raw schema

{
  "type": "object",
  "properties": {
    "powersource_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Strategy (PowerSource / brief) id. Get from list_strategies. Returns the synthesized tone-of-voice (at most one entry today; shape is list-stable for future multi-tone bundles)."
    }
  },
  "required": [
    "powersource_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

brand_id	string	optional	Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.
only_workspace	boolean	optional	When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.
only_official	boolean	optional	When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.
limit	integer	optional	Page size. Default 24, max 100.
offset	integer	optional	Offset for paging through results. Default 0.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "description": "Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "only_workspace": {
      "description": "When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.",
      "type": "boolean"
    },
    "only_official": {
      "description": "When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.",
      "type": "boolean"
    },
    "limit": {
      "description": "Page size. Default 24, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Offset for paging through results. Default 0.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

string

required

Preset id. Discover ids by calling the matching list_<type>_presets first.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Preset id. Discover ids by calling the matching list_<type>_presets first."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_visual_preset_presets

Heista-curated visual heists (style DNA + photography presets). Official-only today; workspace-saved presets are a future surface. Read-only, free. Filter scope with only_workspace / only_official (mutually exclusive — same toggle as the in-app library lens). Page with limit + offset.

Parameters5

brand_id	string	optional	Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.
only_workspace	boolean	optional	When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.
only_official	boolean	optional	When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.
limit	integer	optional	Page size. Default 24, max 100.
offset	integer	optional	Offset for paging through results. Default 0.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "description": "Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "only_workspace": {
      "description": "When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.",
      "type": "boolean"
    },
    "only_official": {
      "description": "When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.",
      "type": "boolean"
    },
    "limit": {
      "description": "Page size. Default 24, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Offset for paging through results. Default 0.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

string

required

Preset id. Discover ids by calling the matching list_<type>_presets first.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Preset id. Discover ids by calling the matching list_<type>_presets first."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

brand_id	string	optional	Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.
only_workspace	boolean	optional	When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.
only_official	boolean	optional	When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.
limit	integer	optional	Page size. Default 24, max 100.
offset	integer	optional	Offset for paging through results. Default 0.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "description": "Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "only_workspace": {
      "description": "When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.",
      "type": "boolean"
    },
    "only_official": {
      "description": "When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.",
      "type": "boolean"
    },
    "limit": {
      "description": "Page size. Default 24, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Offset for paging through results. Default 0.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

string

required

Preset id. Discover ids by calling the matching list_<type>_presets first.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Preset id. Discover ids by calling the matching list_<type>_presets first."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

brand_id	string	optional	Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.
only_workspace	boolean	optional	When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.
only_official	boolean	optional	When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.
limit	integer	optional	Page size. Default 24, max 100.
offset	integer	optional	Offset for paging through results. Default 0.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "description": "Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "only_workspace": {
      "description": "When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.",
      "type": "boolean"
    },
    "only_official": {
      "description": "When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.",
      "type": "boolean"
    },
    "limit": {
      "description": "Page size. Default 24, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Offset for paging through results. Default 0.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

string

required

Preset id. Discover ids by calling the matching list_<type>_presets first.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Preset id. Discover ids by calling the matching list_<type>_presets first."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

brand_id	string	optional	Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.
only_workspace	boolean	optional	When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.
only_official	boolean	optional	When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.
limit	integer	optional	Page size. Default 24, max 100.
offset	integer	optional	Offset for paging through results. Default 0.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "description": "Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "only_workspace": {
      "description": "When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.",
      "type": "boolean"
    },
    "only_official": {
      "description": "When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.",
      "type": "boolean"
    },
    "limit": {
      "description": "Page size. Default 24, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Offset for paging through results. Default 0.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

string

required

Preset id. Discover ids by calling the matching list_<type>_presets first.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Preset id. Discover ids by calling the matching list_<type>_presets first."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

brand_id	string	optional	Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.
only_workspace	boolean	optional	When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.
only_official	boolean	optional	When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.
limit	integer	optional	Page size. Default 24, max 100.
offset	integer	optional	Offset for paging through results. Default 0.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "description": "Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "only_workspace": {
      "description": "When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.",
      "type": "boolean"
    },
    "only_official": {
      "description": "When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.",
      "type": "boolean"
    },
    "limit": {
      "description": "Page size. Default 24, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Offset for paging through results. Default 0.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

string

required

Preset id. Discover ids by calling the matching list_<type>_presets first.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Preset id. Discover ids by calling the matching list_<type>_presets first."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

brand_id	string	optional	Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.
only_workspace	boolean	optional	When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.
only_official	boolean	optional	When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.
limit	integer	optional	Page size. Default 24, max 100.
offset	integer	optional	Offset for paging through results. Default 0.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "description": "Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "only_workspace": {
      "description": "When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.",
      "type": "boolean"
    },
    "only_official": {
      "description": "When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.",
      "type": "boolean"
    },
    "limit": {
      "description": "Page size. Default 24, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Offset for paging through results. Default 0.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

string

required

Preset id. Discover ids by calling the matching list_<type>_presets first.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Preset id. Discover ids by calling the matching list_<type>_presets first."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

brand_id	string	optional	Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.
only_workspace	boolean	optional	When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.
only_official	boolean	optional	When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.
limit	integer	optional	Page size. Default 24, max 100.
offset	integer	optional	Offset for paging through results. Default 0.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "description": "Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "only_workspace": {
      "description": "When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.",
      "type": "boolean"
    },
    "only_official": {
      "description": "When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.",
      "type": "boolean"
    },
    "limit": {
      "description": "Page size. Default 24, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Offset for paging through results. Default 0.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

string

required

Preset id. Discover ids by calling the matching list_<type>_presets first.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Preset id. Discover ids by calling the matching list_<type>_presets first."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

brand_id	string	optional	Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.
only_workspace	boolean	optional	When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.
only_official	boolean	optional	When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.
limit	integer	optional	Page size. Default 24, max 100.
offset	integer	optional	Offset for paging through results. Default 0.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "description": "Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "only_workspace": {
      "description": "When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.",
      "type": "boolean"
    },
    "only_official": {
      "description": "When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.",
      "type": "boolean"
    },
    "limit": {
      "description": "Page size. Default 24, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Offset for paging through results. Default 0.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

string

required

Preset id. Discover ids by calling the matching list_<type>_presets first.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Preset id. Discover ids by calling the matching list_<type>_presets first."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters5

brand_id	string	optional	Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.
only_workspace	boolean	optional	When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.
only_official	boolean	optional	When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.
limit	integer	optional	Page size. Default 24, max 100.
offset	integer	optional	Offset for paging through results. Default 0.

Raw schema

{
  "type": "object",
  "properties": {
    "brand_id": {
      "description": "Optional brand_id to scope workspace presets to. Get from list_brands. Official presets are not brand-scoped and are unaffected by this filter.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "only_workspace": {
      "description": "When true, hide Heista-curated (official) presets and only return workspace (user-created) presets. Mutually exclusive with only_official.",
      "type": "boolean"
    },
    "only_official": {
      "description": "When true, hide workspace (user-created) presets and only return Heista-curated (official) presets. Mutually exclusive with only_workspace.",
      "type": "boolean"
    },
    "limit": {
      "description": "Page size. Default 24, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "description": "Offset for paging through results. Default 0.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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.

Parameters1

string

required

Preset id. Discover ids by calling the matching list_<type>_presets first.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Preset id. Discover ids by calling the matching list_<type>_presets first."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md5 KBView on GitHub

Heista MCP

The Heista MCP server. Decode any video ad. Load any brand. Generate scripts. From inside Claude, ChatGPT, Cursor, VS Code, and any other MCP-compatible client.

Endpoint: https://www.heista.co/api/mcp/mcp Transport: Streamable HTTP (MCP protocol 2025-03-26) Auth: OAuth 2.1 (preferred) or API key (Authorization: Bearer hst_live_*) Status: Live

What you can do

Tool	What it does	Cost
`decode_ad`	Decode any video ad URL into structural formula, hooks, psychology, visual playbook	$0.15 (≤60s) / $0.20 (61–120s)
`get_decode`	Poll for decode result	Free
`create_powersource_url`	Load a brand from a website URL	$1.00
`create_powersource_docs`	Load a brand from internal documents (PDF, DOCX, briefs)	$1.00
`create_powersource_full`	Load a brand from URL + documents combined	$2.00
`get_powersource`	Poll for brand load result	Free
`generate_adscript`	Generate ad scripts from a decoded ad or formula, in any brand's voice	~$0.02–$0.05 per script
`get_hook_intelligence`	Read proven hook patterns from the decoded corpus	Free
`adformula_intelligence`	Read clustered ad formulas from decoded winners	Free
`decoder_intelligence`	Read decoded ads from the corpus	Free
`check_balance`	Check your account balance and monthly usage	Free

Same-domain re-runs of create_powersource_* by the same org are free. Decodes already in your library are free. Failed runs cost nothing.

Full reference, schemas, examples: heista.co/docs.

Install

Claude Code

bash

claude mcp add heista https://www.heista.co/api/mcp/mcp

Or install via plugin marketplace:

bash

/plugin marketplace add Heista-co/claude-code-skills
/plugin install heista-decode@heista-skills

Per-client snippets: clients/.

Authentication

OAuth 2.1 is the default. First call returns 401 + WWW-Authenticate: Bearer with RFC 9728 Protected Resource Metadata. MCP clients follow the chain automatically and prompt the user to sign in.

For headless / server-to-server use, generate an API key at heista.co/api-console/keys and pass it as Authorization: Bearer hst_live_.... Keys are SHA-256 hashed at rest, shown in plaintext once, scoped per key, and capped per day/month.

Scopes:

mcp:account — balance, decode/powersource polling
mcp:intelligence — free corpus reads
mcp:tools — paid generation (decode, powersource, adscript)

mcp:tools is elevated via WWW-Authenticate scope=mcp:tools on first paid call.

Pricing

Pay as you go, no subscription required. All paid calls reserve the maximum cost up front and refund any excess after.

Credit packs (1 credit = 1¢ USD):

Pack	Price	Credits	Decode estimate
Starter	$10	1,000	~100 decodes
Builder ⭐	$50	5,000	~500 decodes
Scale	$100	10,000	~1,000 decodes
Enterprise	$250	25,000	~2,500 decodes

Buy at heista.co/api-console/billing.

Spending caps: set hourly / daily / monthly caps per organization and per key from heista.co/api-console/limits. The server enforces the cap before any compute runs.

Account

A Heista account is required for paid tools. The free intelligence reads work after OAuth sign-in.

Reference

Resource	Link
Full API & MCP docs	heista.co/docs
OpenAPI spec	heista.co/openapi.yaml
Tool schemas (this repo)	`tools/`
Worked examples	`examples/`
Per-client install	`clients/`
Registry manifest	`server.json`
OAuth metadata	/.well-known/oauth-protected-resource
Claude Code skills	github.com/Heista-co/claude-code-skills
Status	heista.co
Support	support@heista.co

License

Docs in this repo are MIT-licensed (see LICENSE). The Heista MCP server itself runs under heista.co/terms.

Install

Tools (76)

decode_adget_decodecreate_powersource_urlget_powersourcecreate_powersource_docscreate_powersource_fullcheck_balanceget_hook_intelligence

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://www.heista.co/api/mcp/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "api": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.heista.co/api/mcp/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.