Billy Grace Insights

View saved version →

---
name: billy-grace-analysis
description: >
  Interpret Billy Grace marketing results: analyze campaign performance,
  explain ROAS and CPA, apply funnel stages, optimize budgets, compare
  channels, evaluate creative performance, and diagnose why performance
  changed. Use whenever the user asks what the numbers mean, why results
  moved, or how to improve them, even if they never say "analysis". Do not
  use to build or run the query that fetches the data (use
  billy-grace-data-retrieval), or to pick attribution models, modes, or
  windows (use billy-grace-attribution).
metadata:
  author: Billy Grace
  version: 1.1.0
  mcp-server: billy-grace-insights-mcp
---

# Billy Grace Marketing Analysis

This skill teaches you how to interpret marketing performance data retrieved from the Billy Grace MCP server and provide actionable, strategically sound advice. The guidance here reflects Billy Grace's domain expertise as a marketing optimization platform.

When users compare Billy Grace numbers to ad-platform or web-analytics reporting, differences are expected: Billy Grace attributes over identity-resolved customer journeys rather than fragmented sessions (see the **billy-grace-attribution** skill).

## Performance metrics

### Core metrics

| Metric | What it measures | When it matters |
|--------|-----------------|-----------------|
| `spend` | Budget invested in a campaign | Understanding pacing and budget distribution |
| `event_value` | Attributed revenue (or value) from the custom event | Measuring return on marketing investment |
| `number_of_events` | Attributed count of conversions | Volume of desired outcomes |
| `impressions` | Number of times ads were shown | Reach and awareness |
| `clicks` | Number of ad clicks | Engagement and traffic generation |
| `sessions` | Website sessions from marketing | Traffic volume |

### Computed metrics

These metrics may be returned by the server or may need to be computed from raw data. Always verify you have the component values and compute them yourself when the server does not return them.

| Metric | Formula | Interpretation |
|--------|---------|----------------|
| `roas` | event_value / spend | Revenue generated per euro spent. Higher is better. Only meaningful for revenue-type events and **paid channels with spend > 0**. |
| `cpa` | spend / number_of_events | Cost to acquire one conversion. Lower is better. Works for both revenue and non-revenue events. Guard against division by zero when a channel has no conversions. |
| `conversion_rate` | (number_of_events / sessions) * 100 | Percentage of sessions that convert. Indicates landing page and funnel effectiveness. |
| `cost_per_click` | spend / clicks | Price per click. Rising CPC with stable CTR may signal increased auction competition. |

When computing these from raw data, handle edge cases: skip ROAS/CPA for rows where `spend` is 0 (non-paid channels), and skip CPA where `number_of_events` is 0.

### Additional metrics (not available for all clients)

| Metric | What it measures |
|--------|-----------------|
| `new_customer` | Conversions from first-time buyers |
| `returning_customer` | Conversions from existing customers |
| `new_customer_revenue` | Revenue from new customers |
| `returning_customer_revenue` | Revenue from returning customers |
| `pre_spend_profit` | Gross profit before subtracting ad spend |

### New vs returning customer metrics

When available, `new_customer`, `returning_customer`, `new_customer_revenue`, and `returning_customer_revenue` reveal the health of acquisition vs retention:

- **High returning_customer share with low new_customer**: the brand is retaining well but may not be growing its customer base. TOFU investment could be underfunded.
- **High new_customer share with low returning_customer**: acquisition is working but retention is weak. Check email/CRM flows and post-purchase experience.
- **new_customer_revenue vs returning_customer_revenue**: returning customers often have higher AOV. A drop in returning_customer_revenue may signal churn, not a marketing problem.

## Custom event types

Custom events are user-defined conversions (e.g., "purchase", "form_send", "demo_booked"). They fall into two categories, and the distinction determines which metrics make sense:

### Revenue events (e.g., purchase, order_completed, subscription_started)

The `event_value` translates directly to monetary value. Use **ROAS** (event_value / spend) as the primary efficiency metric.

### Non-revenue events (e.g., form_send, demo_booked, call_scheduled)

The `event_value` does not represent money, so ROAS is meaningless. Use **CPA** (spend / number_of_events) instead. The goal is minimizing cost per conversion, not maximizing a revenue ratio.

Always confirm which type of event the user is analyzing before choosing metrics.

## Funnel stages

Marketing campaigns serve different roles depending on where in the funnel they operate. Interpret performance relative to the campaign's funnel stage, not in absolute terms.

### TOFU (Top of Funnel) -- Awareness

**Purpose**: reach cold audiences unfamiliar with the brand.

- Expect high impressions, low direct conversions, and higher CPA. This is normal -- TOFU is investing in future demand.
- Platforms typically used: Meta, TikTok, Snapchat, YouTube, TV, Radio.
- Only classify as BOFU when "retargeting" appears in the campaign name.

### MOFU (Middle of Funnel) -- Consideration

**Purpose**: nurture users who previously engaged with TOFU content.

- Targets warm audiences: site visitors, video viewers, email subscribers.
- Performance should be between TOFU and BOFU.

### BOFU (Bottom of Funnel) -- Conversion

**Purpose**: convert high-intent users close to purchasing.

- Expect strong ROAS, low CPA, and high conversion rates. This is where direct ROI shows up.
- Platforms typically used: Google/Bing Search, retargeting campaigns on any platform.
- Only classify Google/Bing Search as TOFU/MOFU when "display" appears in the name.

### Interpreting performance across the funnel

Comparing a TOFU campaign's ROAS to a BOFU campaign's ROAS is like comparing a seed to a harvest. TOFU feeds the funnel that BOFU harvests. Evaluate each stage against its own purpose:

- TOFU: reach, impressions, video views, new audience growth
- MOFU: engagement, CTR, site traffic quality
- BOFU: ROAS, CPA, conversion rate, revenue

## Diagnostic playbook: investigating performance changes

When a user reports that a metric changed (e.g. "ROAS dropped," "CPA spiked," "conversions fell"), follow this investigation workflow:

### Step 1: Establish baseline with supporting metrics

Fetch the primary metric AND its supporting metrics (see below) for the current period and a comparison period (previous week, previous month, or same period last year). Include supporting metrics in the initial query to avoid extra round-trips -- a ROAS investigation should request `roas`, `event_value`, `number_of_events`, `spend`, `cpa`, `clicks`, and `cost_per_click` upfront.

Use the **billy-grace-data-retrieval** skill to make two `insights_query` calls with different date ranges.

### Step 2: Isolate the scope

If the user already names a specific channel (e.g., "Google Ads"), start the investigation filtered to that channel using `dimension_filter_mapping` and break down by `campaign_name`. If no specific channel is mentioned, first break down by `source` to see if the change affects everything or specific channels, then drill into `campaign_name` for the affected channel.

### Step 3: Interpret supporting metrics

A single metric rarely tells the full story. When investigating:

- **ROAS dropped**: check `cpa`, `event_value`, `number_of_events`, and `spend`. Did revenue fall? Did spend increase? Did conversions decrease?
- **CPA increased**: check `spend`, `number_of_events`, `clicks`, `cost_per_click`. Is spend up, or are conversions down?
- **CTR falling**: check `impressions` and `clicks` separately. Is the audience seeing more impressions (frequency issue / creative fatigue) or are fewer people clicking (relevance issue)?

### Step 4: Rule out data and attribution artifacts

- **Conversion lag**: if using a long attribution window and looking at recent data, the dip may be an artifact of incomplete attribution. Consult the **billy-grace-attribution** skill.
- **Incomplete data**: check for zero event_value across all campaigns, which signals a data pipeline issue, not a real performance drop.
- **Campaign status**: include `campaign_status` in the breakdown to check whether campaigns were paused during the period.

### Step 5: Form and communicate hypotheses

Based on the evidence, propose likely explanations framed as hypotheses (see Communication style below). Suggest next steps the user can take to confirm or act on the findings.

## Campaign name interpretation

Campaign names often encode funnel stage, objective, targeting, and market. Common patterns in the data:

- **"Conversie" / "Conversion"** → BOFU objective. Expect strong ROAS/CPA.
- **"Prospecting" / "Awareness" / "Reach"** → TOFU objective. Expect high impressions, weaker direct ROAS.
- **"Retargeting" / "Remarketing"** → BOFU, harvesting warm audiences.
- **"Brand" / "Branded"** → Capturing existing demand. High ROAS is expected but not scalable.
- **"PMax" / "pMax" / "Catch-All"** → Google Performance Max. Mixed funnel; evaluate holistically.
- **"Shopping" / "Fall-Back"** → Product feed campaigns. High impressions with low conversion may signal feed quality issues.
- **Market codes** (e.g. "NL", "BE", emoji flags) → Geographic targeting. Compare markets separately rather than blending.
- **"ABO" vs "CBO"** → Facebook ad set budget optimization vs campaign budget optimization. ABO gives more granular control; CBO lets Meta auto-allocate.

Use these signals to assign funnel context rather than judging all campaigns by a single ROAS bar.

## Interpretation heuristics

These are contextual guidelines, not fixed thresholds -- actual values vary by industry, product, and market.

- **High CPA for TOFU campaigns**: expected. TOFU generates awareness, not immediate conversions.
- **High CPA for BOFU campaigns**: concerning. These should be your most efficient converters.
- **Falling CTR with stable audience and offer**: likely creative fatigue. Suggest testing new creatives before cutting budget.
- **High ROAS on branded search**: expected but not scalable. Branded search captures existing demand; it does not create new demand.
- **Zero event_value or number_of_events across all campaigns**: likely a data issue, not a performance issue. Warn the user and suggest checking data completeness before drawing conclusions.
- **ROAS looks great but spend is tiny**: the campaign may not be scalable. Efficiency at low spend does not guarantee efficiency at higher spend.

## Critical budget anti-pattern: do not shift TOF budget to BOF

When BOFU campaigns show much higher ROAS than TOFU campaigns, it is tempting to recommend moving budget from top-of-funnel to bottom-of-funnel. Do not do this. BOFU campaigns convert users that TOFU campaigns first made aware of the brand. Cutting TOFU starves the funnel that BOFU depends on, leading to declining performance over time even though the short-term ROAS looks great.

Instead, suggest optimizing within TOFU (better creatives, better audiences, reallocating between TOFU campaigns) or consult `references/budget-optimization.md` for deeper budget strategy guidance.

## MER (Marketing Efficiency Ratio)

MER is calculated as total revenue divided by total marketing spend. Billy Grace strongly discourages using MER for decision-making because it creates a perverse incentive: cutting marketing spend directly improves MER, making it look like performance improved when in reality you are starving the funnel. Short-term gains from spend cuts mask long-term damage to pipeline and revenue.

If a user asks about MER, explain this dynamic and suggest ROAS at the channel or campaign level as a more actionable alternative.

## Email, CRM, and owned channels

Channels like Klaviyo, email newsletters, loyalty programs, and direct traffic often appear in Billy Grace data with zero spend. They represent **demand capture and retention**, not paid acquisition.

- **Do not compare their "ROAS" to paid channels.** With zero spend, ROAS is undefined -- these channels are not competing on the same playing field as Meta or Google.
- **High revenue from email/CRM is a sign of healthy retention**, not proof that paid is underperforming. Paid acquisition creates the customer base that email then nurtures and reconverts.
- **When email revenue dominates**, highlight it as a strength but frame paid channels in terms of their **marginal contribution**: are they bringing in new customers that email can later retain?
- **Klaviyo flows vs campaigns**: automated flows (welcome series, cart abandonment, winback) are always-on retention engines. One-off campaigns (newsletters, promotions) are demand spikes. Both can show up as separate `campaign_name` values within the `klaviyo` source.

## Incomplete data detection

Before analyzing results, check for signs of incomplete data:

- If `event_value` and `number_of_events` are zero across all campaigns for recent dates, the data pipeline may have a gap. Do not present zero-conversion data as real performance -- flag it and ask the user to verify.
- If a specific channel suddenly shows zero conversions while others look normal, that channel's integration may have an issue.

Present these as observations, not conclusions, and suggest the user investigate further.

## Result presentation guidance

Tailor output format to the analysis type:

- **Comparisons** (channels, campaigns, time periods): use tables for side-by-side readability.
- **Overviews** (total performance summary): use a brief narrative with key numbers highlighted.
- **Drill-downs** (investigating a specific issue): lead with the finding, then show supporting data.
- **Trends** (daily/weekly performance over time): describe the trajectory and highlight inflection points.

## Communication style

Frame all advice as hypotheses and experiments, not directives. Marketing is complex and context-dependent -- what works for one business may not work for another.

**Preferred phrasing**:
- "The data suggests..."
- "It could be worth testing..."
- "If this pattern continues, you might want to consider..."
- "Given the current data, it is likely that..."

**Avoid**:
- "You must..."
- "This is a waste of money."
- "Always do X."

Acknowledge uncertainty and trade-offs. When the user asks for a definitive recommendation, explain the reasoning and caveats rather than giving a bare instruction.

For deeper guidance on budget optimization strategy, consult `references/budget-optimization.md`.

## Cross-skill references

- Use the **billy-grace-data-retrieval** skill to fetch data through the MCP tools before applying this analysis guidance.
- When the analysis involves choosing or interpreting attribution settings, consult the **billy-grace-attribution** skill.

Referenced files: 2

View saved version →

---
name: billy-grace-attribution
description: >
  Choose and explain Billy Grace attribution settings: attribution models
  (Last Click, MTA, UMM), attribution modes (Session Date vs Event Date),
  attribution windows (1-day through unlimited), and conversion lag. Use
  whenever the user mentions attribution, MTA, UMM, last click, session date,
  event date, attribution windows, or conversion lag, or when the choice of
  attribution parameters changes how a query result must be read. Do not use
  to build or run the query itself (use billy-grace-data-retrieval), or for
  performance interpretation unrelated to attribution settings (use
  billy-grace-analysis).
metadata:
  author: Billy Grace
  version: 1.1.0
  mcp-server: billy-grace-insights-mcp
---

# Billy Grace Attribution

Attribution determines how conversion credit is distributed across marketing touchpoints. Choosing the right attribution settings is critical because different settings can paint very different pictures of the same marketing activity. This skill covers the three dimensions of attribution in Billy Grace and how they map to `insights_query` parameters.

## Identity resolution: the foundation under every model

All Billy Grace attribution models run on top of Billy Grace's industry-leading identity resolution engine. Built on first-party pixel data, it stitches sessions from the same user across devices, browsers, and cookie resets by combining deterministic signals with probabilistic matching, and the resulting identity graph is continuously updated and periodically rebuilt from the ground up as new evidence arrives.

Why this matters for attribution:

- **Complete journeys, not fragments.** MTA and UMM assign credit along the full customer journey. Without cross-device and cross-session stitching, one user looks like several disconnected visitors and mid-funnel touchpoints silently lose the credit they earned.
- **Model quality is bounded by journey quality.** A sophisticated attribution model on fragmented data still produces fragmented answers. Billy Grace's models are powerful precisely because they see identity-resolved journeys.

When a user asks why Billy Grace's numbers differ from ad-platform or web-analytics numbers, identity resolution is a key part of the answer: those sources count fragmented sessions, while Billy Grace attributes over complete stitched journeys.

## Parameter mapping

These are the `insights_query` parameters you control:


| Domain concept     | Parameter            | Options                                 | Default        |
| ------------------ | -------------------- | --------------------------------------- | -------------- |
| Attribution model  | `attribution_model`  | `LC`, `MTA`, `UMM`                      | `MTA`          |
| Attribution mode   | `attribution_mode`   | `session_date`, `event_date`            | `session_date` |
| Attribution window | `attribution_window` | `1-day`, `7-day`, `30-day`, `unlimited` | `7-day`        |


## Attribution models

### Last Click (LC)

Assigns 100% of conversion credit to the last touchpoint before the conversion.

This model gives an extremely narrow view of marketing performance. It completely ignores every touchpoint except the final click, which means awareness campaigns, nurturing efforts, and upper-funnel activity receive zero credit -- regardless of how much they contributed to the eventual conversion. Because of this, Last Click systematically overvalues bottom-of-funnel channels (branded search, retargeting) and undervalues everything else.

Only use Last Click when the user explicitly requests it, and explain these limitations. Never proactively recommend it.

### Multi Touch Attribution (MTA)

Billy Grace's deep-learning MTA model analyzes user behavior, campaign data, and conversion data to assign credit to each click-based touchpoint along the customer journey based on its relative contribution. The journeys it learns from are identity-resolved (see above), so touchpoints are credited even when they happened on a different device or in a different browser than the conversion.

MTA is not a shared heuristic or a generic rules-based model: models are trained and managed per client and per conversion event, on that account's own identity-resolved journey data. A "purchase" and a "newsletter_signup" event each get attribution learned from their own journey patterns. This is also why `list_custom_events` reports available attribution models per event.

MTA is the right choice for:

- **Daily tactical optimization** -- evaluating which campaigns or ad sets to adjust today
- **Click-based customer journeys** -- when the path to conversion is primarily driven by clicks
- **Short customer journeys** -- where the gap between first touch and conversion is relatively small
- **Bottom-of-funnel analysis** -- understanding which BOFU campaigns convert most efficiently

### Unified Marketing Measurement (UMM)

UMM combines Media Mix Modelling (MMM) and MTA through machine learning. Where MTA only credits click-based touchpoints, UMM also models the impact of impressions (views) on sessions that start via other channels. For example, a Meta ad impression may cause a user to later start a Google or direct session that converts -- MTA cannot capture this, UMM can.

This makes UMM essential for understanding the true value of top-of-funnel and awareness campaigns that drive conversions indirectly.

UMM is the right choice for:

- **Strategic marketing evaluation** -- understanding the full impact of your marketing mix
- **Top-of-funnel campaign analysis** -- where impressions matter as much as clicks
- **Long customer journeys** and brand building
- **Weekly or monthly optimization** at the channel level
- **Cross-channel view effects** -- when you suspect upper-funnel activity is feeding lower-funnel conversions

UMM is not available for all clients -- it requires sufficient data volume.

### Decision framework: MTA vs UMM

Ask yourself: **Is the user trying to understand click-driven performance or full-funnel impact?**

- If they care about **daily campaign-level decisions** and **direct-response performance** -> recommend **MTA**
- If they care about **strategic channel allocation**, **impression-driven awareness**, or **why top-of-funnel campaigns matter** -> recommend **UMM**
- When in doubt, suggest running the same query with both models side by side. The difference reveals how much credit shifts to impression-driven channels under UMM.

### UMM calibration schedule

UMM's underlying model trains weekly:

- Training happens every **Thursday**
- Updated numbers appear on **Friday**
- New campaigns added mid-week get attribution based on their most similar existing campaigns until the next training cycle officially incorporates them

This means UMM data for brand-new campaigns may shift after the next Thursday training. Factor this in when analyzing recently launched campaigns.

## Attribution modes

The attribution mode determines *when* in time conversion credit is recorded.

### Session Date

Credit is assigned to the day each marketing touchpoint (session) occurred. This aligns spend and attributed credit in time.

**Use Session Date when the analysis involves spend-based metrics** (ROAS, CPA, POAS, cost_per_click). The reason: spend happens on the day the ad runs, and Session Date puts the attributed credit on that same day. This makes the ratio between spend and credit meaningful. With Event Date, spend and credit land on different days, making ROAS/CPA calculations misleading.

Session Date is the default and the right choice for most analyses.

**Limitation**: with longer attribution windows, recent days will appear understated. Touchpoints happened, but the conversions they contribute to have not yet occurred. This is conversion lag (see below).

### Event Date

Credit is assigned to the day the conversion event happened, regardless of when the touchpoints occurred.

**Use Event Date only when the question is about when conversions happened**, not about marketing efficiency. Good fits:

- "How many purchases happened on Black Friday?"
- Seasonality and demand pattern analysis
- Counting events in a specific period when spend is not part of the question

**Never use Event Date for ROAS, CPA, or any spend-based metric.** Spend and attribution will not align in time, producing numbers that are actively misleading.

**Why stakeholders may prefer Event Date**: Event Date numbers often look "better" and more stable than Session Date because there is no conversion lag effect. This can make it tempting to switch all reporting to Event Date. When a user or their manager proposes this, acknowledge the appeal (stable, complete-looking numbers) but explain that stability comes at the cost of accuracy for any spend-based analysis. Help the user articulate this trade-off to their stakeholders.

### Decision framework: which mode?

1. Does the analysis involve ROAS, CPA, or any metric involving spend? -> **Session Date**
2. Is the user asking about total event counts or when conversions happened? -> **Event Date**
3. Not sure? -> **Session Date** (the safe default)

## Attribution windows

The window defines how far back in time a touchpoint can receive credit for a conversion.


| Window    | Parameter value | Best for                                            |
| --------- | --------------- | --------------------------------------------------- |
| 1 day     | `1-day`         | Very short purchase cycles, impulse buys            |
| 7 days    | `7-day`         | Standard e-commerce, default for most analyses      |
| 30 days   | `30-day`        | Longer consideration periods, higher-value products |
| Unlimited | `unlimited`     | Full customer journey, strategic analysis           |


### How windows interact with modes

The combination of window and mode affects data completeness and interpretation:

- **Session Date + long window (30-day/unlimited)**: credit spreads further back in time. Recent data is more affected by conversion lag because there is a larger window of future conversions that haven't happened yet.
- **Session Date + short window (1-day/7-day)**: less conversion lag, but early-funnel touchpoints that influenced the conversion outside the window get no credit.
- **Event Date + long window**: stable conversion counts with no lag, but cannot be combined with spend metrics.
- **Event Date + short window**: may exclude early-funnel contributions entirely.

## Conversion lag

Conversion lag is the delay between a marketing touchpoint and the eventual conversion. It ranges from minutes to weeks depending on product, channel, and journey length.

### Why it matters

When using Session Date mode, the most recent days in your date range will almost always look understated. The touchpoints happened, but the conversions they will eventually drive have not occurred yet. The effect is strongest for yesterday's data and diminishes as you go further back.

### Practical guidance

- When a user is alarmed by low recent numbers, lead with reassurance before the technical explanation. Start with something like "This is expected behavior given your attribution settings" and then explain the mechanism. Users hearing "conversion lag" for the first time need context, not just terminology.
- When analyzing recent performance with longer attribution windows, explain to the user that metrics like ROAS, CPA, and attributed revenue for recent days will likely increase over time as more conversions come in.
- Data is not "final" until the attribution window has fully closed. For a 30-day window, data from 29 days ago is relatively stable; data from yesterday is not.
- For fair comparisons, consider using a completed period (e.g., the 30 days ending 30 days ago) rather than the most recent 30 days.
- Be cautious about budget decisions based solely on recent Session Date data within an open attribution window.

### Concrete scenario

A user asks for ROAS over the last 14 days using a 30-day attribution window in Session Date mode. The last few days will show lower ROAS than they will eventually reach, because conversions that those touchpoints will drive over the next 16-29 days have not happened yet. Warn the user about this and suggest also looking at a fully closed period for comparison.

## Cross-skill references

- After choosing attribution settings, use the **billy-grace-data-retrieval** skill to build and execute the `insights_query` call with the right parameters.
- When interpreting results, especially differences between attribution models, consult the **billy-grace-analysis** skill for guidance on what the numbers mean for marketing strategy.

Referenced files: 1

View saved version →

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

Referenced files: 1