# Ads Manager

Use Ads Manager to discover and manage ad accounts, campaigns, ad groups, and ads; analyze performance, conversions, and change history; upload creative images; and, when available, complete self-serve account setup. When multiple campaigns need selection, call `list_campaigns` with `include_performance_metrics=true` so the gated picker can show recent performance.

## Try it

- Help me create a new Ad.
- Use $ads-manager-insights to compare performance across my campaigns.
- Use $ads-manager-insights to summarize common topics in my Business Agent conversations, when available.
- Based on those Business Agent sizing concerns, what sizing information should we add?
- Show the recorded changes to my campaign's budget and who made them.
- Use $ads-manager-start-agent to set up recommendation-only reviews for my campaigns.
- Compare campaign performance and highlight opportunities to improve.
- Use $ads-manager-review to run a read-only CMO review of my Ads Manager account.
- Use $ads-manager-actionable-review to review my account and prepare exact changes for my approval.
- Use $ads-manager:ads-manager-setup to help me get started with Ads Manager.
- Help me create an Ads Manager ad account for my business.
- Get help with Ads Manager or troubleshoot why my campaign, ad group, or ad is not delivering.
- Diagnose why an existing campaign is not scaling and give me a read-only recovery plan.

The plugin materializes the first-party `connector_openai_ads_manager` app. It remains explicitly installable and subject to workspace app-access policies: a NoAuth install creates a persisted Ads Manager connector link before its tools are exposed, while existing OAuth links retain their refresh and reauthentication support.

When enabled for both the user and selected account, `ask_business_agent_insights` answers aggregate Business Agent conversation questions and supports practical business recommendations grounded in those themes through this same app in ChatGPT and Codex. It takes the selected `ad_account_id`, a self-contained `question`, and optional paired UTC `start_time` and `end_time`. Follow the returned evidence basis: observed conversation facts use activity dates, while summary snapshots use ingestion dates and may describe earlier activity. Reports lead with supported findings and preserve returned measurements and qualified theme estimates. Missing or uncertain information is discussed only when explicitly requested; a partial answer does not establish that the account has no usable data for its omitted parts. Individual conversation summaries and raw transcripts are not exposed. Follow-ups retain the account, subgroup, numerical intent, and returned UTC window unless the user changes them.

General conversation overviews request the main shopper intents and supported activity highlights. Primary-intent classifications describe the dominant intent; they are not interchangeable with percentages mentioning a narrower topic. Topic-percentage questions preserve the user's meaning and the tool's approximate qualifier, without adding sampling methodology or internal classification details. Deeper qualitative explanations remain grounded in reviewed summaries. When the tool returns a supported date-range alternative, offer it without silently changing the requested period. These instructions ship through the normal plugin bundle release; Sofa deployments and Statsig targeting determine which backend measurement capabilities are available.

## Shared references

Reporting instructions have the following owners:

| Location | Responsibility |
| --- | --- |
| App instructions | Route reporting, recommendations, and diagnosis |
| Insights skill | Resolve scope, select tools, collect evidence, and present reports |
| `shared-references/insights-contract.md` | Metric meaning, comparisons, aggregation, ranking, currency, and unavailable values |
| Tool descriptions and schemas | Argument meaning, defaults, dependencies, and supported response behavior |
| Tool errors | Rejection reasons, recovery actions, and corrective guidance |
| Review skills | Recommendation evidence requirements and thresholds |

When adding a reporting argument, update its schema, description, and pinned eval tool metadata/provenance together. Update the shared contract when interpretation changes and the insights workflow when tool selection or evidence collection changes. Sofa owns attribution calculations, account-specific event recognition, authorization, and data availability.

Canonical cross-skill references live in `shared-references/`. Edit those files directly; do not manually edit generated copies under `skills/*/references/_shared/`.

When a canonical shared reference or `shared-references/consumers.json` changes, run:

```bash
python chatgpt/oai-maintained-plugins/plugins/ads-manager/scripts/materialize_shared_references.py
```

Commit both the canonical changes and regenerated skill-local copies. Use `--check` to verify copies are synchronized.

It bundles eleven skills: `ads-manager-setup` welcomes users and routes their first task; `ads-manager-onboarding` guides progressive business-first self-serve account creation with optional attached, linked, or generated logos; `ads-manager-account-admin` coordinates confirmed existing-account user, invitation, role, removal, and logo workflows; `ads-manager-ad-creation` owns URL-driven website and image discovery, single- and multi-ad drafting, campaign-aware creative image handling, preview, upload, and save or publish; `ads-manager-entity-management` coordinates direct campaign and ad-group creation plus existing campaign, ad-group, and ad updates; `ads-manager-insights` reports performance, rankings, comparisons, trends, conversion data, and aggregate Business Agent conversation insights when available; `ads-manager-help` combines live connector evidence with specific Ads Manager Help Center articles; `ads-manager-delivery-recovery` identifies the first constrained delivery layer and produces a prioritized recovery plan; `ads-manager-start-agent` gathers a bounded recommendation goal, scope, and cadence before running once or preparing recurring read-only reviews; `ads-manager-review` performs scheduled or manual read-only shadow analysis and returns proposal-shaped performance recommendations without mutating Ads Manager state; and `ads-manager-actionable-review` is an explicit-invocation experiment that performs a manual read-only review, offers exact owner-supported changes for approval, and delegates accepted writes to their owning skills.