ChatGPT Ads MCP server

openai ads get insights

openai_ads_get_insights

Read-onlyIdempotent

Read ad performance metrics by account, campaign, ad group, or ad for inclusive date ranges, with optional country, device, or platform delivery breakdowns.

Instructions

Read performance by account, campaign, ad group or ad over inclusive account-local dates. One optional country, device or platform breakdown supports delivery metrics only; use openai_ads_get_conversion_insights for conversions by country or device. Attribution defaults to 30-day click, 1-day view and ad_event_time. CTR and CVR are fractions; money uses major units of the account currency. Pages are followed up to maxRows and truncation is explicit.

Input Schema

Name	Required	Description	Default
`level`	No	Aggregation level: ad_account, campaign, ad_group or ad. Defaults to campaign.	campaign
`since`	Yes	First day of the report, YYYY-MM-DD, in the account's time zone. Inclusive.
`until`	Yes	Last day of the report, YYYY-MM-DD, in the account's time zone. Inclusive. At most 365 days after since.
`maxRows`	No	Maximum rows to collect across pages, 1 to 10,000. truncated is true when more rows exist.
`metrics`	No	Native metrics to return. Defaults to spend, impressions and clicks.
`breakdown`	No	One delivery breakdown per request: country, device or platform. Supports impressions, clicks, spend, ctr, cpc and cpm. Omit for entity totals.
`adAccountId`	Yes	The adacct_ ID configured in OPENAI_ADS_ACCOUNT_ID. The API key is scoped to this one account; another ID is refused.
`attribution`	No	Report attribution only: attribution_window_days 7, 14 or 30, view_through_attribution_window_days 0 or 1, attribution_time_basis ad_event_time or conversion_time. Campaign goals are unchanged.
`timeGranularity`	No	daily returns one row per day; none returns period totals.	daily

Output Schema

Name	Required	Description	Default
`result`	Yes	Original tool result: parsed JSON when the text is JSON, otherwise the text or multiple MCP content blocks. Provider fields depend on the selected query.

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedOct 26, 2026

addedInput schema / properties / attribution / properties / attribution_window_days / anyOf

Added value: +[
+  {
+    "const": 7,
+    "type": "number"
+  },
+  {
+    "const": 14,
+    "type": "number"
+  },
+  {
+    "const": 30,
+    "type": "number"
+  }
+]

removedInput schema / properties / attribution / properties / attribution_window_days / enum
```
Removed value: -[
-  7,
-  14,
-  30
-]
```
removedInput schema / properties / attribution / properties / attribution_window_days / type
```
Removed value: -"number"
```

addedInput schema / properties / attribution / properties / view_through_attribution_window_days / anyOf

Added value: +[
+  {
+    "const": 0,
+    "type": "number"
+  },
+  {
+    "const": 1,
+    "type": "number"
+  }
+]

removedInput schema / properties / attribution / properties / view_through_attribution_window_days / enum
```
Removed value: -[
-  0,
-  1
-]
```
removedInput schema / properties / attribution / properties / view_through_attribution_window_days / type
```
Removed value: -"number"
```
removedInput schema / properties / until / $ref
```
Removed value: -"#/properties/since"
```
addedInput schema / properties / until / pattern
```
Added value: +"^\\d{4}-\\d{2}-\\d{2}$"
```
addedInput schema / properties / until / type
```
Added value: +"string"
```

changedOutput schema / properties / result / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "properties": {},
-    "type": "object"
-  },
-  {
-    "items": {},
-    "type": "array"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {},
+    "type": "object"
+  },
+  {
+    "items": {},
+    "type": "array"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "number"
+  },
+  {
+    "type": "boolean"
+  },
+  {
+    "type": "null"
+  }
+]

First observedv1.0.0Oct 23, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only/non-destructive/idempotent, but the description adds genuinely new behavior: pagination is followed up to maxRows with explicit truncation, attribution defaults to 30-day click and 1-day view on ad_event_time, CTR/CVR are fractions, and money is in major units of account currency. These conventions prevent real misinterpretation of results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four dense sentences, front-loaded with the read scope and followed by exclusions, semantics, and pagination. No filler, though some clauses (attribution defaults, unit conventions) are compressed into a very jargon-heavy run-on that takes a careful read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 9 parameters, nested attribution, and an output schema present, the description covers everything the schema does not carry: cross-metric/breakdown compatibility, unit conventions, attribution default semantics, and pagination/truncation behavior. Nothing needed for a correct call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description does add some meaning beyond the schema (breakdown restricted to delivery metrics, attribution defaults, inclusive date range), but it mostly summarizes defaults already documented per-parameter rather than deepening them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Read performance' at four named aggregation levels over inclusive account-local dates. It immediately distinguishes itself from openai_ads_get_conversion_insights by naming that sibling and its domain, so an agent can route correctly without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing rule: use openai_ads_get_conversion_insights for conversions by country or device. It also states the in-tool constraint that a single breakdown supports delivery metrics only, which tells the agent when not to combine breakdown with conversion metrics.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server