Motion Creative Analytics

Call this FIRST before any workspace-scoped tool. Returns the authenticated user's organizations and workspaces. Use the returned workspaceId to call all other tools. If the user has exactly one workspace, defaultWorkspaceId is set automatically. If multiple workspaces exist, the user will be prompted to select one.

Lists competitor brands the workspace is tracking. Input: required `workspaceId` and optional `brandIds` to narrow to a specific competitor set. Returns each competitor with a `brandId` reference suitable for further brand intelligence lookups.

Returns the workspace's own `brandId` — a reference, not full brand details. Input: required `workspaceId`. The returned `brandId` can then be passed to `get_inspo_brand_context` for positioning, voice, and visual identity, or included in `brandIds` on `get_inspo_creatives` to pull the workspace's own inspo creatives.

Retrieves creative performance insights (your own ads) for a workspace. Input: required `organizationId`, `workspaceId`, and `insightType`, plus optional date range (`datePreset` or `startDate`/`endDate`), metric expansion (`insightGroups`, `tableKPIs`, `includeGlossary`, `includeEntityCategoryValues`, `includeCreativeUrls`, `withAggregatedInsights`, `includeNorthbeam`), attribution overrides (`clickAttributionWindow`, `viewAttributionWindow`), and `groupBy` ('creative' default; pass 'adId' for ad-level rows when the user wants to compare the same creative across ads, ad sets, or campaigns). The v3 payload returns report metadata under `data.data`, with ranked rows at `data.data.insightsResult.data.insights`. The first response includes `goalMetric` (the workspace's preferred efficiency metric) and `spendThreshold` (minimum spend for statistical significance); `customConversions` lives at `data.data.insightsResult.data.customConversions` and is used to build `tableKPIs` keys for custom conversion analysis. Default response is lean: only `defaultKpiMetrics` (spend, cpm, ctr, thumbstop_ratio, video retention, etc.) per ranked insight. Set `includeCreativeUrls` to true when output will be visual (HTML reports, comparisons, briefs) to embed creative pubURLs directly. Set `includeNorthbeam` only with `groupBy: 'adId'` or `groupBy: 'name'`. When `includeGlossary` is enabled, glossary metadata is compacted by hoisting category definitions into `data.data.glossarySchema` and rewriting each ranked insight glossary to an internalName -> string[] map. Every ranked insight includes the full entity hierarchy under `ad` — `adId`, `adName`, `adsetId`, `adsetName`, `campaignId`, `campaignName` — so a single creative asset that runs across multiple ads, ad sets, and campaigns can be compared across contexts. If report generation is still in progress, the tool returns `status: 'waiting'` with `pollAfterMs`; call again with identical params.

Returns ad performance broken down by age and gender demographics for a workspace. Resolve workspaceId via get_auth_context first. This is the audience layer — it answers WHO responds to your ads. Always pair with get_creative_insights(SPEND) to interpret demographic signals. Call for: audience/persona/targeting questions, stakeholder reports, adaptation tasks, concept generation, and production planning. A segment with high thumbstop but zero ROAS is a funnel problem, not a creative problem. A segment with low spend but strong efficiency is an underexploited opportunity.

Fetches a compact AI summary for a specific creative. Resolve workspaceId via get_auth_context first. Use this after get_creative_insights or get_inspo_creatives when the user explicitly asks for more detail on one specific ad and you need more context than metrics, copy, or transcript alone can provide. Returns the AI-detected ad format, a plain-language summary of what the ad is about, the strongest available hook or headline, and detected CTAs in a compact inline payload. Prefer one creative at a time; small comparison sets are okay, but this is a drill-in tool, not a broad discovery tool. If the summary is still generating, the tool returns waiting and should be polled until complete.

Fetches the spoken transcript for a video creative. Only works for video creatives — set `creativeFormat` to "video". Requires `workspaceId`, `creativeEntityId`, and `creativeOrigin` (both entity fields are available on rows returned by get_creative_insights or get_inspo_creatives). The first 1-3 seconds of the transcript is the hook, the most critical element for creative performance.

Returns the workspace's glossary taxonomy — categories and their allowed tag values. Resolve workspaceId via get_auth_context first. This is the creative taxonomy layer — when cross-referenced with performance data from get_creative_insights (use includeGlossary: true), it enables pattern-level insights: which categories are scaling, which have the best efficiency by the workspace goalMetric, what combinations appear in winners but not losers, and what hasn't been tried yet (coverage gaps = creative opportunities). Use categoryNames to narrow to specific categories, customOnly to see only user-defined categories, and includeCreativeIds: true to map tagged creatives back to performance data. Also use to validate tag values before filtering — e.g., confirm "UGC" is a valid tag rather than guessing.

Returns the user's saved reports. Resolve workspaceId via get_auth_context first. Two modes: (1) Omit reportId to list all reports — returns lean metadata (name, type, platform, date range, groupBy, reportUrl). (2) Provide reportId to get the full report configuration — includes reportUrl, filters, attribution selection (standard click/view windows or incrementalityAttribution: true), metrics, comparison settings, and all saved parameters. Use the returned reportUrl when linking to the report; it is null when Motion has no report-detail route for that type. Use the full config to understand what the report tracks, then call get_creative_insights with matching parameters (datePreset, groupBy, filters) to fetch the actual performance data.

Retrieves rich Inspo brand context for a brand — the strategic foundation layer. Returns brand foundations (positioning, voice, tone, messaging angles), product information, and customer voice analysis for the given `brandId`. When `contextData` is null, inspect `reason` to decide how to proceed: `brand_not_found` (no brand matches the provided brandId) or `not_generated` (no context exists for this brand in either the new or legacy storage). Requires `workspaceId` for authorization.

Search for brands by name or domain. Input: `query` (the search string) and `workspaceId` for authorization, plus optional `verbose` (default false) to include full per-brand catalog fields. Returns matching brand records each with an `id`, `name`, and optional `domain`, `logo`, `type`, and `industry`. Default response omits heavy catalog fields (`visualFormats`, `topLandingPages`) — pass `verbose: true` or call `get_brand_by_domain` for full detail.

Retrieves Inspo creatives for one or more brands. Returns an array of brand entries shaped like `{ id, brandDetails, creatives }`, not a brandId-keyed map. Input: `brandIds` (required) plus optional `limit` (default 50, max 1000), `launchDate` filter, `status`, `sort`, and `withGlossary`. Returns creative metadata and ad copy but NO performance metrics — ad libraries do not include spend data, so results represent competitor bets, not measured performance. Set `withGlossary=true` only when you need Motion glossary tags.