Skip to main content
Glama

Manage Custom Audience (create / update / delete)

adsap_manage_custom_audience

Create, update, or delete a RULE-BASED custom audience: Website (pixel/site visitors), Engagement (Instagram/Facebook engagers), Lookalike (people similar to an existing audience), or App (mobile app users). Completes the pair with adsap_list_custom_audiences (read). For create, pick an audience_type and pass a rule (or lookalike fields). dry_run defaults TRUE: call once to preview, then again with dry_run:false to apply. Delete is PERMANENT and auto-pauses any ad sets using the audience — the dry_run preview lists them first. NOTE: this covers rule-based audiences only; uploading a customer list (hashed emails/phones) is NOT supported here. The account must accept Meta's Custom Audience Terms of Service once before any audience can be created (Meta returns an accept URL if not).

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

Input Schema

NameRequiredDescriptionDefault
nameNoRequired for action=create. The audience name shown in Ads Manager.
ruleNoRequired for create when audience_type is website/engagement/app (NOT lookalike). A JSON-ENCODED STRING (not an object). Structure: {"inclusions":{"operator":"or","rules":[<rule>]}} (optional top-level "exclusions" with the same shape). Each <rule>: {"event_sources":[{"type":"<TYPE>","id":"<ID>"}],"retention_seconds":<n>,"filter":{"operator":"and","filters":[...]},"template":"<TEMPLATE>"}. WEBSITE: type "pixel" (id from adsap_list_meta_assets pixels). All visitors → template "ALL_VISITORS" + filter {"field":"url","operator":"i_contains","value":""}. Specific pages → template "VISITORS_BY_URL" + filter {"field":"url","operator":"i_contains","value":"<keyword>"}. Standard events → template "VISITORS_BY_URL" + filter {"field":"event","operator":"eq","value":"Purchase"/"AddToCart"/"Lead"/...}. ENGAGEMENT (Instagram): type "ig_business" (id = Instagram account id from adsap_list_meta_assets), filter {"field":"event","operator":"=","value":"ig_business_profile_all"} (all engagers). APP: type "app" (app id), template "MACA_APP_LAUNCHED_USERS" + filter {"field":"event","operator":"=","value":"fb_mobile_activate_app"}. retention_seconds = how long to keep members (max 15552000 = 180 days; 2592000 = 30 days).
ratioNoLookalike only. Share of the population to match, 0.01 (1%, closest/smallest) to 0.20 (20%, broadest/largest). Defaults to 0.01.
actionYesWhat to do: "create" a new rule-based audience, "update" an existing one's name/description/rule, or "delete" one permanently.
dry_runNoTRUE (default) = preview only, nothing is written. For delete, the preview also lists which ad sets would be auto-paused. Set false to actually create/update/delete.
prefillNoOptional (website/engagement/app create). TRUE backfills the audience with historical data. Defaults to Meta's default (true).
descriptionNoOptional description for the audience (create or update).
ad_account_idYesact_<digits>. The ad account that owns (or will own) the custom audience. Used for ownership, workspace resolution, and Meta API budget.
audience_typeNoRequired for action=create. "website" = pixel/site visitors (WCA), "engagement" = people who engaged with your Instagram/Facebook (ECA), "lookalike" = people similar to an existing audience (LAL), "app" = mobile app users (MACA).
lookalike_countryNoLookalike only. ISO country code (e.g. "US", "FR", "GB"). NO LONGER USED: Meta v27.0 rejects a country on lookalike creation, so Adsap accepts this field for backward compatibility and does not send it. A lookalike has no location of its own; delivery locations come from the ad sets that use the audience, so set location targeting on those ad sets.
custom_audience_idNoRequired for action=update and action=delete. The numeric id of the existing custom audience. Get it from adsap_list_custom_audiences.
origin_audience_idNoRequired for create when audience_type=lookalike. The numeric id of the SEED audience to model on (a WEBSITE/ENGAGEMENT/APP/CUSTOM audience — NOT another lookalike). Get it from adsap_list_custom_audiences.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / lookalike_country / description
      Previous value: -"Lookalike only. ISO country code (e.g. \"US\", \"FR\", \"GB\"). DEPRECATED BY META (v26 / all versions from 2026-09-01): the API silently ignores it and creates a countryless parent lookalike — delivery locations come from the ad sets that use the audience. Still accepted for backward compatibility; Meta returns a deprecation warning."New value: +"Lookalike only. ISO country code (e.g. \"US\", \"FR\", \"GB\"). NO LONGER USED: Meta v27.0 rejects a country on lookalike creation, so Adsap accepts this field for backward compatibility and does not send it. A lookalike has no location of its own; delivery locations come from the ad sets that use the audience, so set location targeting on those ad sets."
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations present the description carries the full burden, and it does: dry_run defaults to TRUE so nothing writes by default, delete is PERMANENT and auto-pauses ad sets using the audience, the dry-run preview enumerates those ad sets, and creation is blocked until Meta's ToS is accepted (returning an accept URL). These are exactly the destructive and prerequisite behaviors an agent cannot infer from the schema.

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 purpose, then alternatives, then workflow, then the destructive warning and ToS caveat — a sensible priority order for an agent deciding whether to call. Every sentence carries information, though the dry_run two-call instruction partly duplicates the schema's dry_run description.

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 12-parameter mutation tool with no annotations and no output schema, the description supplies the missing pieces: safety profile, default-dry-run workflow, prerequisite ToS step, delete side effects on dependent ad sets, and the customer-list exclusion. An agent has what it needs to invoke this correctly on the first attempt.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema already explains every parameter in depth, including rule JSON structure, lookalike ratio bounds, and the deprecated lookalike_country. The description adds little parameter-level meaning beyond restating dry_run and the create-time audience_type/rule pairing, so the baseline of 3 applies.

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 set and resource ('Create, update, or delete a RULE-BASED custom audience') and enumerates the four supported audience types (Website, Engagement, Lookalike, App). It also draws the negative boundary that matters most — customer-list upload with hashed emails/phones is explicitly out of scope — so an agent can rule this tool in or out without reading the 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?

Names the read sibling (adsap_list_custom_audiences) and states the pairing, tells the agent to pick an audience_type plus rule or lookalike fields for create, and prescribes the exact two-call dry-run workflow (preview first, then dry_run:false). It also surfaces the one-time Custom Audience ToS prerequisite, which is the most likely cause of a failed first create.

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