Update to Billy Grace Insights

{
  "name": "billy-grace-data-retrieval",
  "description": "Query Billy Grace marketing data: campaign performance, ROAS, CPA, spend, conversions, impressions, clicks, ad sets, channels, custom events, shopping product ads, and keyword performance. Load once per conversation before the first insights_query call, and whenever the user wants to compare campaigns, channels, or time periods. Do not use to interpret or explain numbers that have already been returned (use billy-grace-analysis), or to choose attribution models, modes, or windows (use billy-grace-attribution).\n",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 423
    }
  ],
  "skill_md_contents": "---\nname: billy-grace-data-retrieval\ndescription: >\n  Query Billy Grace marketing data: campaign performance, ROAS, CPA, spend,\n  conversions, impressions, clicks, ad sets, channels, custom events, shopping\n  product ads, and keyword performance. Load once per conversation before the\n  first insights_query call, and whenever the user wants to compare campaigns,\n  channels, or time periods. Do not use to interpret or explain numbers that\n  have already been returned (use billy-grace-analysis), or to choose\n  attribution models, modes, or windows (use billy-grace-attribution).\nmetadata:\n  author: Billy Grace\n  version: 2.1.0\n  mcp-server: billy-grace-insights-mcp\n---\n\n# Billy Grace Data Retrieval\n\nThis skill teaches you how to retrieve marketing performance data through the Billy Grace Insights MCP server. The server exposes five tools that work together in a discovery-then-query pattern across three datasets.\n\nAll attributed metrics in these datasets are built on identity-resolved customer journeys: Billy Grace's identity resolution engine stitches sessions from the same user across devices and browsers, so attribution reflects complete journeys rather than fragmented sessions (see the **billy-grace-attribution** skill for details).\n\n## Available datasets\n\n| MCP `table_name` | Use case |\n| ---------------- | -------- |\n| `marketing_performance` | Campaign and ad-level performance (default) |\n| `shopping_performance` | Product-level shopping ad performance (advertised products in feeds) |\n| `keyword_performance` | Keyword-level performance with full channel + attribution join |\n\n**Shopping vs sold products:** `shopping_performance` covers products **advertised** in shopping campaigns. Sold-product order data is a separate dataset not exposed by this MCP.\n\n## Available tools\n\n| Tool | Purpose |\n| ---- | ------- |\n| `get_client_id` | Resolve a display name (e.g. \"Acme Corp\") to a tenant `client_id`, or pass `%` to list all accessible clients |\n| `get_skills` | Load this and other Billy Grace skill content |\n| `get_table_schema` | Discover valid metrics, computed metrics, dimensions, and attribution options for a dataset |\n| `list_custom_events` | Discover conversion events with per-event attribution models and metrics |\n| `insights_query` | Fetch aggregated performance data with filters, grouping, and attribution settings |\n\n## Getting started\n\nWhen a user first connects the MCP or you have not yet established context, walk them through discovery:\n\n1. Resolve the account: if the user gives a display name, call `get_client_id`; if they already gave a `client_id`, use it directly.\n2. Call `get_table_schema(table_name=...)` to pick the dataset and valid fields.\n3. Call `list_custom_events(client_id)` to show available conversion events with per-event attribution and metrics.\n4. Call `insights_query` with validated parameters.\n\nThis ensures every subsequent query uses valid parameter values.\n\n## Standard workflow\n\nFor any data retrieval request, follow these steps:\n\n### Step 1: Pick the dataset\n\nCall `get_table_schema` for the relevant `table_name`:\n\n- **marketing_performance** — campaign/ad performance; supports UMM, LC, MTA; session_date and event_date modes.\n- **shopping_performance** — product ad performance; LC and MTA only; session_date and event_date modes.\n- **keyword_performance** — keyword performance with full join parity; LC and MTA only; **session_date mode only**. Always requires `customer_name` + `custom_event` (ev) filters.\n\n### Step 2: Identify required parameters\n\nEvery `insights_query` call needs:\n\n- **client_id**: tenant identifier from conversation context or `get_client_id`\n- **table_name**: dataset from step 1 (default `marketing_performance`)\n- **metrics**: from `get_table_schema` and `list_custom_events`\n- **start_date** / **end_date**: inclusive, ISO format `YYYY-MM-DD`\n- **custom_event**: from `list_custom_events`\n\nReuse validated values on follow-up questions — do not re-run discovery on every turn.\n\n### Step 3: Choose attribution settings\n\nConsult the **billy-grace-attribution** skill for guidance.\n\n| Parameter | Options | Default |\n| --------- | ------- | ------- |\n| `attribution_model` | `LC`, `MTA`, `UMM` (UMM pixel only) | `MTA` |\n| `attribution_mode` | `session_date`, `event_date` (keyword: session_date only) | `session_date` |\n| `attribution_window` | `1-day`, `7-day`, `30-day`, `unlimited` | `7-day` |\n\nPer-event `attribution_models` from `list_custom_events` guide event selection (UMM only when listed for that event).\n\n### Step 4: Add dimensions and filters\n\n- **dimensions**: columns to group by from `get_table_schema`\n- **dimension_filter_mapping**: `{\"dimension_name\": [\"value1\", \"value2\"]}`\n\n### Step 5: Call `insights_query`\n\nReturns rows with requested dimensions and SUM-aggregated metric values.\n\n## Example tool calls\n\n### Campaign performance by channel (pixel)\n\n```json\n{\n  \"client_id\": \"acme-corp\",\n  \"table_name\": \"marketing_performance\",\n  \"metrics\": [\"spend\", \"event_value\", \"number_of_events\", \"impressions\", \"clicks\"],\n  \"start_date\": \"2026-03-31\",\n  \"end_date\": \"2026-04-06\",\n  \"custom_event\": \"purchase\",\n  \"dimensions\": [\"source\"],\n  \"attribution_model\": \"MTA\",\n  \"attribution_mode\": \"session_date\",\n  \"attribution_window\": \"7-day\",\n  \"dimension_filter_mapping\": { \"is_integrated_channel\": [\"1\"] }\n}\n```\n\n### Shopping product performance\n\n```json\n{\n  \"client_id\": \"acme-corp\",\n  \"table_name\": \"shopping_performance\",\n  \"metrics\": [\"spend\", \"clicks\", \"impressions\", \"event_value\", \"number_of_events\"],\n  \"start_date\": \"2026-03-01\",\n  \"end_date\": \"2026-03-31\",\n  \"custom_event\": \"purchase\",\n  \"dimensions\": [\"product_name\", \"source\"],\n  \"dimension_filter_mapping\": { \"source\": [\"google\"] }\n}\n```\n\n### Keyword performance\n\n```json\n{\n  \"client_id\": \"acme-corp\",\n  \"table_name\": \"keyword_performance\",\n  \"metrics\": [\"spend\", \"clicks\", \"impressions\", \"sessions\", \"number_of_events\"],\n  \"start_date\": \"2026-03-01\",\n  \"end_date\": \"2026-03-31\",\n  \"custom_event\": \"order_completed\",\n  \"dimensions\": [\"keyword\", \"campaign_name\"],\n  \"attribution_model\": \"MTA\",\n  \"attribution_mode\": \"session_date\"\n}\n```\n\n## Computed metrics\n\n| Metric | Formula | When to use |\n| ------ | ------- | ----------- |\n| `roas` | `event_value / spend` | Revenue-generating events |\n| `cpa` | `spend / number_of_events` | Conversion-count events |\n| `conversion_rate` | `(number_of_events / sessions) * 100` | Session conversion share |\n| `cost_per_click` | `spend / clicks` | Click cost |\n\nUse `event_value` for revenue events and `number_of_events` for conversion-count events (see per-event `metrics` from `list_custom_events`).\n\n## Important data rules\n\n### Integrated channels and spend metrics\n\nAlways include `{\"is_integrated_channel\": [\"1\"]}` when querying spend-derived metrics on **marketing_performance** data. Shopping and keyword datasets are integrated-channel data by nature.\n\n### Keyword partitioning\n\nThe keyword table is partitioned on `customer_name` + `ev`. Always pass both `client_id` and `custom_event` — the server enforces this.\n\n### Data recency\n\nData is available through yesterday.\n\n## Error recovery\n\n- **Invalid metric/dimension**: call `get_table_schema` for the table_name, then retry.\n- **Invalid attribution**: check per-table attribution_models/modes from `get_table_schema`.\n- **Empty results**: verify client_id, custom_event, and date range.\n\n## Cross-skill references\n\n- **billy-grace-attribution** — choosing attribution model, mode, and window\n- **billy-grace-analysis** — interpreting results and marketing advice\n"
}