Replace ad creative (edit ad content) (`adsap_replace_ad_creative`)

Platform: Meta · Read or write: Write · Plan: Early Access · Consumes a task: Yes · Preview supported: Yes

What it does

Edits the content of a live Meta ad: primary text, headline, description, call to action, destination link, display link, URL parameters, and the image or video. Meta creatives cannot be edited in place, so the copilot builds a new creative and points the ad at it. The ad keeps its id. Ask for a preview first: it returns the before and after diff plus the current media slots.

When to use it

Use it to change what an existing ad says or shows: primary texts, headlines, description, call to action, link, display link, URL tags, or the image or video.
You need the ad_id and the ad_account_id. To change the ad’s name, status or schedule, use adsap_update_entity.
primary_texts and headlines are arrays. Send the complete list with your edits applied, because the list you send replaces the current one.
It supports a preview call. With dry_run set to true, it returns the before and after diff plus current_media, and writes nothing.
Media swaps are like for like and use creative library assets. For an ad with more than one media slot, send media with one entry per slot, in the current_media order.

Worked example

You ask

“Change the headline on ad 120210000000000 to ‘Now 30% off’ and keep everything else. Show me the diff first.”

The assistant calls `adsap_replace_ad_creative`


{
  "ad_id": "120210000000000",
  "ad_account_id": "act_1234567890",
  "creative_spec": {
    "headlines": ["Now 30% off"]
  },
  "dry_run": true
}

Adsap returns

The field names are the ones Adsap returns. The values are examples.


{
  "ok": true,
  "dry_run": true,
  "ad_id": "120210000000000",
  "ad_name": "Spring sale, image 1",
  "current_creative_id": "120210000000006",
  "changes": [
    {
      "field": "primary_texts",
      "current_value": ["Our spring collection is here."],
      "new_value": ["Our spring collection is here."],
      "will_change": false
    },
    {
      "field": "headlines",
      "current_value": ["New season styles"],
      "new_value": ["Now 30% off"],
      "will_change": true
    }
  ],
  "total_would_change": 1,
  "current_media": [
    {
      "kind": "image",
      "index": 0,
      "label": null,
      "image_hash": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "thumbnail_url": null
    }
  ]
}

How to read it

changes lists every editable text field: primary_texts, headlines, description, cta_type, link, display_link and url_tags. The example shows two of the seven. Fields you did not send keep their current value, so will_change is false for them. total_would_change counts the fields that differ.

current_media describes the ad’s media slots in order. Each slot has a kind of image or video and its current image_hash or video_id. Use that order to build a media swap. The full response also has a human_readable_summary sentence, left out here. To apply the edit, the assistant repeats the call with dry_run set to false. The ad keeps its ID and gets a new creative.

Parameters

Descriptions are shortened from the tool schema. Your assistant sees the full text.

Name	Type	Required	Description
`ad_id`	string	Yes	The Meta AD id to edit (the ad, not the creative). The ad keeps this id; only its creative is replaced.
`ad_account_id`	string	Yes	act_<digits>.
`creative_spec`	object	Yes	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).
`creative_spec.primary_texts`	array of string	No	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.
`creative_spec.headlines`	array of string	No	Full ordered set of headlines, WITH your edits applied. Send ALL of them: unedited entries are preserved. Omit to leave headlines unchanged.
`creative_spec.description`	string	No	Link description (single value). Omit to leave unchanged.
`creative_spec.cta_type`	string	No	Call-to-action button enum, e.g. SHOP_NOW, LEARN_MORE, SIGN_UP. Omit to leave unchanged.
`creative_spec.link`	string	No	Destination URL. Omit to leave unchanged.
`creative_spec.display_link`	string	No	The display link / caption domain shown on the ad (e.g. example.com). Omit to leave unchanged.
`creative_spec.url_tags`	string	No	URL tracking parameters (UTM) appended to the destination, e.g. ‘utm_source=facebook&utm_medium=cpc’. Omit to leave unchanged.
`creative_spec.image_hash`	string	No	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.
`creative_spec.video_id`	string	No	Single-video shorthand: a creative-library video id to swap the ad’s one video. For multi-asset ads use `media`. Like-for-like only.
`creative_spec.media`	array of object or null	No	Multi-slot media swap. One entry per existing media slot, IN THE ORDER returned by a dry_run’s current_media; null = keep that slot unchanged. Each entry sets image_hash OR video_id matching that slot’s type.
`dry_run`	boolean	No	Preview only: the request is validated and the resolved payload returned, nothing is created or changed.

Example prompts

“Change the headline on the Blue Sneaker ad to ‘Now 30% off’ and keep everything else.”
“Swap the image on the Blue Sneaker ad for the new lifestyle shot from the creative library.”
“Preview replacing the destination URL on this ad with the new landing page.”

Notes

Editing a spending ad can reset its likes, comments and shares and restart the learning phase. Media swaps are like for like: image to image, video to video, from the creative library only.

adsap_create_ad_from_ig_post: Turn an existing Instagram post, video, or reel into an ad inside an EXISTING ad set: Meta Ads Manager’s “Use existing post”.
adsap_get_ad_library_snapshot: SHOW what Ad Library ads ACTUALLY LOOK LIKE (creative, copy, page name), in a SELF-CONTAINED card.
adsap_get_ad_preview: Render a pixel-accurate visual preview of an existing Meta ad (real Meta render; video ads also get an animated clip in the interactive…
adsap_get_creative_performance: Ranked creative performance analysis with fatigue detection.
adsap_get_import_status: Check progress of a Meta historical-asset import started with adsap_import_account_creatives: status, phase (images then videos)…
adsap_get_preview_clip: Fetch the animated placement-preview clip (recorded video of the real Meta preview) for an ad+placement previously rendered with…
adsap_get_upload_status: Check status of an async video upload.
adsap_import_account_creatives: Import ALL historical creative assets (images + videos) that already exist in a Meta ad account into the Adsap Creative Library.
adsap_list_creative_assets: List uploaded Meta creative images and videos in the ad account asset library.
adsap_list_drive_files: Browse Google Drive for creative image/video files to upload to Meta.
adsap_list_dropbox_files: Browse Dropbox for creative image/video files to upload to Meta.
adsap_list_ig_media: List an Instagram account’s recent media/posts (live from Meta): the posts, reels, and stories that can be promoted.
adsap_search_ad_library: Search Meta’s public Ad Library for ads (competitor research / ad transparency).
adsap_upload_creative: Upload image/video from Google Drive or Dropbox to a Meta ad account.

Guide

Read Creatives for the workflow around this tool, and the Tool reference for every tool.

The Meta Ads MCP server page shows how to connect Meta Ads to Claude, ChatGPT or Perplexity.

Replace ad creative (edit ad content) (adsap_replace_ad_creative)