Skip to main content
Glama
ChatGPT Ads MCP server

ChatGPT Ads MCP server

by get-mcp-ads

openai ads get ad groups

openai_ads_get_ad_groups
Read-onlyIdempotent

Lists ad groups in a campaign with cursor paging and optional name filtering, returning native IDs and serving issues when requested.

Instructions

List one page of ad groups in a campaign. Native ad group IDs start with adgrp_. Follow last_id only when has_more is true.

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>",
      "campaignId": "<campaignId>"
    },
    "name": "openai_ads_get_ad_groups"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoReturn only entities whose name matches this text, 3 to 1,000 characters.
afterNoNext-page cursor: the previous page's last_id, only when has_more is true.
limitNoPage size, 1 to 500. Defaults to 100.
orderNoSort by creation time. Defaults to desc, newest first.desc
beforeNoPrevious-page cursor: a first_id returned by a later page.
includeNoAdd serving_issues to receive native reasons why this entity cannot serve. A paused state is intentional, not an issue.
campaignIdYesNative campaign ID (cmpn_) in the configured account.
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. Changed1 schema field changed
    • 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

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds behavior annotations don't: results are returned one page at a time, IDs carry the adgrp_ prefix, and cursors should only be followed when has_more is true. It stops short of noting default page size or rate limits, which the schema covers anyway.

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 short sentences, front-loaded with the action and scope, then the two facts an agent needs (ID format, cursor rule). No filler or repetition of schema content.

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 and full annotation coverage, the description does not need to explain return values. It covers pagination behavior, which is the main complexity for an 8-parameter listing tool. Only the absence of any filtering or sorting hint keeps it from being fully complete.

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%, so every parameter including after, before, limit and order is already documented. The description's mention of last_id and has_more adds useful ties between response fields and the after cursor but nothing beyond that. Baseline 3 applies where the schema does the heavy lifting.

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?

Uses a specific verb and resource with scope: "List one page of ad groups in a campaign." That clearly separates it from the singular openai_ads_get_ad_group sibling, though it never names the sibling explicitly. Purpose is unambiguous but differentiation is left implicit.

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?

The sentence "Follow last_id only when has_more is true" gives real usage guidance for pagination, which is the main way this tool gets misused. However, it says nothing about when to choose this lister versus openai_ads_get_ad_group or how it relates to openai_ads_get_ads; tool-selection guidance is only implied by the plural/scoped naming.

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