Analyze any ad creative (image, video, carousel, landing page, email) and return structured classification across 21 dimensions: media type, asset type, visual format, visual style, talent and talent demographics, hook type, messaging angle, audience, CTA, emotion, audio type, voiceover tone, seasonality, offer type, aspect ratio, duration, and more. Also generates standardized naming conventions. Provide one of: file_path, url, or html_content.

Get Creative Tagger taxonomy v2's 15 controlled dimensions, one derived/open aspect-ratio dimension, and two dynamic, brand-specific dimensions. The package ships a versioned vocabulary because the API schema does not expose enums for every classification field. Use this before analyze_creative when you want to know the vocabulary the system understands. Taxonomy v2: media type (the auto-detected format — static image, video, carousel), asset type (production class), and visual format (execution style) are three separate dimensions; 'Static Image' and 'Carousel' are media types, not visual_format values.

List the authenticated user's workspaces and their exact brand_name scope. Call this first, then reuse one returned brand_name on every library, status, report, and strategist request.

Browse the authenticated user's saved analysis library (memory). Every analyze_creative call is automatically saved. Use this to recall what has been analyzed before — search by filename, hook, angle, emotion, CTA, talent, offer, audio, season, or format, then sort by recency or joined performance (spend, reach, frequency, ROAS, CTR, CPM, CPA).

Get pattern insights across the user's entire library: which hooks, angles, creative types, emotions they over- or under-index on. Returns top values per dimension with percentages plus rule-based diversification insights. Use this for portfolio analysis before recommending what to make next.

Get the full analysis result for a single saved library item by ID. Use after list_library when you need the complete 21-dimension classification (list_library returns a summary; this returns the full JSON).

Ask the Creative Strategist a question, grounded in the user's library + brand context. The strategist auto-loads patterns from prior analyses and any saved brand voice/audience/anti-patterns for the brand, then answers with concrete creative recommendations using taxonomy values. Use this for open-ended strategic questions ('what should I test next', 'how should I approach Q4', 'what kind of UGC would work for this audience').

Identify gaps in the user's creative library for a given brand and propose concrete next creatives that fill them. Surfaces concentration risk (e.g., 78% UGC TalkHead) and recommends under-represented hook types, messaging angles, creative types. Returns JSON with gap analysis + ready-to-produce briefs.

Retrieve the saved brand context for a brand: voice, target audience, top performers, anti-patterns, and notes. Strategist tools auto-include this; this tool exposes the raw stored context.

Create or update brand context for a brand. Stored per-user. This is the brand's long-term memory — voice, audience, what works, what to avoid. Future strategist and brief calls automatically include this context. Upserts on (user, brand_name).

Retrieve the brand-custom taxonomy for a brand: custom values, aliases, and entities such as founder, recurring creators, products, offers, customer segments, ICPs, and campaign labels. Standard taxonomy still lives in attributes; this is the brand-specific extension layer.

Create or update one brand-specific allowed value for an existing Creative Tagger dimension, with aliases. Example: dimension=talent, value='Stephen Lavender / Founder', aliases=['Stephen','founder'].

Delete one brand-specific taxonomy value by brand, dimension, and canonical value. Use this to prune stale founders, segments, offers, or internal labels from Brand Taxonomy Studio.

Create or update a prompt/entity-based brand entity to recognize in creative analysis: founder, creator, customer, spokesperson, product, offer, customer_segment, icp, or campaign_label.

Delete one brand entity by brand, entity_type, and canonical name. Useful when a creator, product, offer, customer segment, ICP, or campaign label should no longer be recognized for the brand.

List every variable available in saved naming templates, including standard taxonomy fields plus brand-custom variables like founder, product, offer, customer_segment, icp, and campaign_label.

List the authenticated user's saved naming templates. Templates are applied automatically to future analyze_creative results.

Create or update a saved naming template using {variable} placeholders. Supports standard taxonomy fields and brand-custom variables.

Delete a saved naming template by name.

Preview a naming template with sample taxonomy values before saving it.

Check whether read-only Meta performance sync is connected for the authenticated user. Returns account id, scopes, read-only status, and latest sync metadata.

Trigger a read-only Meta ads performance sync for a brand. Syncs ad performance rows and reports summaries by standard and brand-custom taxonomy values. Supports explicit attribution/lookback windows so agents can match the buyer's Ads Manager view. Does not create campaigns or edit budgets.

Read the saved Meta performance memory for a brand without triggering a sync. Returns totals plus winners/losers by standard taxonomy and brand-custom taxonomy values, including explainable funnel_score signals for capture, hold, bring-to-site, and convert stages. Supports all_time, last_7_days, last_30_days, last_90_days, or custom date windows.

Return tag-level performance with significance gating and coverage gaps. Use this to find which taxonomy values are associated with stronger historical outcomes, which are under-observed, and which standard values have never been tried. Rows include ROAS, CTR, thumbstop, and funnel_score when performance memory exists. Supports the same date presets as the main performance summary.

Return Motion-style prebuilt creative reports for a brand: best hooks, landing pages, messaging angles, audiences, offers, CTAs, visual formats, and brand-custom values. Rows include ROAS, spend, CTR, thumbstop, and funnel_score when performance memory exists. Optional start_date/end_date (YYYY-MM-DD) scope the report window.

Read one workspace's observational Strategy matrix and decision queue. Defaults to a bounded concise response; use detailed only for an explicit deep dive. Treat cells as test hypotheses, not causal effects.

Read one workspace's current Brand Brain observations, conclusions, watchouts, audience signals, gaps, and agent_context. Validate associations with controlled tests before changing allocation. Audience filters use higher_observed_efficiency or lower_observed_efficiency.

Persist a reviewed get_brain_learnings slice as Brand Brain notes. Uses the same canonical audience filters; saving memory does not prove causality.

Export a bounded, prompt-ready context from get_brain_learnings, including follow-up Strategy and time-series queries and the same canonical audience filters.

Read one workspace's saved performance series for observational fatigue, trajectory, and data-coverage checks.

Export the bounded agent_context from get_performance_timeseries with its decision queue and data-quality warnings.

Create a custom performance report by selecting standard and/or brand taxonomy dimensions, then ranking the actual matched dimension combinations by ROAS, funnel_score, spend, CTR, or CPA. Use this when the user asks for a custom Motion-style view like hook x landing_page x offer_type, founder x hook, offer x audience, or custom segments. Optional start_date and end_date let an agent isolate a specific test window before explaining the winning combination. Rows can include parts and values so the agent can explain the winning combination.

List saved custom report definitions for a brand.

Save or update a reusable custom report definition for a brand. Use this when the user wants the same Motion-style combination view available later, such as hook_type x landing_page x offer_type, including custom report windows scoped to a specific test period or a richer dashboard preset with a saved view type, grouping, metric set, filters, sort, and metric preset.

Run a saved custom report definition by id.

Delete a saved custom report definition by id.

Legacy-named observational pre-flight. Compare a creative's tags with the brand's historical tag-level performance; this is not a forecast or causal estimate. Use the fit score and tag associations to form a one-variable controlled-test hypothesis with predeclared success and stop criteria. Pass an analysis_id or raw attributes.

Return saved age x gender delivery with account-relative higher and lower observed-return-per-spend bands. These are descriptive associations, not audience outcome or action verdicts. Supports report date presets like last_30_days or a custom start_date/end_date (YYYY-MM-DD) to scope the audience read to a specific performance window.

Return an agent-ready audience context payload from saved age x gender performance memory. Use this when another agent or workflow needs the higher and lower observed-efficiency bands, account totals, summary text, a prompt-ready descriptive review queue, and date-scoped mixed creative x audience strategy queries plus time-series follow-up queries without opening the dashboard.

Auto-build a brand's ENTIRE custom taxonomy from trends in its analyzed creative library — messaging themes, intended audiences, AND entities (products, founders, creators, offers, customer segments, campaign labels). Lets a brand get the full brand-custom layer with zero manual setup. Optionally persists everything into Brand Taxonomy Studio so future analyses, predictions, and naming templates use them.

Scan a competitor's ads from the Meta Ad Library and return classified results plus an aggregate strategy breakdown (top hook types, visual styles, CTAs, emotions, estimated spend). Provide page_id, page_name, or keyword. Returns ad metadata, full Creative Tagger analysis per ad, and strategy insights.

Return saved competitor Market scans/imports for the current workspace without re-running Meta Ad Library access. Useful for re-briefing past market reads, checking the latest tagged competitor patterns, or building strategy prompts from previously saved scans.

Generate V1-compatible standard, full, compact, and reporting naming convention strings from creative attributes. Use when you already have classified attributes (for example from analyze_creative) and need the same naming structure the API returns.