Skip to main content
Glama
logly

mureo

by logly
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

meta_ads_audiences_create_lookalike

Create a Lookalike Audience from an existing source audience to reach new people similar to your best customers. Returns the new audience ID for immediate use in ad campaigns.

Instructions

Creates a Lookalike Audience from an existing source audience. 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. Lookalikes typically populate within 24–72h; the approximate_count remains 0 until Meta finishes the similarity build. ratio=0.01 gives the top 1% most similar users in the target country (smallest, highest match); ratio=0.10 gives top 10% (larger reach, looser match). For the base audience list use meta_ads_audiences_list.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesAudience name shown in Ads Manager. Must be unique within the account.
ratioYesSimilarity ratio — fraction of the target country's population to include. 0.01 = top 1% (tightest match, smallest audience); 0.20 = top 20% (loosest, largest). Meta caps at 0.20.
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.
countryYesTarget country ISO code(s) for the lookalike expansion. Accepts a single code string (e.g. 'JP') or a list (e.g. ['JP', 'KR']). Lookalike reach is always scoped to the specified country/countries.
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.
starting_ratioNoLower bound of the ratio range. Default 0.0. Advanced: set > 0 to carve out a tiered lookalike that excludes the top-similarity slice (e.g. starting_ratio=0.01, ratio=0.05 = users ranked 1–5% in similarity, excluding the top 1%).
source_audience_idYesSource Custom Audience to build the lookalike from. Meta recommends a source of at least 1,000–10,000 users for good match quality.

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. Changed1 schema field changedv1.0.7
    • changedInput schema / required
      Previous value: -[
-  "account_id",
-  "name",
-  "source_audience_id",
-  "country",
-  "ratio"
-]New value: +[
+  "name",
+  "source_audience_id",
+  "country",
+  "ratio"
+]
  4. Addedv0.9.12
  5. Removedv0.9.6
  6. Addedv0.9.2
  7. Removedv0.9.1
  8. Addedv1.0.5

TDQS

A4.3/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 behavioral burden and handles it well. It discloses the mutating nature, irreversibility, rollback suggestion, 24–72h population delay, zero approximate_count until build completion, and the practical meaning of ratio values.

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?

The description is information-dense and front-loaded: purpose and return value appear first, followed by essential behavioral caveats and usage guidance. A small amount of ratio detail duplicates the schema, but every sentence otherwise earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, return behavior, mutability, rollback, timing, and a relevant sibling tool. Although there is no output schema, the key return value is stated; the main omission is explicit discussion of permissions, error conditions, or polling behavior beyond the approximate_count note.

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 coverage is 100%, and the input schema already documents ratio ranges, country formats, defaults, and source audience guidance. The description adds useful context like ratio=0.01 vs 0.10 examples and the timing of approximate_count, but these mostly reinforce rather than materially extend the schema.

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 states a specific verb and resource: 'Creates a Lookalike Audience from an existing source audience' and notes the returned audience_id. This clearly distinguishes the tool from generic audience creation and related sibling tools by naming the exact operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete context for use: it requires an existing source audience, warns that the operation is mutating and not reversible, and points to meta_ads_audiences_list for the base audience list. It does not explicitly contrast with meta_ads_audiences_create or other alternatives, but the context is sufficiently clear.

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