Adstudio

View saved version →

---
name: ad-account-performance-review
description: Summarize how a Google Ads, Meta Ads or TikTok Ads account performed over a period (last week, last month, a custom date range) and compare it with the previous period. Use when the user asks for a performance review, weekly or monthly report, "how did my ads do", or a period-over-period comparison of spend, conversions, CPA or ROAS.
---

Use this skill when the user wants a period summary of one or more connected ad accounts. Adstudio tools are read-only: you can report and interpret, never change anything.

## Workflow

1. **Discover scope.** Call `list_accounts` (no arguments). It returns every workspace this connection reaches, the platforms connected in each (`google_ads`, `meta_ads`, `tiktok_ads`) and the selected account per platform.
   - If more than one workspace or account could fit, ask the user which one before going further. Never guess or default an id.
   - If the user says "all my ads" and the workspace has more than one ad platform connected, review each platform separately (steps 2-4 per platform) and then combine.
2. **Confirm what is queryable.** Call `describe_capabilities` with `workspaceId`, `platform` and `accountId`. Use the returned levels, metrics and breakdowns; do not request anything it does not list.
3. **Resolve the dates.** Convert the user's phrase into explicit `YYYY-MM-DD` ranges. "Last week" = the last full Monday-Sunday week; "last month" = the last full calendar month. Set `comparison` to the immediately preceding period of the same length unless the user names another baseline. State the ranges you chose in the answer.
4. **Query account totals.** Call `query_performance` with:
   - `level: "account"`, `start`, `end`, `comparison: { start, end }`
   - `metrics`: `["spend", "impressions", "clicks", "conversions", "conversion_value"]`, plus platform extras when useful (Google campaign level: `search_impression_share`, `search_budget_lost_impression_share`, `search_rank_lost_impression_share`; Meta: `reach`, `frequency`, `cpm`, `ctr`, `cpc`).
5. **Query campaign detail.** Call `query_performance` again with `level: "campaign"`, the same dates and comparison, `sort: { field: "spend", direction: "desc" }` and `limit: 50`. This is what the top movers section is built from.
6. **Optional trend.** If the user asks how the period developed, run one more `query_performance` at `level: "account"` with `breakdowns: ["date"]`. Only one breakdown is allowed per call.
7. **Compute derived metrics yourself** from the raw rows, for both the current and the comparison period:
   - CTR = clicks / impressions, CPC = spend / clicks, CVR = conversions / clicks
   - CPA = spend / conversions, ROAS = conversion_value / spend
   Google Ads rows do not include CTR, CPC or CPM; Meta and TikTok rows may, but compute them from the raw numbers anyway so the platforms are comparable.

## Output format

Lead with a two-to-three sentence verdict, then:

- **Totals table**: metric, current period, previous period, absolute and percentage change. Include spend, impressions, clicks, CTR, CPC, conversions, CVR, CPA, conversion value, ROAS.
- **Top movers**: up to five campaigns whose spend or CPA changed the most, with the numbers.
- **What to look at next**: two or three concrete follow-up questions the user can ask (for example, "diagnose campaign X" or "audit the creatives in campaign Y").

Show the currency exactly as the tool returns it and say which date ranges were used. Round money to two decimals and rates to one decimal place.

## Rules and pitfalls

- Always start with `list_accounts`; every other call needs an explicit `workspaceId`, `platform` and `accountId`.
- Metrics differ by platform and level; only request what `describe_capabilities` listed for that level.
- Meta `conversions` and `conversion_value` are attributed action totals; say "attributed conversions" rather than presenting them as sales.
- Conversion counts near zero make CPA and ROAS unstable. Flag that instead of ranking by them.
- If a response reports `truncated`, say the list is partial and offer to narrow the range or raise `limit` (max 500).
- If the envelope lists `unresolved` items, mention what could not be answered and why. Do not fill gaps with estimates.
- Do not compare rows from different platforms as if they were one dataset; present them side by side and note attribution differs.
- Never promise budget changes, pausing, bid edits or any action; the tools cannot perform them.

View saved version →

---
name: campaign-diagnosis
description: Explain why a Google Ads, Meta Ads or TikTok Ads campaign's CPA, ROAS, conversions or spend changed by decomposing the move into spend, impressions, CTR, CPC and conversion rate and locating it in the campaign's ad groups or ad sets. Use when the user asks "why did my CPA go up", "what happened to campaign X", "why did conversions drop" or wants a root cause for a metric change.
---

Use this skill when the user names a metric that moved and wants to know why. The answer is a decomposition of the change into its drivers, backed by tool rows. Adstudio tools are read-only.

## Workflow

1. **Discover scope.** Call `list_accounts` (no arguments). If more than one workspace or account could fit, ask which one. Never guess or default ids.
2. **Confirm capabilities.** Call `describe_capabilities` with `workspaceId`, `platform` and `accountId` and use only the levels, metrics and breakdowns it lists.
3. **Find the campaign.** If the user gave a name rather than an id, call `get_entities` with `level: "campaign"` (raise `limit` up to 500 if needed) and match the name. If several campaigns match, ask which one.
4. **Set the two windows.** Convert the user's phrasing into `start`/`end` and a `comparison` window of the same length immediately before it, unless the user names both periods. State the windows in the answer.
5. **Campaign-level decomposition.** Call `query_performance` with `level: "campaign"`, `filters: [{ field: "entity_id", value: "<campaignId>" }]`, both windows, and `metrics: ["spend", "impressions", "clicks", "conversions", "conversion_value"]`. Add `search_impression_share`, `search_budget_lost_impression_share` and `search_rank_lost_impression_share` on Google Ads; add `reach`, `frequency`, `cpm` on Meta Ads.
6. **Compute the chain for both windows** and the percentage change of each link:
   - impressions -> CTR (clicks / impressions) -> clicks -> CPC (spend / clicks) -> spend
   - clicks -> CVR (conversions / clicks) -> conversions -> CPA (spend / conversions)
   - conversion_value / spend -> ROAS
   Rank the links by how much they changed. The largest movers are the primary drivers; a CPA rise with flat CPC and falling CVR is a conversion problem, not a traffic-cost problem.
7. **Locate the change one level down.** Call `get_entities` with `level: "ad_group"` (Google Ads, TikTok Ads) or `level: "ad_set"` (Meta Ads) and `parentId: <campaignId>` to get the children's ids. Then call `query_performance` at that level with both windows, `filters` set to one `{ field: "entity_id", value }` entry per child id, and `sort: { field: "spend", direction: "desc" }`. Identify which children account for most of the metric change.
8. **One breakdown if it helps.** With the same filter, run one more `query_performance` using a single breakdown: `date` to see when the change started, `device` on any platform, or `placement`, `age`, `gender` on Meta Ads and TikTok Ads. Only one breakdown per call.
9. **Creative angle if CTR moved.** If CTR is a primary driver, call `get_creatives` with `scopeLevel: "campaign"` and `entityId: <campaignId>` to see what ads and copy are live, and suggest the creative-audit workflow for ranking them.

## Output format

- **Verdict** in two sentences: what moved, by how much, and the main driver.
- **Decomposition table**: metric, previous window, current window, change. Rows: impressions, CTR, clicks, CPC, spend, CVR, conversions, CPA, conversion value, ROAS (only the ones the platform supports).
- **Where it happened**: the two or three ad groups / ad sets (or breakdown segments) that explain most of the change, with numbers.
- **Likely causes** phrased as hypotheses with the evidence for each, followed by what the user could check or change. Distinguish clearly between what the data shows and what you infer.

Use the currency the tool returns, name the windows, and round consistently.

## Rules and pitfalls

- Never default `workspaceId`, `platform` or `accountId`; every call names them explicitly.
- Compute CTR, CPC, CVR, CPA and ROAS yourself from raw rows so both platforms use the same definitions.
- Small conversion counts (roughly under 20 per window) make CPA and CVR changes noisy; say so instead of over-interpreting them.
- `conversions` on Meta Ads are attributed action totals and are not sortable; sort by `spend` or `clicks` instead.
- TikTok Ads does not report `conversion_value` with the `age`, `gender`, `placement` or `device` breakdowns; use `date` or no breakdown for value questions.
- Google `search_*_impression_share` metrics are campaign-level only; `budget_lost` share rising points to a budget cap, `rank_lost` rising points to bids or quality.
- The tools expose no change history, budgets, bids or audiences; say when a suspected cause cannot be verified from the available data.
- Report `truncated` and `unresolved` fields honestly; do not fill gaps with estimates.
- Do not promise or imply that any change can be applied through these tools.

View saved version →

---
name: creative-audit
description: Rank the ads and creatives in a Google Ads, Meta Ads or TikTok Ads account, campaign, ad group or ad set by performance, show what each one says and links to, and flag likely creative fatigue. Use when the user asks which ads or creatives are working, which to pause or refresh, whether an ad is fatigued, or wants a creative review.
---

Use this skill when the user wants to know which ads are performing and which are wearing out. Adstudio tools are read-only: you can rank, quote and recommend, never pause or edit an ad.

## Workflow

1. **Discover scope.** Call `list_accounts` (no arguments). If more than one workspace or account could fit, ask which one. Never guess or default ids.
2. **Confirm capabilities.** Call `describe_capabilities` with `workspaceId`, `platform` and `accountId`. Use only the levels, metrics, breakdowns and creative scope levels it returns.
3. **Narrow the scope if asked.** If the user names a campaign, ad group or ad set, resolve its id with `get_entities` (`level: "campaign"`, then `"ad_group"` on Google Ads and TikTok Ads or `"ad_set"` on Meta Ads with `parentId`). Ask when a name matches several entities.
4. **Pull the creatives.** Call `get_creatives` with `scopeLevel` set to `"account"` (omit `entityId`), or `"campaign"`, `"ad_group"` / `"ad_set"`, `"ad"` with the matching `entityId`. `limit` is at most 100; page by narrowing the scope if the response reports `truncated`. Rows contain ad-to-creative assignments and normalized copy, media, destinations and automation flags, but no metrics.
5. **Pull ad performance.** Call `query_performance` with `level: "ad"`, the analysis window (default: the last 30 days, stated explicitly as `YYYY-MM-DD`), `metrics: ["spend", "impressions", "clicks", "conversions", "conversion_value"]` plus `reach`, `frequency`, `ctr`, `cpm`, `video_thruplays` on Meta Ads, `sort: { field: "spend", direction: "desc" }` and `limit` up to 500. Add `filters` with one `{ field: "entity_id", value }` per ad id when the user scoped the audit to a campaign or group. Add a `comparison` window of the same length before it so you can see decay.
6. **Trend for fatigue.** For the top ads by spend, run one more `query_performance` at `level: "ad"` with `breakdowns: ["date"]` and `filters` for those ad ids (weekly is fine: aggregate the daily rows yourself).
7. **Join and compute.** Match performance rows to creative rows by ad id. For each ad compute CTR = clicks / impressions, CPC = spend / clicks, CVR = conversions / clicks, CPA = spend / conversions, ROAS = conversion_value / spend. Compute the same for the comparison window.
8. **Flag fatigue** when an ad shows two or more of the following against its comparison window or its own earlier days: CTR down 20 percent or more with similar or higher impressions, CPA or CPM up 20 percent or more, frequency above roughly 3 on Meta Ads with flat or falling CTR, or a steady week-over-week decline in CTR in the date breakdown. Report the signals you saw, not just the label.

## Output format

- **Ranking table**: ad id and name, campaign, spend, impressions, CTR, CPC, conversions, CPA, ROAS, and a status column (Scale / Keep / Watch / Fatigued / Too little data).
- **What the winners say**: for the top three ads, quote the headline or primary text, describe the media type and the destination from `get_creatives`, and name the common pattern.
- **Fatigue flags**: each flagged ad with the specific signals and numbers behind the flag.
- **Suggestions**: two or three next steps the user can take in their ad platform (refresh a creative, test a new angle, shift attention to a winner). Phrase them as recommendations; the tools cannot apply them.

Use the currency returned by the tool, state the window, and round consistently.

## Rules and pitfalls

- Every call after `list_accounts` names `workspaceId`, `platform` and `accountId` explicitly.
- Ads with fewer than roughly 1,000 impressions or fewer than 10 conversions get "Too little data" rather than a rank by CPA or ROAS.
- Compute rates from raw numbers so Google Ads, Meta Ads and TikTok Ads are comparable; Google rows do not include CTR, CPC or CPM.
- Google Ads has no `frequency` or `reach`; fatigue there rests on CTR and CPA trends plus the date breakdown.
- TikTok Ads media is reported by asset id (Spark Ads by post id); `video_thruplays` is TikTok's 6-second view count, not a full ThruPlay.
- Meta `conversions` and `conversion_value` are attributed action totals and not sortable; sort by `spend` or `clicks`.
- `get_creatives` returns no metrics and `query_performance` returns no copy; always join them, never guess what an ad contains.
- Report `truncated` and `unresolved` fields honestly; say what you could not see.
- Do not promise to pause, edit, duplicate or launch ads; the tools are read-only.