Skip to main content
Glama

meta_ads_conversions_send

Send arbitrary conversion events in batches to the Meta Conversions API for event types like AddToCart, InitiateCheckout, CompleteRegistration, and custom events.

Instructions

Sends a batch of arbitrary conversion events to the Meta Conversions API. Returns Meta's response including events_received and messages (warnings for missing fields). Mutating on Meta's side — events become part of the pixel's attribution stream. For common event types prefer the dedicated meta_ads_conversions_send_purchase or send_lead helpers, which enforce required fields and fewer mistakes. For other event names (AddToCart, InitiateCheckout, CompleteRegistration, custom events) use this generic tool.

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": {
      "pixel_id": "<pixel_id>",
      "events": "<events>"
    },
    "name": "meta_ads_conversions_send"
  }
}

Input Schema

NameRequiredDescriptionDefault
eventsYesEvent payloads to send. Meta batches are typically ≤1000 events per call.
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)
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.
pixel_idYesMeta Pixel ID the event is attributed to. Find via meta_ads_pixels_list. CAPI events flow into the same pixel as browser events; dedupe happens on event_id if one is supplied in user_data / custom_data.
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.
test_event_codeNoMeta Events Manager test_event_code. When set, the event is routed to the test event stream visible in Events Manager instead of production reporting. Use for validation; drop the field once verified. Get the code from Events Manager → Test Events tab.

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. Addedv0.9.12
  7. Removedv0.9.6
  8. Addedv0.9.2
  9. Removedv0.9.1
  10. Addedv1.0.5

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does disclose the key traits: the call mutates Meta's side, events enter the pixel's attribution stream permanently, and the response contains events_received plus warning messages. It omits permissions/rate-limit context and does not note that events are batched at up to 1000 per call in the prose (that is only in 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.

Conciseness5/5

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

Four sentences, zero waste, with the core action and return shape front-loaded before the sibling-routing guidance. Every sentence 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?

There is no output schema, but the description names the return fields (events_received, messages) and explains that messages surface warnings for missing fields. For a nested, 8-parameter mutation tool with no annotations this is nearly complete; only auth and rate-limit context are 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% and the nested event fields are thoroughly documented there, so the baseline of 3 applies. The description adds no parameter-level detail beyond what the schema already provides, such as batch sizing or pixel selection guidance.

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?

States a specific verb and resource: it sends a batch of arbitrary conversion events to the Meta Conversions API. It explicitly separates itself from the dedicated send_purchase and send_lead siblings and names the event types this generic tool is intended for.

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?

Gives explicit routing: prefer meta_ads_conversions_send_purchase or send_lead for common event types because they enforce required fields, and use this tool for AddToCart, InitiateCheckout, CompleteRegistration, or custom events. Both the when and the when-not are stated.

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