Add Meta Ad
User wants to add another ad/creative variation to an EXISTING ad set.
DO NOT USE to create a new campaign. For new campaigns:
- Video campaign -
create_meta_video_campaign - Image campaign -
create_meta_image_campaign - Carousel campaign -
create_meta_carousel_campaign
Common scenarios:
- A/B test ad copy: Different headlines, primary text, or CTAs for the same audience
- A/B test creatives: Different images or videos for the same audience
- Format testing within one audience: Image vs video ad in the same ad set
- Dynamic Creative (DCO): Multiple images + text variations in one ad — Meta auto-optimizes
KEY DISTINCTION — add_meta_ad vs add_meta_ad_set:
- Same audience, different creative/copy - use THIS tool (add_meta_ad)
- Different audience/targeting - use
add_meta_ad_setinstead (creates a new ad set)
Ads in the same ad set SHARE: targeting, budget, schedule, pixel tracking. Each ad has its OWN: creative (image/video/carousel), headline, primary text, CTA, landing page.
IMPORTANT: You need an ad_set_id from a previously created ad set. Use list_meta_ad_sets first if you don’t have the ad_set_id.
Supports all 3 ad types + Dynamic Creative:
image: Different image + copy variationvideo: Different video + copy variationcarousel: Different card set + copy variation- Dynamic Creative (DCO): Pass
image_urls(2-10 images),headlines(up to 5),primary_texts(up to 5),descriptions(up to 5). Meta tests ALL combinations and optimizes delivery automatically.
Dynamic Creative Optimization (DCO) workflow:
- Create ad set with
is_dynamic_creative=trueviaadd_meta_ad_set - Call this tool with
image_urls(list of 2-10 image URLs), plus optionalheadlines,primary_texts,descriptionsarrays - Meta will test all image × headline × text combinations and optimize
- DCO ad sets support only 1 ad — if the ad set already has is_dynamic_creative enabled, this tool auto-detects it Note: Cannot mix image_urls (DCO) with image_url (single image) or placement-specific images.
Standard workflow:
- Get ad_set_id from prior campaign creation or
list_meta_ad_sets - Write variant ad copy (different headline/primary_text/image)
- Call this tool with ad_set_id + new creative + copy
Authorizations
API key from https://adspirer.ai/keys. Prefix sk_live_. Treat as a secret — never commit.
Headers
Client-generated UUID to make writes idempotent. Strongly recommended for write tools. A repeat call with the same key returns the cached result instead of re-executing. Example: 550e8400-e29b-41d4-a716-446655440000
Body
All tool arguments are wrapped in an arguments object. The fields accepted inside arguments are listed below — required fields are marked with a red asterisk.
Input schema for adding a new ad to an existing ad set
Response
Tool executed successfully. data.text carries the human-readable result (markdown-friendly). data.quota shows your current usage against the plan limit. data.structured appears when the tool emits machine-parseable structured content. data.content appears for tools that return non-text blocks (images, resources).
Returned on HTTP 200. data.text is the primary human-readable output. data.quota is always present for billable calls. data.structured is set only when the tool emits machine-parseable structured content. data.content is set only when the tool emits non-text content blocks.