Skip to main content
Glama

Find and replace text in ads

adsap_replace_ad_text

Change the same text in many Meta ads at once, for example an old offer or a number that changed. Works on the ads of ONE ad set or ONE campaign per call. Step 1, preview (dry_run true, the default): pass find, replace_with and ad_set_id or campaign_id. It searches up to 500 ads with the same rule as adsap_list_ads text (upper and lower case ignored, line breaks and repeated spaces count as one space, emojis, punctuation and digits exact), replaces every occurrence by replace_with exactly as typed, and previews each ad without changing anything. It returns preview_id, the ads that would change with each text before and after, held (ads where another setting would also change), cannot_change (texts Adsap cannot change: carousel cards, Flexible ads, catalog ads, ads made from an existing post) and meta.active_ads (how many of these ads are running). Show the user ONE list: every ad with its before and after text, then the held and cannot_change ads with their reasons. Each changed ad gets a new creative: on a running ad this can restart learning and reset the likes and comments shown, so when meta.active_ads is above 0 say so. Apply only after the user confirms. Step 2, apply: pass the same ad_account_id, dry_run false and preview_id (within 30 minutes). Held ads are left out unless their ids are in ad_ids, and only after the user agreed to the other setting change; pass ad_ids also to apply only some ads. Each call changes ads for about 35 seconds and answers with what changed; when meta.remaining is above 0, call again with the same preview_id until it is 0. An ad changed by someone else after the preview is skipped, never overwritten. Every text you do not ask to change stays as it is, and so do the enhancements, Shop, the button, the link and the media. Say nothing about the settings checks when they find nothing. Only for ads listed under warnings (after the apply): tell the user which settings Meta reports as different, using the names and values returned. More than 50 ads to change: apply these, then preview again for the rest. One task is counted per ad changed. To change other fields (link, button, media) or one ad in a custom way, use adsap_replace_ad_creative.

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_replace_ad_text"
  }
}

Input Schema

NameRequiredDescriptionDefault
findNoPreview only: the text to find. Upper and lower case and extra spaces are ignored; emojis, punctuation and digits must match exactly.
afterNoPreview only: meta.paging_after from a previous preview, to search the ads after the first 500.
ad_idsNoApply only: change only these ads of the preview. Held ads are changed only when named here.
fieldsNoPreview only: which texts to change. Default: all three (primary_text, headline, description).
dry_runNotrue (default) = preview, nothing is changed. false = apply a preview (needs preview_id).
ad_set_idNoPreview only: the ad set whose ads to search (numeric). Pass exactly one of ad_set_id or campaign_id.
preview_idNoApply only: the preview_id returned by the preview.
campaign_idNoPreview only: the campaign whose ads to search, across its ad sets (numeric). Pass exactly one of ad_set_id or campaign_id.
replace_withNoPreview only: the new text, used exactly as typed (case included). An empty string removes the text found.
ad_account_idYesAd account ID (act_xxx). Required in both steps.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.8/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 thoroughly: it discloses that each changed ad gets a new creative, that running ads may restart learning and reset shown likes/comments, that previews expire after 30 minutes, that concurrent edits are skipped rather than overwritten, and that calls process ~35 seconds of ads with meta.remaining signaling continuation. It also explains the held/cannot_change classifications and the 50-ad batch pattern.

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?

The description is long but front-loads the core action and organizes the rest into labeled Step 1 and Step 2, matching the actual workflow. Some instructions (e.g., 'Say nothing about the settings checks when they find nothing') are useful but dense, and the block could be trimmed slightly without losing meaning.

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?

For a 10-parameter, two-phase mutation tool with no output schema and no annotations, the description covers return payloads (preview_id, held, cannot_change, meta.active_ads, meta.remaining, warnings), error/skip behavior, and confirmation etiquette. Nothing an agent needs to invoke it correctly is missing.

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 the baseline is 3; the description adds operational meaning beyond the schema, notably the 30-minute preview_id validity, the sequencing of find/replace_with only at preview, and ad_ids as the mechanism for including held or partial ads at apply. Most of this is reinforcement of schema text rather than new semantics, keeping it below 5.

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 first sentence states a specific verb and resource ('Change the same text in many Meta ads at once') and gives a concrete use case. It also explicitly delineates the boundary against adsap_replace_ad_creative for other fields or single custom edits, so an agent can distinguish it from siblings without opening a schema.

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?

It prescribes an explicit two-step flow (preview with dry_run true, then apply with dry_run false and preview_id), states the one-ad-set-or-one-campaign scope per call, and names the alternative tool for link/button/media changes. When-to-use and when-not-to-use are both covered.

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