Skip to main content
Glama

Soclo

by app.soclo
OverviewDiscussionsAdmin

Create Click-to-Call ad

soclo_ads_create_call_ad
Destructive

Create a click-to-call advertisement using the supplied creative, phone destination and budget. 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_call_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. Changed85 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 / phoneNumber / description
      Removed value: -"E.164 number the CALL_NOW CTA dials (e.g. +34600111222)."
    • 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.4/5.0
Behavior5/5

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

Annotations already flag destructive=true, idempotent=false and openWorld=true, but the description adds the operationally important details: spending preview before commit, owner approval gate, requestId reuse for recovery, prohibition on automatic repurchase, status reported as returned rather than assuming 'live', and the caveat that platform review can delay delivery.

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 purpose, then proceeds through quote, approve, confirm, recover, report in a tight sequence. Every sentence carries an operational instruction or constraint, with no restatement of the title or filler.

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 destructive, non-idempotent creation tool with no output schema, the description covers the risk profile, approval workflow and recovery path thoroughly. It omits guidance on the required payload fields (name, phoneNumber, linkUrl) and on the breadth of optional targeting/budget inputs, which matters given 10 parameters and deep nesting.

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 schema already documents confirm, requestId, expectedCurrency, expectedBudgetType and expectedBudgetAmount. The description reinforces the confirm/requestId workflow but adds no field-level meaning beyond that, and the large nested payload (targeting, budget, placements) is left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a click-to-call advertisement') plus the key inputs (creative, phone destination, budget), so an agent can identify it precisely. It does not contrast itself against near siblings like soclo_ads_create_standalone_ad, soclo_ads_create_ctwa_ad or soclo_ads_create_messaging_ad, which is the main shortfall.

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 an explicit two-step protocol: call without confirm:true to get a quote, show the preview, obtain owner approval, then confirm with the same requestId. It also names the follow-up tool (soclo_ads_operation_status) for uncertain outcomes and forbids automatic retry, leaving little to inference.

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