ChatGPT Ads MCP server

openai ads list ad creatives

openai_ads_list_ad_creatives

Read-onlyIdempotent

List chat card ad creatives for an ad account or one ad group, or read up to 60 exact ad IDs, with pagination and image URL refresh.

Instructions

List chat card creatives of the account or of one ad group, 20 ads per page, or read up to 60 exact adIds. Each item has the native file_id, signed image_url, title, body, destination and review status. An expired image link is refreshed with one ad read. Follow nextCursor when hasMore.

Input Schema

Name	Required	Description
`adIds`	No	Up to 60 exact ad IDs to read. Cannot be combined with adGroupId or after.
`after`	No	The nextCursor of the previous page, only when hasMore is true.
`limit`	No	Ads per page, 1 to 20. Defaults to 20.
`adGroupId`	No	Optional ad group (adgrp_) to list. Omit to list ads across the account.
`adAccountId`	Yes	The adacct_ ID configured in OPENAI_ADS_ACCOUNT_ID. The API key is scoped to this one account; another ID is refused.

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.

Changed1 schema field changedOct 26, 2026

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

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered and the description spends its budget on real behavior: 20 items per page, a 60-id batch ceiling, sequential paging via nextCursor/hasMore, and the fact that an expired signed image_url is refreshed by a single ad read. That last detail is non-obvious side-effect disclosure an agent would otherwise not know.

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?

Three densely packed sentences, front-loaded with the core listing scope, and each one carries actionable information about paging, return fields, or link refresh. The enumeration of return fields is marginally redundant given an output schema exists, but it is compact enough not to waste space.

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

Completeness4/5

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

With an output schema present the description needn't document return shape, and it still adds pagination termination rules and the batch-read mode that the schema alone would not make obvious. Account scoping is left to the schema's adAccountId text, so the description is complete but not exhaustive for a 5-parameter listing tool.

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

Parameters4/5

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

Schema description coverage is 100%, so baseline is 3; the description goes further by tying pagination to concrete values ("20 ads per page") and by explaining that after should be followed from nextCursor when hasMore is true, plus the 60-id cap on adIds. It adds page-size and paging-loop semantics beyond the field-level schema text.

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

Purpose4/5

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

States a specific verb plus resource ("List chat card creatives") and enumerates the three access modes: account-wide, one ad group, or up to 60 exact adIds. An agent immediately knows the scope and shape of the call. It does not explicitly distinguish itself from the sibling openai_ads_get_ads / openai_ads_get_ad, which is the only thing keeping it from a 5.

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

Usage Guidelines4/5

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

"List ... of the account or of one ad group, ... or read up to 60 exact adIds" clearly frames the mutually exclusive invocation modes, and the schema reinforces that adIds cannot combine with adGroupId or after. There is no explicit when-not guidance or named alternative among the large set of sibling listing tools.

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

Deploy Server