skills/billy-grace-data-retrieval/SKILL.md

---
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).
metadata:
  author: Billy Grace
  version: 2.1.0
  mcp-server: billy-grace-insights-mcp
---

# Billy Grace Data Retrieval

This 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.

All 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).

## Available datasets

| MCP `table_name` | Use case |
| ---------------- | -------- |
| `marketing_performance` | Campaign and ad-level performance (default) |
| `shopping_performance` | Product-level shopping ad performance (advertised products in feeds) |
| `keyword_performance` | Keyword-level performance with full channel + attribution join |

**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.

## Available tools

| Tool | Purpose |
| ---- | ------- |
| `get_client_id` | Resolve a display name (e.g. "Acme Corp") to a tenant `client_id`, or pass `%` to list all accessible clients |
| `get_skills` | Load this and other Billy Grace skill content |
| `get_table_schema` | Discover valid metrics, computed metrics, dimensions, and attribution options for a dataset |
| `list_custom_events` | Discover conversion events with per-event attribution models and metrics |
| `insights_query` | Fetch aggregated performance data with filters, grouping, and attribution settings |

## Getting started

When a user first connects the MCP or you have not yet established context, walk them through discovery:

1. Resolve the account: if the user gives a display name, call `get_client_id`; if they already gave a `client_id`, use it directly.
2. Call `get_table_schema(table_name=...)` to pick the dataset and valid fields.
3. Call `list_custom_events(client_id)` to show available conversion events with per-event attribution and metrics.
4. Call `insights_query` with validated parameters.

This ensures every subsequent query uses valid parameter values.

## Standard workflow

For any data retrieval request, follow these steps:

### Step 1: Pick the dataset

Call `get_table_schema` for the relevant `table_name`:

- **marketing_performance** — campaign/ad performance; supports UMM, LC, MTA; session_date and event_date modes.
- **shopping_performance** — product ad performance; LC and MTA only; session_date and event_date modes.
- **keyword_performance** — keyword performance with full join parity; LC and MTA only; **session_date mode only**. Always requires `customer_name` + `custom_event` (ev) filters.

### Step 2: Identify required parameters

Every `insights_query` call needs:

- **client_id**: tenant identifier from conversation context or `get_client_id`
- **table_name**: dataset from step 1 (default `marketing_performance`)
- **metrics**: from `get_table_schema` and `list_custom_events`
- **start_date** / **end_date**: inclusive, ISO format `YYYY-MM-DD`
- **custom_event**: from `list_custom_events`

Reuse validated values on follow-up questions — do not re-run discovery on every turn.

### Step 3: Choose attribution settings

Consult the **billy-grace-attribution** skill for guidance.

| Parameter | Options | Default |
| --------- | ------- | ------- |
| `attribution_model` | `LC`, `MTA`, `UMM` (UMM pixel only) | `MTA` |
| `attribution_mode` | `session_date`, `event_date` (keyword: session_date only) | `session_date` |
| `attribution_window` | `1-day`, `7-day`, `30-day`, `unlimited` | `7-day` |

Per-event `attribution_models` from `list_custom_events` guide event selection (UMM only when listed for that event).

### Step 4: Add dimensions and filters

- **dimensions**: columns to group by from `get_table_schema`
- **dimension_filter_mapping**: `{"dimension_name": ["value1", "value2"]}`

### Step 5: Call `insights_query`

Returns rows with requested dimensions and SUM-aggregated metric values.

## Example tool calls

### Campaign performance by channel (pixel)

```json
{
  "client_id": "acme-corp",
  "table_name": "marketing_performance",
  "metrics": ["spend", "event_value", "number_of_events", "impressions", "clicks"],
  "start_date": "2026-03-31",
  "end_date": "2026-04-06",
  "custom_event": "purchase",
  "dimensions": ["source"],
  "attribution_model": "MTA",
  "attribution_mode": "session_date",
  "attribution_window": "7-day",
  "dimension_filter_mapping": { "is_integrated_channel": ["1"] }
}
```

### Shopping product performance

```json
{
  "client_id": "acme-corp",
  "table_name": "shopping_performance",
  "metrics": ["spend", "clicks", "impressions", "event_value", "number_of_events"],
  "start_date": "2026-03-01",
  "end_date": "2026-03-31",
  "custom_event": "purchase",
  "dimensions": ["product_name", "source"],
  "dimension_filter_mapping": { "source": ["google"] }
}
```

### Keyword performance

```json
{
  "client_id": "acme-corp",
  "table_name": "keyword_performance",
  "metrics": ["spend", "clicks", "impressions", "sessions", "number_of_events"],
  "start_date": "2026-03-01",
  "end_date": "2026-03-31",
  "custom_event": "order_completed",
  "dimensions": ["keyword", "campaign_name"],
  "attribution_model": "MTA",
  "attribution_mode": "session_date"
}
```

## Computed metrics

| Metric | Formula | When to use |
| ------ | ------- | ----------- |
| `roas` | `event_value / spend` | Revenue-generating events |
| `cpa` | `spend / number_of_events` | Conversion-count events |
| `conversion_rate` | `(number_of_events / sessions) * 100` | Session conversion share |
| `cost_per_click` | `spend / clicks` | Click cost |

Use `event_value` for revenue events and `number_of_events` for conversion-count events (see per-event `metrics` from `list_custom_events`).

## Important data rules

### Integrated channels and spend metrics

Always include `{"is_integrated_channel": ["1"]}` when querying spend-derived metrics on **marketing_performance** data. Shopping and keyword datasets are integrated-channel data by nature.

### Keyword partitioning

The keyword table is partitioned on `customer_name` + `ev`. Always pass both `client_id` and `custom_event` — the server enforces this.

### Data recency

Data is available through yesterday.

## Error recovery

- **Invalid metric/dimension**: call `get_table_schema` for the table_name, then retry.
- **Invalid attribution**: check per-table attribution_models/modes from `get_table_schema`.
- **Empty results**: verify client_id, custom_event, and date range.

## Cross-skill references

- **billy-grace-attribution** — choosing attribution model, mode, and window
- **billy-grace-analysis** — interpreting results and marketing advice