Skip to main content
Glama

List Ads

adsap_list_ads

List ALL ads inside an ad set or a campaign, live from Meta, including ads created today that have no delivery yet (which insights-based views miss). Pass exactly ONE of ad_set_id or campaign_id. Returns each ad's id, name, status, effective_status, created_time and creative id. Use this to enumerate ads before duplicating an ad set, auditing what exists, or picking an ad_id for adsap_get_ad / adsap_get_ad_status / adsap_replace_ad_creative. Deleted/archived ads are excluded unless you ask for them via effective_status. FIND ADS BY THEIR TEXT: pass text to get only the ads whose primary texts, headlines or descriptions contain that phrase, every variant included (carousel cards and Flexible ads too). Each ad comes back with text_matches (the field, the card number for a carousel card, and the full text) and current_texts: its complete primary_texts, headlines and descriptions, exactly as adsap_replace_ad_creative takes them. To change a text, send those complete lists with the edit applied (dry_run true first): no adsap_get_ad call is needed. A match that is not in current_texts (a carousel card, a Flexible ad, a catalog ad, an ad made from an existing post) cannot be changed with adsap_replace_ad_creative; say so. Upper and lower case are ignored, and line breaks or repeated spaces count as one space; emojis, punctuation and digits must match exactly. One call searches up to 500 ads; when meta.has_next is true, pass meta.paging_after as after with the same text to search the rest. Ads whose text Meta does not return are listed in meta.not_searchable. On catalog ads the headline is usually Meta's {{product.name}} placeholder, so a product name never matches. Use text instead of one adsap_get_ad per ad, for example to find every ad that still says an old offer before changing it. To change the same text in several ads, use adsap_replace_ad_text: it searches, previews every ad and applies in a few calls.

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": {
      "ad_account_id": "<ad_account_id>"
    },
    "name": "adsap_list_ads"
  }
}

Input Schema

NameRequiredDescriptionDefault
textNoOptional phrase to search for in the ads' primary texts, headlines and descriptions (all variants). Only the ads that contain it are returned, each with the matching texts and its complete current texts. Case is ignored; emojis and punctuation must match exactly.
afterNoPagination cursor from a previous response's meta.paging_after, to fetch the next page.
limitNoWithout text: max ads to return per page. Default 50, max 100. With text: the search stops after the page of 100 ads on which it has found at least this many matching ads (default 50).
ad_set_idNoAd set ID (numeric) to list the ads of. Pass exactly one of ad_set_id or campaign_id.
campaign_idNoCampaign ID (numeric) to list the ads of (across all its ad sets). Pass exactly one of ad_set_id or campaign_id.
ad_account_idYesAd account ID (act_xxx) the ad set or campaign belongs to. Required. Scopes the request and anchors the Meta budget check.
effective_statusNoOptional server-side filter on effective_status. Common values: ACTIVE, PAUSED, ADSET_PAUSED, CAMPAIGN_PAUSED, PENDING_REVIEW, DISAPPROVED, WITH_ISSUES, IN_PROCESS, ARCHIVED, DELETED. Omit to get every non-deleted ad (Meta's default excludes DELETED and ARCHIVED).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / ad_account_id / description
      Previous value: -"Ad account ID (act_xxx) the ad set or campaign belongs to. Required — scopes the request and anchors the Meta budget check."New value: +"Ad account ID (act_xxx) the ad set or campaign belongs to. Required. Scopes the request and anchors the Meta budget check."
    • changedInput schema / properties / limit / description
      Previous value: -"Max ads to return per page. Default 50, max 100."New value: +"Without text: max ads to return per page. Default 50, max 100. With text: the search stops after the page of 100 ads on which it has found at least this many matching ads (default 50)."
    • addedInput schema / properties / text
      Added value: +{
      +  "description": "Optional phrase to search for in the ads' primary texts, headlines and descriptions (all variants). Only the ads that contain it are returned, each with the matching texts and its complete current texts. Case is ignored; emojis and punctuation must match exactly.",
      +  "maxLength": 200,
      +  "minLength": 1,
      +  "type": "string"
      +}
  2. Added

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses liveness/recency behavior (today's non-delivering ads), default exclusion of DELETED/ARCHIVED, the 500-ad search cap, paging via meta.paging_after, the meta.not_searchable escape hatch, catalog placeholder limitation, and matching normalization rules (case-insensitive, whitespace collapsed, emojis/digits exact).

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

Conciseness3/5

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

Front-loaded with purpose and the one-of constraint, which is good, but the body is a single dense block that spends many sentences on the text-search/current_texts workflow that largely belongs to adsap_replace_ad_text. The inline caps headers help, yet there is redundancy between the "FIND ADS BY THEIR TEXT" section and the closing workflow advice.

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?

No output schema exists, and the description compensates by enumerating returned fields (id, name, status, effective_status, created_time, creative id, text_matches, current_texts) plus meta.has_next/paging_after/not_searchable. For a 7-parameter tool with two distinct modes, it covers mode selection, pagination, filtering, and matching edge cases.

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 coverage is 100%, so baseline is 3; the description still adds meaning by explaining how limit behaves differently with and without text, how after relates to meta.paging_after for repeated text searches, and how effective_status overrides Meta's default exclusion. It does not add new syntax detail for ad_account_id or the id parameters beyond the schema.

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?

Opens with a specific verb+resource+scope: "List ALL ads inside an ad set or a campaign, live from Meta," and explicitly distinguishes itself from insight-based views ("ads created today that have no delivery yet"). It also names the exact return fields and how it differs from adsap_get_ad and adsap_replace_ad_text.

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?

Gives explicit routing rules: pass exactly one of ad_set_id or campaign_id, use text "instead of one adsap_get_ad per ad," and defer bulk text edits to adsap_replace_ad_text. It also states concrete use cases (enumerate before duplicating an ad set, audit, pick an ad_id) and a when-not rule: a match absent from current_texts cannot be changed with adsap_replace_ad_creative.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources