Skip to main content
Glama

Replace Ad Creative (edit ad content)

adsap_replace_ad_creative

DESTRUCTIVE. Edit the CONTENT of an existing Meta ad: primary text, headline, description, CTA, destination link, display link, UTM url_tags, the image/video itself, and Shop (shop: 'on' or 'off'). Meta creatives are immutable, so this builds a NEW creative and repoints the ad: the ad keeps its id but gets a new creative_id and the old creative is orphaned. Editing a live/spending ad can reset its social proof (likes/comments/shares) and restart the learning phase. Text fields are ARRAYS: send the COMPLETE set with your edits applied; entries you don't change are preserved verbatim (primary_texts, headlines, descriptions). To change the same text in several ads, use adsap_replace_ad_text instead: one preview and one confirmation for all of them. Media swaps use creative-library assets only and are like-for-like (image->image, video->video); for multi-image ads (square + vertical) use the media array, one entry per slot. ALWAYS call with dry_run: true first: the preview returns the before/after diff AND the current media slots (use those to build a media swap), then dry_run: false to apply. When the ad's format has no room for a change (for example two primary texts on an ad that holds one), the answer is EDIT_NOT_SUPPORTED and nothing is changed: tell the user, using the message as returned. Everything you do not ask to change stays exactly as it is: enhancements, Shop, the other text variations, the button and the media. Both answers check it. Shop: off means people always go to the website; on means Meta can send people to the business's Facebook or Instagram shop instead, if the business has one. The preview's settings_check.shop is the ad's current Shop setting and settings_check.shop_applies says whether Shop applies to the ad at all (website ads only). Say nothing about the check when it finds nothing. Only when settings_check.unexpected (preview) or after_apply_check.unexpected (apply) is above 0: tell the user which settings would change or changed, using the setting names and values as returned, and before an apply get the user's confirmation again. Entries marked expected: true are Meta bookkeeping (a new id Meta gives a video on every video edit, a retired summary switch Meta no longer accepts): never mention them unless the user asks.

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_id": "<ad_id>",
      "ad_account_id": "<ad_account_id>",
      "creative_spec": "<creative_spec>"
    },
    "name": "adsap_replace_ad_creative"
  }
}

Input Schema

NameRequiredDescriptionDefault
ad_idYesThe Meta AD id to edit (the ad, not the creative). The ad keeps this id; only its creative is replaced.
dry_runNotrue = preview the before->after diff without writing anything. ALWAYS run dry_run: true first.
ad_account_idYesact_<digits>.
creative_specYesThe content fields to change. Text fields are ARRAYS: send the complete set with edits applied; unchanged entries are kept. Media swaps use creative-library assets only (image->image, video->video). At least one field is required.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / creative_spec / properties / shop
      Added value: +{
      +  "description": "Meta's Shop setting. off = people always go to the website. on = Meta can send people to the business's Facebook or Instagram shop instead of the website, if the business has a shop. Omit to keep the ad's current Shop setting (the preview's settings_check.shop). Website ads only: on WhatsApp, lead form or messaging ads the answer is EDIT_NOT_SUPPORTED.",
      +  "enum": [
      +    "on",
      +    "off"
      +  ],
      +  "type": "string"
      +}
  2. Changed6 schema fields changed
    • changedInput schema / properties / creative_spec / description
      Previous value: -"The content fields to change. Text fields are ARRAYS — send the complete set with edits applied; unchanged entries are kept. Media swaps use creative-library assets only (image->image, video->video). At least one field is required."New value: +"The content fields to change. Text fields are ARRAYS: send the complete set with edits applied; unchanged entries are kept. Media swaps use creative-library assets only (image->image, video->video). At least one field is required."
    • changedInput schema / properties / creative_spec / properties / description / description
      Previous value: -"Link description (single value). Omit to leave unchanged."New value: +"The FIRST description only (single value); further descriptions stay as they are. To change any of them, send descriptions instead. Omit to leave unchanged."
    • addedInput schema / properties / creative_spec / properties / descriptions
      Added value: +{
      +  "description": "Full ordered set of descriptions, WITH your edits applied (the list adsap_list_ads returns in current_texts.descriptions). Send ALL of them: unedited entries are preserved. Use this or description, not both. Omit to leave descriptions unchanged.",
      +  "items": {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "minItems": 1,
      +  "type": "array"
      +}
    • changedInput schema / properties / creative_spec / properties / headlines / description
      Previous value: -"Full ordered set of headlines, WITH your edits applied. Send ALL of them — unedited entries are preserved. Omit to leave headlines unchanged."New value: +"Full ordered set of headlines, WITH your edits applied. Send ALL of them: unedited entries are preserved. Omit to leave headlines unchanged."
    • changedInput schema / properties / creative_spec / properties / image_hash / description
      Previous value: -"Single-image shorthand: a creative-library image hash to swap the ad's one image. For multi-image ads (e.g. square + vertical) use `media` instead. Like-for-like only — you can't put an image on a video ad. The image must already be in the creative library."New value: +"Single-image shorthand: a creative-library image hash to swap the ad's one image. For multi-image ads (e.g. square + vertical) use `media` instead. Like-for-like only: you can't put an image on a video ad. The image must already be in the creative library."
    • changedInput schema / properties / creative_spec / properties / primary_texts / description
      Previous value: -"Full ordered set of primary-text (body) variations, WITH your edits applied. Send ALL of them — entries you don't change are preserved verbatim. Omit to leave every primary text unchanged."New value: +"Full ordered set of primary-text (body) variations, WITH your edits applied. Send ALL of them: entries you don't change are preserved verbatim. Omit to leave every primary text unchanged."
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full burden and does so: it flags DESTRUCTIVE up front, explains that creatives are immutable so a new creative_id is created and the old one orphaned, and warns that editing a live ad can reset social proof and restart the learning phase. It also documents the settings_check/after_apply_check confirmation protocol and which 'unexpected' entries are Meta bookkeeping to suppress.

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?

Front-loaded with the DESTRUCTIVE warning and the dry_run-first workflow, so the highest-risk information arrives first. It is dense and long, with the Shop definition and settings_check guidance restated in several places, which costs a point but each block is still actionable rather than filler.

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 destructive nested-object mutation with no annotations and no output schema, the definition covers everything an agent needs: irreversibility, ad-vs-creative id semantics, array replacement rules, media slot ordering, the preview/apply cycle, and the exact conditions for re-confirming with the user. Nothing material is left to inference.

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, but the description adds real meaning beyond the schema: the array fields must be sent as a COMPLETE set with unedited entries preserved, media swaps are like-for-like and require reading current_media from a dry_run first, and single-field shorthands (image_hash, video_id, description) versus their list counterparts. Some of this restates the schema's own wording, which keeps it below a 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?

States a specific verb and resource ('Edit the CONTENT of an existing Meta ad') and enumerates the editable fields (primary text, headline, description, CTA, link, display link, url_tags, media, Shop). It also explicitly distinguishes itself from the sibling adsap_replace_ad_text by scope (one ad vs. several ads).

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 when-to-use routing ('To change the same text in several ads, use adsap_replace_ad_text instead'), a mandatory workflow ('ALWAYS call with dry_run: true first ... then dry_run: false'), and a case-specific alternative ('for multi-image ads use the `media` array'). It even covers the failure path: EDIT_NOT_SUPPORTED means nothing changed and the user must be told.

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