facebook-ads9.39 KB
View saved version →
---
name: facebook-ads
description: Analyze and manage Meta Ads (Facebook & Instagram ad placements) through Windsor.ai. Use when the user asks about their Facebook Ads / Meta Ads performance — pulling campaign, ad set, or ad metrics (spend, impressions, clicks, conversions, CPA, ROAS), comparing date ranges, or finding top or underperforming campaigns — or when they want to create, pause, or enable a campaign, ad set, or ad, change a budget, boost an existing post, edit ad creative or targeting, duplicate an ad set, look up targeting interests or locations, or create a lead form (Instant Form). Do not use for other ad platforms (Google Ads, TikTok, LinkedIn, Microsoft Ads), organic Facebook Page posts or Instagram organic content, or designing/generating ad creative images.
---
# Facebook Ads via Windsor.ai
Windsor.ai exposes Meta Ads data (read) and a set of campaign management
actions (write) for Facebook and Instagram ad placements through MCP tools.
The connector id is `facebook`. On the Facebook Ads app the connector is
already scoped, so you usually do not need to pass it — but when a tool asks
for a connector, use `facebook`.
This connector covers **Meta Ads** (paid Facebook & Instagram ad placements)
only. It is distinct from Facebook Organic (Page posts) and Instagram
organic, which live in their own connectors — route organic questions there.
Golden rules:
- **Never guess field, account, action, or option names.** They come from
`get_fields`, `get_connectors`, `list_actions`, and `get_options`. Call those
first; do not invent identifiers.
- **Reads are safe; writes change live ad spend.** Only call `execute_action`
after the user has confirmed the specific change.
- Report numbers the user asked for, concisely. Don't dump raw rows unless asked.
## 1. Ground yourself first
Call `get_connectors` to see which Meta Ads accounts are connected (each has
an id and, usually, a name). If none are connected, help the user connect one:
call `get_connector_authorization_url` (or `get_connector_connect_info` for the
auth type and steps) and give them the setup link — do not describe manual
dashboard navigation.
If the user names an account, match it to a connected account id. If several are
connected and the request is ambiguous, ask which account.
## 2. Reading performance data
1. Call `get_fields` for `facebook` to get valid field ids (e.g. campaign,
ad set, ad, date, spend, impressions, clicks, conversions, purchases — use
the exact ids returned, not these examples).
2. If the analysis needs attribution windows or other segmentation controls,
call `get_options` to see the connector's options and valid values (e.g.
click/view attribution windows).
3. Call `get_data` with:
- `fields`: the ids you actually need (keep the set small).
- `accounts`: the target account id(s); omit for all connected accounts.
- A date range: either `date_from`/`date_to` (`"2026-02-01"`), or
`date_preset` — `last_7d`, `last_30d`, `last_Xd`/`last_Xw`/`last_Xm`,
`this_month`, `this_year`, `last_year`. Append `T` to include today
(e.g. `last_7dT`, `this_monthT`).
- `options`: only if get_options showed relevant ones.
- `filters`: optional conditions, e.g. `[["spend", "gt", 100]]`; combine
with `"and"`/`"or"` and nest as needed.
Common requests → recipe:
- **Overview / trend:** fields `date` + the metrics, over a preset range.
- **By campaign / ad set / ad:** fields campaign/ad set/ad + metrics; sort or
aggregate in your answer.
- **Best / worst campaign:** pull campaign + the metric, then rank; return only
what was asked (e.g. just the campaign name) if the user constrained the
output format.
- **Efficiency:** cost per result = spend ÷ conversions (or purchases); ROAS =
purchase value ÷ spend. Compute from returned fields; note if the
denominator is zero.
Watch out: Meta spend fields are in the account currency (state it if known).
If a field the user wants isn't in `get_fields`,Preview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.