Skip to main content
Glama
logly

mureo

by logly
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

meta_ads_audiences_create_lookalike

Creates a Meta lookalike audience from a source custom audience and returns the new audience ID; set country and ratio to control similarity and reach.

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

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.
approvalNoExternal approval this change carries out (recorded and shown, never verified)
expectedNoExpected effects [{metric, direction, target?, horizon_days?, primary?}], exactly one primary:true when several; metric cpa/cpc/cpl/cpm/conversions/cvr/ctr/roas/cost/spend/clicks/impressions; direction up/down/hold.
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.
decision_idNoA proposed decision this change carries out.
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.33.0
    • changedInput schema / properties / expected / description
      Previous value: -"Expected effects [{metric, direction, target?, horizon_days?}]; metric cpa/cpc/cpl/cpm/conversions/cvr/ctr/roas/cost/spend/clicks/impressions; direction up/down/hold."New value: +"Expected effects [{metric, direction, target?, horizon_days?, primary?}], exactly one primary:true when several; metric cpa/cpc/cpl/cpm/conversions/cvr/ctr/roas/cost/spend/clicks/impressions; direction up/down/hold."
  2. Changed1 schema field changedv0.28.0
    • addedInput schema / properties / approval
      Added value: +{
+  "additionalProperties": false,
+  "description": "External approval this change carries out (recorded and shown, never verified)",
+  "properties": {
+    "approved_at": {
+      "maxLength": 64,
+      "type": "string"
+    },
+    "approved_by": {
+      "maxLength": 80,
+      "type": "string"
+    },
+    "reference": {
+      "maxLength": 128,
+      "type": "string"
+    }
+  },
+  "required": [
+    "reference",
+    "approved_by",
+    "approved_at"
+  ],
+  "type": "object"
+}
  3. Changed2 schema fields changedv0.26.0
    • addedInput schema / properties / decision_id
      Added value: +{
+  "description": "A proposed decision this change carries out.",
+  "maxLength": 128,
+  "minLength": 1,
+  "type": "string"
+}
    • addedInput schema / properties / expected
      Added value: +{
+  "description": "Expected effects [{metric, direction, target?, horizon_days?}]; metric cpa/cpc/cpl/cpm/conversions/cvr/ctr/roas/cost/spend/clicks/impressions; direction up/down/hold.",
+  "maxItems": 12,
+  "type": "array"
+}
  4. 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"
+}
  5. Changed1 schema field changedv0.10.37
    • addedInput schema / additionalProperties
      Added value: +false
  6. 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"
+]
  7. Addedv0.9.12
  8. Removedv0.9.6
  9. Addedv0.9.2
  10. Removedv0.9.1
  11. Addedv1.0.5

TDQS

A4.4/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 does: it declares the tool mutating, not automatically reversible, and recommends journaling before-state for rollback. It also discloses the 24–72h population latency and that approximate_count stays 0 until Meta finishes the build — behavior an agent could not 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 and return value, then behavior and caveats, then the sibling pointer — well ordered. The ratio sentence is somewhat redundant against the schema and costs more space than it earns.

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?

Despite 10 parameters and no output schema, the description states the return value, the mutability/rollback path, the async population window, and the ratio tradeoff. Nothing an agent needs to invoke this correctly is missing.

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%, so the schema already documents every parameter including ratio bounds, starting_ratio tiering, and source audience sizing. The description's ratio=0.01 vs 0.10 explanation largely restates what the schema's ratio and starting_ratio descriptions already say, adding little beyond the schema baseline.

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 and resource (creates a Lookalike Audience) and states it builds from an existing source audience, plus names the return value (audience_id). It is clearly distinguishable from meta_ads_audiences_create and meta_ads_audiences_list named in the same text.

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?

Explicitly routes the agent to meta_ads_audiences_list for the base audience list and to mureo_state_action_log_append for capturing before-state, which is genuine when-to-use guidance. It does not state when a lookalike should be preferred or avoided versus a custom audience, so it stops short of full alternatives coverage.

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