ChatGPT Ads MCP server

openai ads get audience operation

openai_ads_get_audience_operation

Read-onlyIdempotent

Read the lifecycle state of a single custom audience operation, preserving native fields and pagination, to track its progress or completion.

Instructions

Read the lifecycle state of one custom audience operation. Native fields and pagination are preserved. See openai_ads_get_write_schema for nested request fields.

Input Schema

Name	Required	Description
`adAccountId`	Yes	The adacct_ ID configured in OPENAI_ADS_ACCOUNT_ID. The API key is scoped to this one account; another ID is refused.
`operation_id`	Yes	Exact native operation_id. The entity must belong to the configured ad account.
`custom_audience_id`	Yes	Exact native custom_audience_id. The entity must belong to the configured ad account.

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

A3.7/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is fully covered. The description adds only 'Native fields and pagination are preserved', a partial note on output fidelity that is largely redundant with the existing output schema. It says nothing about rate limits, eventual consistency of operation state, or what a terminal vs in-progress state looks like.

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 short sentences with the purpose front-loaded; no filler. The final cross-reference sentence is slightly off-target for a read-only tool, but it is brief and does not obscure the main statement.

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 need not explain return values, and rich annotations carry the safety profile, so the remaining job is purpose plus scoping and both are stated. What is missing is whether the returned lifecycle state can be polled to completion and how it relates to the list-level sibling, which would matter for an operations-status tool.

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 description coverage is 100% and all three required parameters are documented in the schema, including the account-scoping constraint ('another ID is refused'). The description contributes nothing about operation_id or custom_audience_id, so baseline 3 applies.

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?

The description gives a specific verb and resource ('Read the lifecycle state of one custom audience operation'), and the word 'one' plus 'lifecycle state' distinguishes it from the plural sibling openai_ads_get_audience_operations. An agent can pick the right tool 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 Guidelines3/5

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

Usage is only implied by the singular scope; there is no explicit instruction on when to call this versus openai_ads_get_audience_operations (polling an in-flight op) or openai_ads_get_mutation. The one routing hint given ('see openai_ads_get_write_schema for nested request fields') points at write-side schema, which does not help an agent decide when to read an operation.

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

Deploy Server