Skip to main content
Glama
logly

mureo

by logly
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

meta_ads_split_tests_create

Creates a Meta Ads split test comparing pre-existing ad sets across chosen objectives and returns the study_id. Use it to launch a controlled experiment with defined start and end times.

Instructions

Creates a new Split Test. Returns the new study_id. Mutating — not automatically reversible; record before-state with mureo_state_action_log_append if you may need to roll back. Meta runs the test for the configured duration, then compares cells on the chosen objective (COST_PER_RESULT / CONVERSIONS / REACH / CPC / CPM). Cells must reference pre-existing ad sets; this tool does not create ad sets. For test analysis post-conclusion use meta_ads_split_tests_get.

Input Schema

NameRequiredDescriptionDefault
nameYesTest name shown in Experiments. Should describe the hypothesis being tested.
cellsYesTest cells (2 or more). Each cell has {name, adsets: [ad_set_id, ...]}. Meta splits traffic evenly across cells.
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.
approvalNoExternal approval this change carries out (recorded and shown, never verified)
end_timeYesTest end in ISO 8601. Meta requires at least 4 days between start_time and end_time for statistical significance.
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.
objectivesYesMetrics Meta will use to rank cells. Each entry is {type: COST_PER_RESULT | CONVERSIONS | REACH | CPC | CPM}. Multiple objectives produce multi-dimensional results.
start_timeYesTest start in ISO 8601 (e.g. '2026-04-25T00:00:00+0900'). Must be in the future when the test is created.
decision_idNoA proposed decision this change carries out.
descriptionNoFree-text description of the hypothesis. Internal — not shown to end users.
confidence_levelNoStatistical confidence threshold for declaring a winner. Default 95 (95%). Higher values need more spend / longer duration to conclude.

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",
-  "cells",
-  "objectives",
-  "start_time",
-  "end_time"
-]New value: +[
+  "name",
+  "cells",
+  "objectives",
+  "start_time",
+  "end_time"
+]
  7. Addedv0.9.12
  8. Removedv0.9.6
  9. Addedv0.9.2
  10. Removedv0.9.1
  11. Addedv1.0.5

TDQS

A4.9/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 so: it flags the operation as mutating and not automatically reversible, prescribes a rollback-safety step, and explains the underlying Meta behavior (test runs for the configured duration, then cells are compared on the chosen objective).

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?

Front-loads what the tool does and returns, then layers mutation risk, mechanics, and sibling routing in a tight sequence. Every sentence contributes a distinct, actionable fact with no repetition of schema content.

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 covers what an agent needs: purpose, return value, irreversibility, prerequisite data, and the follow-up tool. Remaining gaps are covered by the fully documented input schema.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by constraining the cells parameter to pre-existing ad set IDs and naming the objective metrics Meta ranks on. It does not add semantics for the journaling params (reason, approval, decision_id) or confidence_level, which remain schema-only.

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+resource ('Creates a new Split Test') and immediately states the return value ('Returns the new study_id'). It also carves out boundaries against siblings: it does not create ad sets, and analysis after conclusion belongs to meta_ads_split_tests_get.

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?

Explicitly routes the agent: use meta_ads_split_tests_get for post-conclusion analysis, and note that cells must reference pre-existing ad sets this tool will not create. It also adds operational guidance — log before-state with mureo_state_action_log_append if rollback may be needed.

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