Skip to main content
Glama
DatalisHQ

ZuckerBot

by DatalisHQ
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

zuckerbot_create_ad

Create ONE new ad (a new creative built from a declared asset) in an EXISTING ad set of the connected ad account — the way to add a brand-new image or video into a campaign that is already running, including ZuckerBot-external campaigns.

Instructions

Create ONE new ad (a new creative built from a declared asset) in an EXISTING ad set of the connected ad account — the way to add a brand-new image or video into a campaign that is already running, including ZuckerBot-external campaigns. Dry-run by default: returns the exact object plan (1 new creative + 1 new ad) without creating anything; pass execute: true plus an idempotency_key to build it. The ad is ALWAYS created PAUSED — activating it is a separate deliberate action. Optionally pass images (1–10 labeled image_hash/image_url/file_path entries); multiple images use placement customisation with a dry-run placement_table. Local file_path works only in local stdio/CLI and uploads automatically on execute. Omitted placements are inferred from original 1:1, 4:5 or 9:16 dimensions; remaining ad-set placements use square or the first image. Explicit placements use platform.position or platform.position.device (e.g. facebook.feed.mobile). Every target placement/device is assigned once, including newer placements returned by Meta. No ad-set settings are changed. Multiple images currently require final_url and cta. Asset: IMAGE (image_hash from zuckerbot_upload_ad_asset, or image_url — uploaded to the library automatically) or VIDEO (video_id from zuckerbot_upload_ad_asset, which must be processed/ready; thumbnail auto-derived, thumbnail_url overridable). Destination: exactly one of final_url (website) or lead_form_id (instant form — requires cta). VIDEO ads carry their link in the call_to_action, so VIDEO + final_url also requires cta. To clone an ad that already exists in the account instead, use zuckerbot_duplicate_ad.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
ctaNoUppercase Meta CTA type, e.g. LEARN_MORE or SIGN_UP (required for VIDEO ads and instant-form destinations)
nameYesName for the new ad
imagesNoLabeled images; choose exactly one hash, HTTPS URL or local file path per image. Mutually exclusive with the single-asset fields.
executeNoDefault false (dry-run). Set true to actually create the PAUSED ad — requires idempotency_key
headlineNoHeadline
video_idNoVIDEO: Meta video id (from zuckerbot_upload_ad_asset; must be processed/ready)
final_urlNoWebsite destination URL (exactly one of final_url or lead_form_id)
image_urlNoIMAGE: https URL — uploaded to the ad-account library automatically on execution
asset_typeNoIMAGE (image_hash or image_url) or VIDEO (video_id)
image_hashNoIMAGE: 32-char Meta library image hash from zuckerbot_upload_ad_asset for THIS ad account — hashes from the business media library or another ad account are rejected as image_hash_unusable
business_idNoOptional business ID override for the authenticated API key
descriptionNoDescription
lead_form_idNoMeta instant-form id on the connected Page (exactly one of final_url or lead_form_id; see zuckerbot_lead_forms)
primary_textNoPrimary text / body copy
thumbnail_urlNoVIDEO: optional https thumbnail override (default: derived from the processed video)
thumbnail_hashNoVIDEO: optional library image hash to use as the thumbnail
idempotency_keyNoRequired when execute is true. Generate once per logical operation (UUIDv4 recommended); reuse the identical value only when retrying the identical request
target_adset_idYesNumeric Meta ad set id to create the ad in (must be an EXISTING ad set in the connected ad account)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.4.10
    • addedInput schema / properties / images
      Added value: +{
+  "description": "Labeled images; choose exactly one hash, HTTPS URL or local file path per image. Mutually exclusive with the single-asset fields.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "file_path": {
+        "type": "string"
+      },
+      "image_hash": {
+        "type": "string"
+      },
+      "image_url": {
+        "type": "string"
+      },
+      "label": {
+        "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,49}$",
+        "type": "string"
+      },
+      "placements": {
+        "items": {
+          "type": "string"
+        },
+        "maxItems": 100,
+        "minItems": 1,
+        "type": "array"
+      }
+    },
+    "required": [
+      "label"
+    ],
+    "type": "object"
+  },
+  "maxItems": 10,
+  "minItems": 1,
+  "type": "array"
+}
    • changedInput schema / required
      Previous value: -[
-  "target_adset_id",
-  "name",
-  "asset_type"
-]New value: +[
+  "target_adset_id",
+  "name"
+]
  2. Changed1 schema field changedv0.4.8
    • changedInput schema / properties / image_hash / description
      Previous value: -"IMAGE: 32-char Meta library image hash (from zuckerbot_upload_ad_asset)"New value: +"IMAGE: 32-char Meta library image hash from zuckerbot_upload_ad_asset for THIS ad account — hashes from the business media library or another ad account are rejected as image_hash_unusable"
  3. Addedv0.4.7

TDQS

A5/5.0
Behavior5/5

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: dry-run by default, execute requires idempotency_key, ads are ALWAYS created PAUSED, no ad-set settings are changed, local file_path works only in local stdio/CLI, and image_hash is rejected if not from the connected ad account. These are non-obvious operational traits that an agent needs before calling.

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?

Despite being long, the description is dense and every sentence earns its place given the tool's complexity. It is front-loaded with the core purpose and dry-run behavior, then progresses through asset, destination, placement, and exception details without filler or repetition.

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 an 18-parameter creation tool with no annotations and no output schema, the description is remarkably complete. It covers the create plan return, execution semantics, paused state, asset constraints, placement inference rules, destination rules, and known error/constraint cases like image_hash_unusable. No critical operational gap remains for an agent to call it correctly.

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

Parameters5/5

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

Even though schema description coverage is 100%, the description adds significant relational semantics beyond the schema: final_url and lead_form_id are mutually exclusive, VIDEO + final_url also requires cta, image entries must be labeled and 1-10, idempotency_key must be reused only for identical retries, and image_hash must come from this specific ad account. This goes well beyond the schema's per-field descriptions.

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?

The description opens with a specific verb, resource, and scope: 'Create ONE new ad ... in an EXISTING ad set of the connected ad account.' It explicitly differentiates from cloning by naming zuckerbot_duplicate_ad as the alternative for existing ads, and it clarifies that this is the path for adding brand-new creatives to running campaigns.

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?

The description gives clear when-to-use guidance ('the way to add a brand-new image or video into a campaign that is already running'), explains the dry-run vs execute workflow, and explicitly routes cloning cases to zuckerbot_duplicate_ad. It also notes conditions like 'Multiple images currently require final_url and cta' and the paused-by-default behavior.

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