Skip to main content
Glama
ChatGPT Ads MCP server

ChatGPT Ads MCP server

by get-mcp-ads

openai ads get mutation

openai_ads_get_mutation
Read-onlyIdempotent

Retrieve a write preview or receipt by mutation ID to inspect its status, approved native state, and result before confirming or resubmitting a change.

Instructions

Read a write preview or receipt held by this server process: its state, the native state it was approved against and the result. Receipts live in memory and a restart forgets them. Never resubmit a write whose state is UNKNOWN or APPLYING.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "adAccountId": "<adAccountId>",
      "mutationId": "<mutationId>"
    },
    "name": "openai_ads_get_mutation"
  }
}

Input Schema

NameRequiredDescriptionDefault
mutationIdYesThe confirmationToken or mutationId returned by a write preview or receipt.
adAccountIdYesThe adacct_ ID configured in OPENAI_ADS_ACCOUNT_ID. The API key is scoped to this one account; another ID is refused.

Output Schema

NameRequiredDescriptionDefault
resultYesOriginal 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.

  1. Changed2 schema fields changed
    • addedInput schema / properties / mutationId / pattern
      Added value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    • 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"
      +  }
      +]
  2. First observedv1.0.0

TDQS

A4.1/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing durability ('Receipts live in memory and a restart forgets them') and the specific state semantics that matter operationally (UNKNOWN/APPLYING must not be resubmitted). The readOnly/idempotent hints are already in the annotations, so this added context is exactly the kind that earns credit.

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

Conciseness5/5

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

Three sentences, front-loaded with what the tool reads, then the durability caveat, then the operational warning. Every sentence carries information an agent would otherwise have to discover by failure.

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 it is fair not to enumerate the returned structure, and the description still summarizes it plus the memory volatility caveat. What it omits is how the enumerated states relate to each other (what to do after APPLYING resolves), leaving a small but real gap for a status-polling 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 coverage is 100% and both parameters carry their own descriptions, so the baseline is 3. The description adds a little meaning by tying 'preview' and 'receipt' to the two possible identifiers, but it gives no format or lookup details beyond the schema.

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 and resource: 'Read a write preview or receipt held by this server process,' and enumerates the payload (state, approved-against native state, result). Among the many get_* siblings it is unmistakably the only mutation/receipt reader, though it never names a sibling explicitly.

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?

Context for use is clear: this is how you check on a preview or receipt you already hold, and 'Never resubmit a write whose state is UNKNOWN or APPLYING' gives a concrete decision rule for the polling loop. It stops short of naming alternatives such as openai_ads_get_bulk_job or openai_ads_get_write_context, so the routing is not fully explicit.

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