Supermetrics Marketing Agent

Store and retrieve durable business context — guidelines, policies, and preferences a team wants applied consistently and shared with all members. Context can cover reporting conventions, analysis rules, brand and tone, data governance, naming, plans, or account-specific preferences. Stored at three scopes, each read independently (a `get` returns one scope's context, not a merge): - **Team** — applies everywhere (e.g. "report currency in EUR"). - **Data source** — a specific platform (e.g. "for Meta, break out Advantage+ separately"). - **Account** — a specific account (e.g. "this client reports last-click only"). **Actions:** - `get` — Retrieve context by scope, chosen by the ids (no cascade): no ids → team-level; `ds_id` → that data source's level; `ds_id`+`account_id` → that account's level. `tags` filters by tag — a record matches if it carries **any** of the tags you pass (OR); commas are just separators, so `tags: ["a,b"]` and `["a","b"]` both match records tagged a or b — handy for fetching several clients at once (e.g. one client tag per client, then `["acme,globex"]`). Omit `tags` to read all entries at the scope, and **`tags` with no ids searches across all scopes**, so a tag lookup isn't confined to one level. Returned grouped as `team`/`data_source`/`account` (empty omitted); a single-source data-source list is keyed `data_source:<ds_id>` (e.g. `data_source:AW`). To assemble everything applicable to an account, read the levels separately — or rely on the discovery tools, which surface applicable context automatically. - `save` — Create/update at a scope; needs `context_text` and `tags` (a tag can't contain a comma). Tags identify the entry within a scope, so a scope can hold several entries (one per tag set): `mode: "replace"` (default) overwrites the entry with those tags, `mode: "append"` concatenates to it, and a different tag set is saved as a separate entry rather than overwriting. - `delete` — Remove the single entry identified by scope (`ds_id`/`account_id`) **and** `tags` — it targets that one tag set, never the others at the scope. Omit `tags` to remove the untagged entry. Irreversible, so confirm first. **When to save:** when the user shares a plan, guidelines, or SOP; states a durable preference ("for this client, always…"); or corrects your approach — offer to save it so it applies in future sessions. Distill the key, reusable rules — do not store documents verbatim — and tag them (e.g. "data-analysis", "targeting", "naming-conventions", "brand-visuals", "brand-language"). Tags are how you retrieve an entry later — use category tags, or, to group context the scope can't (an agency client that spans several accounts and platforms), the client's name: a team-level entry tagged with a client name that maps the client to its accounts is a good pattern. Avoid tags that merely restate the scope (a data-source entry's own data source, an account's own id). **When to read:** prefer what the discovery tools already surface — `data_source_discovery` and `accounts_discovery` include team- and data-source-level context in their responses, and a narrowed `accounts_discovery` (≤3 accounts) inlines an account's own context. When a discovery response surfaces a scope only as a tag list (its context was too large to inline), read the tags relevant to the action you're taking with `get`. Also call `get` for a scope a discovery response did not cover — e.g. an account you are about to act on that was not in a discovery result — or to re-read after you `save`. A discovery response also states when the team has no saved context yet, so don't call `get` merely to check whether any exists. Apply context when analysing data and making changes.

manage_business_context

Share live dashboards in Supermetrics Studio — self-contained pages that re-query the user's data on each view, so a shared link always shows current numbers. Before uploading, show a STATIC inline preview (data hard-coded, no smQuery), then confirm before uploading the LIVE smQuery version. smQuery and window.fetch work only inside Studio, so a preview using them renders empty in the chat — the inline preview must hard-code the data you already fetched, and the upload must fetch via smQuery (see the 'code' param), never the hard-coded preview. ALWAYS offer this upload after building a dashboard — it is how users discover Studio; do not just show the preview and stop. Skip the confirmation only when the user EXPLICITLY asked to publish (e.g. "put this in Studio and give me a link"). Actions: - 'upload': Upload a new dashboard or replace an existing one. Requires title, code, allowed_tools, allowed_accounts; description is optional. The code format (HTML or JSX) is detected automatically. - 'get': Retrieve a dashboard's source code and metadata by ID. Use this to load current code before editing. - 'edit': Apply targeted anchor-based patches to dashboard code. Call 'get' first to see the current code, then send patches. - 'changelog': View version history with change descriptions. Edit patch types (pick the smallest that fits): - region replace (PREFER for changing a section's logic/content): {"from": "// #region charts", "to": "// #endregion charts", "replace": "// #region charts\n<new code>\n// #endregion charts"} — replaces the WHOLE region from 'from' to 'to', anchor lines INCLUDED. Write the COMPLETE new block in 'replace' and reproduce the 'from' and 'to' marker lines inside it (normally unchanged) so they survive; omitting a marker deletes it. Restating an anchor does NOT duplicate it. 'from' must be unique; 'to' is the first match after it. - find/replace (small unique swap): {"find": "old text", "replace": "new text"} - after/insert (a NEW element): {"after": "anchor text", "insert": "new content"} - before/insert: {"before": "anchor text", "insert": "new content"} Modifiers (find/replace only): "nth": N (target Nth occurrence), "all": true (replace all). Patches are applied sequentially and atomically. Patchable code: When uploading, wrap each section in PAIRED region markers so edits can target them, and declare each variable/function inside the region that uses it: - HTML: <!-- #region header -->…<!-- #endregion header --> - CSS: /* #region kpi-cards */…/* #endregion kpi-cards */ - JS: // #region chart-init … // #endregion chart-init - Tag key elements with data-sm attributes: data-sm="kpi-spend", data-sm="filter-date" Each anchor must be unique in the code. Best practices: - Add a loading indicator (spinner or skeleton) while data is being fetched. - When it makes sense, add selectors (dropdowns, date pickers, toggles) that let viewers change query parameters such as date range, account, or metric. - Date controls: offer a genuinely flexible date range, not just a few fixed presets. smQuery's date_range_type accepts today, yesterday, this_month(_inc), last_month, this_year_inc, last_year(_inc), and the last_x_days / last_x_weeks_sun_sat / last_x_weeks_mon_sun / last_x_months / last_x_years families — substitute a number for x (e.g. last_90_days, last_3_months) and append _inc to include the current period. There is NO native quarter or year-to-date preset: deliver 'this/last quarter', 'year to date', and any viewer-picked custom range via date_range_type="custom" with start_date/end_date (YYYY-MM-DD) computed in the dashboard's own JS (derive the boundaries from new Date()). Prefer including a fully custom start/end picker alongside the presets. - Period comparison: when comparison is wanted, add ONE dashboard-wide comparison control and feed the SAME compare params into EVERY widget's smQuery — time-series charts too, not only scorecards. compare_type="prev_range" (previous period), "prev_year" (same period last year), "prev_year_weekday", or "custom" (with compare_start_date/compare_end_date, YYYY-MM-DD); compare_show="perc_change" (default), "abs_change", or "value". For a year-over-year time-series overlay, either use compare_type or issue a second smQuery for the prior period and plot it as an additional series. - Give each chart/table/KPI its own stable smQuery key (see the 'code' param) so rapidly changing a selector can't show stale data from a previous selection. - If an 'upload' response includes `code_warnings`, the board will render empty/wrong data or never refresh — fix the issue it names (a static board with no smQuery calls, or column mapping via requested_field_ids) and re-upload before sharing the board.

manage_dashboards

Manage your Supermetrics account: user and license info, team members and invites, data-source login links, subscription user assignment, and viewing or changing a data source prioritised (pinned) accounts with the cap and monthly change quota. Operations: get_info; invite_member; login_data_source (ds_id); add_user_to_subscription (license_id, user_ids); get_prioritised_accounts (ds_id); set_prioritised_accounts (ds_id, account_ids). Use get_info to find license_id and team member user_ids.

manage_user_and_team

Free marketing utilities: no Supermetrics subscription or connected data source needed. **Actions:** - utm_build: tag each of the urls with source/medium/campaign/term/content, correctly encoded (macros like {campaignid} kept), validated against your team's conventions. - utm_parse: audit the urls against your team's conventions and GA4 channel rules. - pagespeed_check: PageSpeed Insights for up to 10 urls (run in parallel; 30s-2min): scores, lab and field vitals, top fixes; detail="full" for every finding. Returns within ~45s; if checks are still running it returns status="running" and a job_id: poll with {"action":"pagespeed_check","job_id":...} about every 30s. Results are cached for 24h (cached=true, checked_at); pass refresh=true only after the page has changed. - link_check: follow up to 50 urls through redirects; do UTM and click-id params (gclid, fbclid...) reach the landing page, and at which hop are they lost. Also broken pages, loops, tagging mistakes. - web_vitals_trend: ~6 months of real-user LCP/INP/CLS/FCP/TTFB for up to 50 sites (bare domain) or pages. - safety_check: up to 50 urls and every host they redirect through: Web Risk malware/phishing flags, invalid or expiring certificates, domains expiring soon or registered in the last 30 days. - link_preview: how up to 50 urls render when shared on LinkedIn, Facebook, X and Slack; flags missing or small og:image, missing description, truncated titles. - email_dns: SPF, DKIM, DMARC, MX and BIMI for up to 50 domains (urls may be domains, emails or URLs). - char_limits: exact lengths of up to 200 texts against Google Ads, Meta, LinkedIn and X limits (counted as each platform counts). Use it whenever copy must fit a limit; do not count characters yourself. Google asset fields (path, long_headline, business_name, callout, sitelink_text, sitelink_description) are checked only when named in field. **Results:** every result has input (as sent), url, status (ok|warning|critical|unknown) and findings[] of {code, severity, message, suggestion?, ...extras}; unknown results carry error {code, message} (e.g. quota_exhausted, daily_limit, no_data, url_throttled). Each batch has a summary of counts. **UTM conventions** come from business context (tags='utm-conventions'). A JSON object is enforced; every key is optional; lists are exact, case-sensitive matches: {"approved_sources":[...],"approved_mediums":[...],"blocklist":{"utm_campaign":["test"]}, "regex":{"utm_campaign":"\d{4}"},"max_length":{"utm_campaign":60},"casing":"lowercase"|"as_is", "separator":"-"|"_","require_all_core":true} When utm_source is a known ad network (google, bing, facebook/instagram, tiktok, linkedin, snapchat, pinterest), utm_build returns network {medium, campaign_macro, id_macro, click_id} and both actions flag macros written in another network's syntax, which that network would leave unfilled. utm results report conventions_source: team (JSON enforced), team_free_text (returned as team_conventions for you to apply) or defaults (lowercase, hyphens).

marketing_utilities

Query data from Google Ads, Facebook Ads, Google Analytics, LinkedIn Ads, TikTok Ads, Microsoft Ads, Shopify, HubSpot, and 200+ other platforms. Use data_source_discovery, accounts_discovery and field_discovery first. Returns rows when completed; else pass schedule_id to get_async_query_results. Team- and data-source-level context arrives with data_source_discovery/accounts_discovery, and a narrowed accounts_discovery (≤3 accounts) inlines an account's own context — apply what you already have. Only when you are querying a specific account whose context you have not seen, read it first with manage_business_context (action 'get', ds_id + account_id) for reporting guidelines — e.g. which campaigns to exclude, how to segment data, preferred metrics. If the user specifies reporting preferences during the conversation (e.g. "exclude brand campaigns", "always break out Advantage+ separately", "for this client we only look at last-click attribution"), ask whether to save these as context for future sessions using manage_business_context with action 'save'.

data_query

Explain what Supermetrics can do, what's new, or how to fix a common problem. Use mode="tour" (the default) for what the user can do; mode="whats_new" for recent changes. Not for looking up data sources, accounts or fields. Call tour/whats_new at most once per conversation. TROUBLESHOOTING: when the user reports a common problem, fetch the matching guide and walk them through it before offering a support ticket. Connecting / access: connect_data_source (sign-in / "no accounts found"), google_connectors (GA4/Search Console/YouTube/etc. access), meta_instagram (Facebook/Instagram setup), microsoft_connectors (Microsoft Ads/Bing Webmaster), linkedin_connectors (Ads vs Company Pages), tiktok_connectors (Ads vs Organic), x_twitter_connectors (X Ads vs X Organic), amazon_connectors (Ads/DSP/Seller/Vendor), data_warehouse (BigQuery/Snowflake), reconnect (expired connection). Licensing and accounts: license_and_trials (LICENSE_NOT_FOUND / trial expired), data_source_on_plan (LICENSE_DATA_SOURCE_NOT_AVAILABLE), destination_on_plan (AI Chats destination missing), prioritized_accounts ("not a prioritised account"), manage_users_and_accounts (adding users/accounts and making a new account usable). Data and queries: no_data (empty results), data_discrepancies (numbers don't match the platform), ga4_data (GA4 sampling/thresholding/partial data), query_errors (date/field/account errors), quotas_and_limits (quota exceeded). Campaigns: write_access. Each returns steps the user can follow without Supermetrics staff.

supermetrics_guide