Skip to main content
Glama
logly

mureo

by logly
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

meta_ads_audiences_create

Create a Meta Ads Custom Audience for targeted advertising. Choose website, customer, or app data sources, set retention, and get a new audience_id for use in ad campaigns.

Instructions

Creates a Custom Audience in a Meta Ads account. Returns the new audience_id. Mutating — not automatically reversible; record before-state with mureo_state_action_log_append if you may need to roll back. Subtype controls the data source: WEBSITE audiences require a pixel_id and an event rule; CUSTOM audiences accept a manually supplied rule or a customer list upload (the upload path is handled out-of-band by Meta). For similarity-expanded reach use meta_ads_audiences_create_lookalike on top of this audience.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesAudience name shown in Ads Manager. Must be unique within the account.
ruleNoAudience rule definition (Meta rule JSON schema). When omitted with subtype=WEBSITE, a default PageView rule scoped to the supplied pixel is auto-generated. See Meta Marketing API docs for rule syntax — supports url filters, event parameters, and compound boolean operators.
reasonNoWhy this change is being made: one or two sentences naming the evidence and the expected effect. Stored in the journal and on the action_log entry this call produces, for the operator and the next session.
subtypeNoAudience type hint. WEBSITE auto-generates a PageView rule from the linked pixel when `rule` is omitted; CUSTOM requires an explicit rule or a customer-list upload; APP requires an app_id. Default CUSTOM when omitted.
pixel_idNoMeta Pixel ID to source events from. Required for subtype=WEBSITE. Find via meta_ads.pixels.list.
account_idNoMeta Ads account ID in the format 'act_XXXXXXXXXX' (e.g. 'act_1234567890'). Optional — falls back to META_ADS_ACCOUNT_ID from the configured credentials. The leading 'act_' prefix is required.
descriptionNoOptional free-text description stored with the audience. Not visible to end users.
retention_daysNoHow long a matched user stays in the audience after their last qualifying event. Default 30. Meta caps at 180 days.
customer_file_sourceNoSource declaration required by Meta for compliance. USER_PROVIDED_ONLY (default) — data came from the advertiser's own first-party sources; PARTNER — from a data provider; BOTH — mixed. Meta uses this to set legal-basis defaults.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.20.0
    • addedInput schema / properties / reason
      Added value: +{
+  "description": "Why this change is being made: one or two sentences naming the evidence and the expected effect. Stored in the journal and on the action_log entry this call produces, for the operator and the next session.",
+  "maxLength": 500,
+  "type": "string"
+}
  2. Changed1 schema field changedv0.10.37
    • addedInput schema / additionalProperties
      Added value: +false
  3. Addedv0.9.12
  4. Removedv0.9.6
  5. Addedv0.9.2
  6. Removedv0.9.1
  7. Addedv1.0.5

TDQS

A5/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden and delivers strongly: it flags the operation as mutating, states it is not automatically reversible, and directs the agent to mureo_state_action_log_append for rollback needs. It also discloses defaults, auto-generation of PageView rules, the out-of-band upload path, and compliance semantics for customer_file_source.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: purpose, return value, mutability and rollback, subtype behavior, defaults, and the lookalike alternative are all covered without redundancy. It is front-loaded with the core action and output.

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 9-parameter mutation tool with no annotations and no output schema, the description is remarkably complete. It covers the return value, side effects, revert strategy, subtype-specific requirements, defaults, compliance considerations, and points to external docs for rule syntax. Nothing essential that an agent would need to call it correctly is missing.

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

Parameters5/5

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

Although the schema has 100% description coverage, the tool description adds substantial meaning beyond the schema: it explains account_id fallback to META_ADS_ACCOUNT_ID, the auto-generated default rule for WEBSITE, the required pixel_id for WEBSITE, the compliance role of customer_file_source, and the retention cap. This materially helps an agent choose and fill parameters correctly.

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 description opens with a specific verb and resource: 'Creates a Custom Audience in a Meta Ads account. Returns the new audience_id.' It clearly identifies what the tool does and distinguishes it from siblings like meta_ads_audiences_create_lookalike and meta_ads_audiences_delete.

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?

The description explicitly explains when to use this tool versus the lookalike alternative: 'For similarity-expanded reach use meta_ads_audiences_create_lookalike on top of this audience.' It also provides subtype-specific usage guidance, such as when WEBSITE requires a pixel_id and rule versus when CUSTOM accepts a manual rule or upload.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools