Skip to main content
Glama

Soclo

by app.soclo
OverviewDiscussionsAdmin

Create CTWA ad (deprecated)

soclo_ads_create_ctwa_ad
Destructive

Create a click-to-WhatsApp advertisement using the supplied creative, WhatsApp destination and budget through the existing legacy endpoint. Quote first by calling without confirm:true. Show the returned spending preview and obtain owner approval before confirming with the same requestId. Retain that requestId for soclo_ads_operation_status after an uncertain result; never automatically repeat a purchase. Report the returned status without claiming the ad is live until active. Confirmed creation requests active status; platform review may delay delivery. Fields: soclo://tools/soclo_ads_create_ctwa_ad.

Input Schema

NameRequiredDescriptionDefault
confirmNoTrue only after owner approval of spending/deletion preview.
payloadYes
platformNo
accountIdYes
requestIdNoReuse this request ID for confirmation and outcome recovery.
parametersNo
adAccountIdNoAdvertiser/ad account selected from your Soclo connection.
expectedCurrencyNoApproved preview currency, e.g. GBP.
expectedBudgetTypeNoApproved preview budget type: daily or lifetime.
expectedBudgetAmountNoApproved preview amount; changes require a new preview.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed84 schema fields changed
    • addedInput schema / definitions
      Added value: +{
+  "s1": {
+    "properties": {
+      "callToAction": {
+        "type": "string"
+      },
+      "description": {
+        "maxLength": 255,
+        "type": "string"
+      },
+      "headline": {
+        "maxLength": 255,
+        "type": "string"
+      },
+      "imageUrl": {
+        "type": "string"
+      },
+      "linkUrl": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "imageUrl"
+    ],
+    "type": "object"
+  },
+  "s10": {
+    "items": {
+      "properties": {
+        "key": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "key"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "s2": {
+    "items": {
+      "$ref": "#/definitions/s7"
+    },
+    "type": "array"
+  },
+  "s3": {
+    "properties": {
+      "address": {
+        "type": "string"
+      },
+      "distanceUnit": {
+        "enum": [
+          "mile",
+          "kilometer"
+        ],
+        "type": "string"
+      },
+      "latitude": {
+        "maximum": 90,
+        "minimum": -90,
+        "type": "number"
+      },
+      "longitude": {
+        "maximum": 180,
+        "minimum": -180,
+        "type": "number"
+      },
+      "name": {
+        "type": "string"
+      },
+      "radius": {
+        "type": "number"
+      }
+    },
+    "required": [
+      "latitude",
+      "longitude",
+      "radius",
+      "distanceUnit"
+    ],
+    "type": "object"
+  },
+  "s4": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "s5": {
+    "type": "string"
+  },
+  "s6": {
+    "items": {
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "id"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "s7": {
+    "enum": [
+      "africa",
+      "asia",
+      "europe",
+      "north_america",
+      "south_america",
+      "oceania",
+      "central_america",
+      "caribbean",
+      "eea",
+      "euro_area",
+      "nafta",
+      "mercosur",
+      "afta",
+      "apec",
+      "gcc",
+      "cisfta",
+      "emerging_markets",
+      "itunes_app_store",
+      "android_free_store",
+      "android_paid_store"
+    ],
+    "type": "string"
+  },
+  "s8": {
+    "pattern": "^\\d+_\\d+$",
+    "type": "string"
+  },
+  "s9": {
+    "minLength": 1,
+    "type": "string"
+  }
+}
    • removedInput schema / properties / accountId / description
      Removed value: -"The connected ad account in Soclo."
    • removedInput schema / properties / payload / properties / audienceExclude / description
      Removed value: -"Custom or lookalike audience ids to exclude."
    • removedInput schema / properties / payload / properties / audienceId / description
      Removed value: -"Custom audience ID to target."
    • removedInput schema / properties / payload / properties / audienceInclude / description
      Removed value: -"Custom or lookalike audience ids to include."
    • addedInput schema / properties / payload / properties / carouselCards / items / $ref
      Added value: +"#/definitions/s1"
    • removedInput schema / properties / payload / properties / carouselCards / items / properties
      Removed value: -{
-  "callToAction": {
-    "type": "string"
-  },
-  "description": {
-    "description": "Card description, under the title.",
-    "maxLength": 255,
-    "type": "string"
-  },
-  "headline": {
-    "description": "Card title (Meta name).",
-    "maxLength": 255,
-    "type": "string"
-  },
-  "imageUrl": {
-    "type": "string"
-  },
-  "linkUrl": {
-    "type": "string"
-  }
-}
    • removedInput schema / properties / payload / properties / carouselCards / items / required
      Removed value: -[
-  "imageUrl"
-]
    • removedInput schema / properties / payload / properties / carouselCards / items / type
      Removed value: -"object"
    • addedInput schema / properties / payload / properties / countryGroups / $ref
      Added value: +"#/definitions/s2"
    • removedInput schema / properties / payload / properties / countryGroups / items
      Removed value: -{
-  "enum": [
-    "africa",
-    "asia",
-    "europe",
-    "north_america",
-    "south_america",
-    "oceania",
-    "central_america",
-    "caribbean",
-    "eea",
-    "euro_area",
-    "nafta",
-    "mercosur",
-    "afta",
-    "apec",
-    "gcc",
-    "cisfta",
-    "emerging_markets",
-    "itunes_app_store",
-    "android_free_store",
-    "android_paid_store"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / payload / properties / countryGroups / type
      Removed value: -"array"
    • removedInput schema / properties / payload / properties / creatives / items / properties / body / description
      Removed value: -"Primary text shown above the image / video."
    • addedInput schema / properties / payload / properties / creatives / items / properties / carouselCards / items / $ref
      Added value: +"#/definitions/s1"
    • removedInput schema / properties / payload / properties / creatives / items / properties / carouselCards / items / properties
      Removed value: -{
-  "callToAction": {
-    "type": "string"
-  },
-  "description": {
-    "description": "Card description, under the title.",
-    "maxLength": 255,
-    "type": "string"
-  },
-  "headline": {
-    "description": "Card title (Meta name).",
-    "maxLength": 255,
-    "type": "string"
-  },
-  "imageUrl": {
-    "type": "string"
-  },
-  "linkUrl": {
-    "type": "string"
-  }
-}
    • removedInput schema / properties / payload / properties / creatives / items / properties / carouselCards / items / required
      Removed value: -[
-  "imageUrl"
-]
    • removedInput schema / properties / payload / properties / creatives / items / properties / carouselCards / items / type
      Removed value: -"object"
    • addedInput schema / properties / payload / properties / creatives / items / properties / existingPostId / $ref
      Added value: +"#/definitions/s9"
    • removedInput schema / properties / payload / properties / creatives / items / properties / existingPostId / minLength
      Removed value: -1
    • removedInput schema / properties / payload / properties / creatives / items / properties / existingPostId / type
      Removed value: -"string"
    • addedInput schema / properties / payload / properties / creatives / items / properties / objectStoryId / $ref
      Added value: +"#/definitions/s8"
    • removedInput schema / properties / payload / properties / creatives / items / properties / objectStoryId / pattern
      Removed value: -"^\\d+_\\d+$"
    • removedInput schema / properties / payload / properties / creatives / items / properties / objectStoryId / type
      Removed value: -"string"
    • addedInput schema / properties / payload / properties / creatives / items / properties / platformPostId / $ref
      Added value: +"#/definitions/s4"
    • removedInput schema / properties / payload / properties / creatives / items / properties / platformPostId / minLength
      Removed value: -1
    • removedInput schema / properties / payload / properties / creatives / items / properties / platformPostId / type
      Removed value: -"string"
    • addedInput schema / properties / payload / properties / creatives / items / properties / video / properties / id / $ref
      Added value: +"#/definitions/s5"
    • removedInput schema / properties / payload / properties / creatives / items / properties / video / properties / id / type
      Removed value: -"string"
    • removedInput schema / properties / payload / properties / creatives / items / properties / welcomeMessage / properties / text / description
      Removed value: -"Greeting shown when the chat opens. Replaces Meta's default."
    • addedInput schema / properties / payload / properties / existingPostId / $ref
      Added value: +"#/definitions/s9"
    • removedInput schema / properties / payload / properties / existingPostId / minLength
      Removed value: -1
    • removedInput schema / properties / payload / properties / existingPostId / type
      Removed value: -"string"
    • addedInput schema / properties / payload / properties / interests / $ref
      Added value: +"#/definitions/s6"
    • removedInput schema / properties / payload / properties / interests / items
      Removed value: -{
-  "properties": {
-    "id": {
-      "type": "string"
-    },
-    "name": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "id"
-  ],
-  "type": "object"
-}
    • removedInput schema / properties / payload / properties / interests / type
      Removed value: -"array"
    • removedInput schema / properties / payload / properties / neighborhoods / description
      Removed value: -"Meta neighborhood keys (from GET /v1/ads/targeting/search)."
    • addedInput schema / properties / payload / properties / objectStoryId / $ref
      Added value: +"#/definitions/s8"
    • removedInput schema / properties / payload / properties / objectStoryId / pattern
      Removed value: -"^\\d+_\\d+$"
    • removedInput schema / properties / payload / properties / objectStoryId / type
      Removed value: -"string"
    • removedInput schema / properties / payload / properties / places / description
      Removed value: -"Meta place keys (from GET /v1/ads/targeting/search)."
    • addedInput schema / properties / payload / properties / platformPostId / $ref
      Added value: +"#/definitions/s4"
    • removedInput schema / properties / payload / properties / platformPostId / minLength
      Removed value: -1
    • removedInput schema / properties / payload / properties / platformPostId / type
      Removed value: -"string"
    • removedInput schema / properties / payload / properties / specialAdCategories / description
      Removed value: -"Meta special ad categories on the new campaign."
    • changedInput schema / properties / payload / properties / targeting / properties / cities / items / anyOf
      Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "properties": {
-      "distanceUnit": {
-        "description": "Required if radius is set.",
-        "enum": [
-          "mile",
-          "kilometer"
-        ],
-        "type": "string"
-      },
-      "key": {
-        "type": "string"
-      },
-      "name": {
-        "type": "string"
-      },
-      "radius": {
-        "type": "number"
-      }
-    },
-    "required": [
-      "key"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "properties": {
+      "distanceUnit": {
+        "enum": [
+          "mile",
+          "kilometer"
+        ],
+        "type": "string"
+      },
+      "key": {
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      },
+      "radius": {
+        "type": "number"
+      }
+    },
+    "required": [
+      "key"
+    ],
+    "type": "object"
+  }
+]
    • removedInput schema / properties / payload / properties / targeting / properties / countries / description
      Removed value: -"ISO 3166-1 alpha-2 country codes (e.g. ['US'])."
    • addedInput schema / properties / payload / properties / targeting / properties / countryGroups / $ref
      Added value: +"#/definitions/s2"
    • removedInput schema / properties / payload / properties / targeting / properties / countryGroups / items
      Removed value: -{
-  "enum": [
-    "africa",
-    "asia",
-    "europe",
-    "north_america",
-    "south_america",
-    "oceania",
-    "central_america",
-    "caribbean",
-    "eea",
-    "euro_area",
-    "nafta",
-    "mercosur",
-    "afta",
-    "apec",
-    "gcc",
-    "cisfta",
-    "emerging_markets",
-    "itunes_app_store",
-    "android_free_store",
-    "android_paid_store"
-  ],
-  "type": "string"
-}
    • removedInput schema / properties / payload / properties / targeting / properties / countryGroups / type
      Removed value: -"array"
    • addedInput schema / properties / payload / properties / targeting / properties / customLocations / items / $ref
      Added value: +"#/definitions/s3"
    • removedInput schema / properties / payload / properties / targeting / properties / customLocations / items / properties
      Removed value: -{
-  "address": {
-    "type": "string"
-  },
-  "distanceUnit": {
-    "enum": [
-      "mile",
-      "kilometer"
-    ],
-    "type": "string"
-  },
-  "latitude": {
-    "maximum": 90,
-    "minimum": -90,
-    "type": "number"
-  },
-  "longitude": {
-    "maximum": 180,
-    "minimum": -180,
-    "type": "number"
-  },
-  "name": {
-    "type": "string"
-  },
-  "radius": {
-    "description": "Positive radius around the point.",
-    "type": "number"
-  }
-}
    • removedInput schema / properties / payload / properties / targeting / properties / customLocations / items / required
      Removed value: -[
-  "latitude",
-  "longitude",
-  "radius",
-  "distanceUnit"
-]
    • removedInput schema / properties / payload / properties / targeting / properties / customLocations / items / type
      Removed value: -"object"
    • removedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / cities / items / properties / distanceUnit / description
      Removed value: -"Required if radius is set."
    • removedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / cities / items / properties / radius / description
      Removed value: -"Radius around the excluded city. Requires distanceUnit."
    • addedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / countryGroups / items / $ref
      Added value: +"#/definitions/s7"
    • removedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / countryGroups / items / enum
      Removed value: -[
-  "africa",
-  "asia",
-  "europe",
-  "north_america",
-  "south_america",
-  "oceania",
-  "central_america",
-  "caribbean",
-  "eea",
-  "euro_area",
-  "nafta",
-  "mercosur",
-  "afta",
-  "apec",
-  "gcc",
-  "cisfta",
-  "emerging_markets",
-  "itunes_app_store",
-  "android_free_store",
-  "android_paid_store"
-]
    • removedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / countryGroups / items / type
      Removed value: -"string"
    • addedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / customLocations / items / $ref
      Added value: +"#/definitions/s3"
    • removedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / customLocations / items / properties
      Removed value: -{
-  "address": {
-    "type": "string"
-  },
-  "distanceUnit": {
-    "enum": [
-      "mile",
-      "kilometer"
-    ],
-    "type": "string"
-  },
-  "latitude": {
-    "maximum": 90,
-    "minimum": -90,
-    "type": "number"
-  },
-  "longitude": {
-    "maximum": 180,
-    "minimum": -180,
-    "type": "number"
-  },
-  "name": {
-    "type": "string"
-  },
-  "radius": {
-    "description": "Positive radius around the point.",
-    "type": "number"
-  }
-}
    • removedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / customLocations / items / required
      Removed value: -[
-  "latitude",
-  "longitude",
-  "radius",
-  "distanceUnit"
-]
    • removedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / customLocations / items / type
      Removed value: -"object"
    • addedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / regions / $ref
      Added value: +"#/definitions/s10"
    • removedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / regions / items
      Removed value: -{
-  "properties": {
-    "key": {
-      "type": "string"
-    },
-    "name": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "key"
-  ],
-  "type": "object"
-}
    • removedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / regions / type
      Removed value: -"array"
    • addedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / zips / $ref
      Added value: +"#/definitions/s10"
    • removedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / zips / items
      Removed value: -{
-  "properties": {
-    "key": {
-      "type": "string"
-    },
-    "name": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "key"
-  ],
-  "type": "object"
-}
    • removedInput schema / properties / payload / properties / targeting / properties / excludedLocations / properties / zips / type
      Removed value: -"array"
    • removedInput schema / properties / payload / properties / tracking / properties / pixelId / description
      Removed value: -"Meta Pixel ID to attach for offsite-conversion measurement."
    • removedInput schema / properties / payload / properties / userDevice / description
      Removed value: -"Meta `user_device`."
    • removedInput schema / properties / payload / properties / userOs / description
      Removed value: -"Meta `user_os`, e.g. [\"iOS_ver_14.0_and_above\"]."
    • addedInput schema / properties / payload / properties / video / properties / id / $ref
      Added value: +"#/definitions/s5"
    • removedInput schema / properties / payload / properties / video / properties / id / type
      Removed value: -"string"
    • removedInput schema / properties / payload / properties / welcomeMessage / properties / quickReplies / items / properties / title / description
      Removed value: -"Chip label the person taps."
    • addedInput schema / properties / payload / properties / workEmployers / $ref
      Added value: +"#/definitions/s6"
    • removedInput schema / properties / payload / properties / workEmployers / items
      Removed value: -{
-  "properties": {
-    "id": {
-      "type": "string"
-    },
-    "name": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "id"
-  ],
-  "type": "object"
-}
    • removedInput schema / properties / payload / properties / workEmployers / type
      Removed value: -"array"
    • addedInput schema / properties / payload / properties / workIndustries / $ref
      Added value: +"#/definitions/s6"
    • removedInput schema / properties / payload / properties / workIndustries / items
      Removed value: -{
-  "properties": {
-    "id": {
-      "type": "string"
-    },
-    "name": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "id"
-  ],
-  "type": "object"
-}
    • removedInput schema / properties / payload / properties / workIndustries / type
      Removed value: -"array"
    • addedInput schema / properties / payload / properties / workPositions / $ref
      Added value: +"#/definitions/s6"
    • removedInput schema / properties / payload / properties / workPositions / items
      Removed value: -{
-  "properties": {
-    "id": {
-      "type": "string"
-    },
-    "name": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "id"
-  ],
-  "type": "object"
-}
    • removedInput schema / properties / payload / properties / workPositions / type
      Removed value: -"array"
    • removedInput schema / properties / platform / description
      Removed value: -"The campaign platform."
  2. Changed3 schema fields changed
    • removedInput schema / properties / payload / properties / creatives / items / properties / video / properties / url / description
      Removed value: -"Public URL of the video to upload. Provide either `url` or `id`."
    • removedInput schema / properties / payload / properties / placements / properties / devicePlatforms / description
      Removed value: -"Restrict by device. Omit to deliver on both mobile and desktop."
    • removedInput schema / properties / payload / properties / video / properties / url / description
      Removed value: -"Public URL of the video to upload. Provide either `url` or `id`."
  3. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Goes well beyond the annotations: it discloses the quote-before-purchase pattern, the requestId recovery contract, the prohibition on auto-repeating a purchase, and that confirmed creation requests ACTIVE while platform review may delay delivery. These are exactly the behavioral facts an agent needs for a destructive, open-world, non-idempotent spend operation.

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-loads the create action, then the quote/confirm/recovery workflow. Sentences are dense but each carries a distinct safety or procedural fact; there is minor overlap between 'retain requestId' and 'never automatically repeat a purchase' but not wasteful.

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?

For a complex, 10-parameter nested mutation with no output schema, the description covers the critical safety workflow (quote, approval, recovery, status reporting) that an agent would otherwise guess wrong. The main gap is that the return shape is only loosely implied ('report the returned status'), but the operational essentials are present.

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 60% and the description reinforces the confirm/requestId workflow that the schema already documents. However the large nested payload object (targeting, creatives, placements, budget fields) gets no semantic explanation in the description, and it does not compensate for the undocumented parameters beyond the preview fields.

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 (Create) and resource (click-to-WhatsApp advertisement), and pins the scope to the legacy/CTWA endpoint, which distinguishes it from siblings like soclo_ads_create_messaging_ad and soclo_ads_create_call_ad. An agent can tell what it produces without opening the schema.

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?

Gives an explicit two-step usage flow: call without confirm:true to quote, show the preview, obtain owner approval, then confirm with the same requestId; also says to reuse requestId for soclo_ads_operation_status on uncertain results. This is strong procedural guidance, though it doesn't explicitly contrast against the other create-ad siblings.

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

All Soclo toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources