Update to Supermetrics Marketing Agent

{
  "description": "How to query live marketing data through Supermetrics without failed queries — discovery, report types, field IDs, date ranges, filters and reading results — for Google Ads, Meta Ads, GA4, LinkedIn Ads, TikTok Ads, Microsoft Advertising, Instagram, Shopify, HubSpot, Search Console and every other connected source. Use before any data_query, for cross-channel or blended questions, and whenever a query errors or returns no data.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 248
    },
    {
      "relative_path": "assets/icon-small.png",
      "size_in_bytes": 2921
    },
    {
      "relative_path": "references/google-ads.md",
      "size_in_bytes": 10204
    },
    {
      "relative_path": "references/google-analytics-4.md",
      "size_in_bytes": 10171
    },
    {
      "relative_path": "references/instagram-insights.md",
      "size_in_bytes": 11131
    },
    {
      "relative_path": "references/linkedin-ads.md",
      "size_in_bytes": 11619
    },
    {
      "relative_path": "references/meta-ads.md",
      "size_in_bytes": 12098
    },
    {
      "relative_path": "references/microsoft-ads.md",
      "size_in_bytes": 10764
    },
    {
      "relative_path": "references/tiktok-ads.md",
      "size_in_bytes": 12261
    }
  ],
  "name": "marketing-data-queries",
  "skill_md_contents": "---\nname: marketing-data-queries\ndescription: How to query live marketing data through Supermetrics without failed queries — discovery, report types, field IDs, date ranges, filters and reading results — for Google Ads, Meta Ads, GA4, LinkedIn Ads, TikTok Ads, Microsoft Advertising, Instagram, Shopify, HubSpot, Search Console and every other connected source. Use before any data_query, for cross-channel or blended questions, and whenever a query errors or returns no data.\n---\n\n# Querying marketing data with Supermetrics\n\nNever answer a performance question from memory. Supermetrics returns live data — query it.\n\n\n## Platform references\n\nBefore querying one of these platforms, read its reference file for field IDs, report types, combinations that fail and data-freshness lags:\n\n| Platform | Reference |\n|---|---|\n| Google Ads (`AW`) | [references/google-ads.md](references/google-ads.md) |\n| Meta Ads (`FA`) | [references/meta-ads.md](references/meta-ads.md) |\n| Google Analytics 4 (`GAWA`) | [references/google-analytics-4.md](references/google-analytics-4.md) |\n| LinkedIn Ads (`LIA`) | [references/linkedin-ads.md](references/linkedin-ads.md) |\n| TikTok Ads (`TIK`) | [references/tiktok-ads.md](references/tiktok-ads.md) |\n| Microsoft Advertising (`AC`) | [references/microsoft-ads.md](references/microsoft-ads.md) |\n| Instagram Insights (`IGI`) | [references/instagram-insights.md](references/instagram-insights.md) |\n\nFor any other source, use the workflow below with `field_discovery`.\n\n## The workflow\n\nFollow these steps in order. Skipping discovery is the most common cause of failed queries.\n\n1. **`data_source_discovery()`** — list sources and their auth status. Pick the one the\n   user means. If they say \"Facebook\" or \"Meta\", that is `FA`; \"Google Ads\" is `AW`;\n   \"GA4\" is `GAWA`.\n2. **`data_source_discovery(ds_id=X)`** — read that source's configuration before\n   querying. It tells you what the next steps must be:\n   - `has_account_list: true` → call `accounts_discovery(ds_id=X)` for account IDs.\n   - `has_report_type_selection: true` → choose a `report_type` and pass it in `settings`.\n   - `has_fields: true` → call `field_discovery(ds_id=X)` to get valid field IDs.\n   - `is_date_range_required: true` → set a date range (nearly always true).\n3. **`field_discovery(ds_id=X, filter=\"...\")`** — filter rather than dumping every field.\n   `filter=\"cost,click,conversion\"` is far more useful than the full catalogue.\n4. **`data_query(...)`** — dimensions before metrics in `fields`. All fields must belong\n   to the same report type.\n5. **`get_async_query_results(schedule_id=...)`** — if the query returns a schedule ID\n   instead of rows, poll immediately and keep polling until `completed`.\n\n## Business context\n\nBefore analyzing a specific account, call `manage_business_context` with `action=\"get\"`\nand the `ds_id` (plus `account_id` where relevant). Teams store reporting conventions\nthere — which campaigns to exclude, which attribution window to use, how to segment.\nApplying them is the difference between a correct answer and a plausible one.\n\nIf the user states a durable preference mid-conversation (\"always exclude brand\ncampaigns\", \"we report in EUR\"), offer to save it with `action=\"save\"`.\n\n## Writing good queries\n\n- **Dates**: prefer relative ranges (`last_30_days`, `last_month`, `this_month_inc`).\n  For anything relative to \"now\", call `get_today` first — do not assume the date.\n- **Comparisons**: `compare_type=\"prev_range\"` or `\"prev_year\"` answers \"how does that\n  compare?\" in one query instead of two. Other values: `prev_year_weekday`, or `custom` with\n  `compare_start_date`/`compare_end_date`. `compare_show` picks `perc_change` (default),\n  `abs_change` or `value`.\n- **Filters**: `filters=\"country == US AND clicks > 100\"`. Operators include `==`, `!=`,\n  `>`, `>=`, `=@` (contains), `=~` (regex), `[]` (in list).\n- **Row limits**: default is 1000. Raise `max_rows` for long date ranges broken out by day.\n\n## Reading results\n\nRows come back as a 2D array: row 0 is display headers, rows 1+ are data. Map columns by\n`requested_field_ids`, **not** by the row-0 labels — the labels are human-readable names\nthat differ from field IDs (`screenPageViews` displays as \"Views\"), so matching on labels\nsilently reads the wrong column.\n\n**Check `canonical_field_ids` too.** Supermetrics resolves loose field names through an alias\nlayer, so a name you guessed can succeed while quietly returning a *different* metric instead of\nerroring — asking Meta Ads for `purchases` returns `action_omni_purchase` (web, app and in-store),\nnot website purchases. When `canonical_field_ids` is present and differs from what you requested,\nreport the metric that actually came back.\n\nValues may be strings. Parse numbers before arithmetic. An empty cell is `null`, not zero — say\n\"no data\" rather than reporting it as a zero.\n\nIf the response carries a `currency_recommendation`, the monetary columns have no currency attached.\nAdd the currency dimension it names before stating an amount.\n\n## Interpreting, not just reporting\n\nA table is not an answer. After retrieving data:\n\n- Lead with what changed and why it matters, not with the numbers.\n- Compare against a baseline — prior period, prior year, or the account average.\n- Flag anomalies: sudden CPA moves, campaigns with spend but no conversions, sources\n  whose data ends before the requested range (often a broken connection, not a real zero).\n- Say when a number is unreliable — GA4 sampling, incomplete last day, thresholding.\n\n## When something fails\n\nCall `supermetrics_guide` with the matching `mode` before escalating: `no_data`,\n`data_discrepancies`, `ga4_data`, `query_errors`, `reconnect`, `prioritized_accounts`,\n`quotas_and_limits`. Most failures are configuration, not bugs, and the guide resolves\nthem without a support ticket.\n"
}