Tool reference

Show the current ZuckerBot authentication mode (demo vs authenticated), the Free/Pro/Scale and Lifetime billing tiers, setup instructions if not yet configured, and the recommended tool flow from audit → campaign → launch → performance. Returns status, recommended_flow steps, pricing info, and setup guide for unauthenticated users. Call this first in any new session to orient the agent.

Check your current ZuckerBot billing tier, API call usage this month, remaining quota, and overage costs. Use this when a user asks about their plan or usage limits.

Run a full audit of the connected Meta ad account: wasted spend detection, creative fatigue, opportunity score (0-100), projected CPL improvement, and prioritised action items. Read-only and available on every tier — the recommended FIRST call for any new account or when a user asks 'how are my ads doing?'.

Analyse the historical ad performance for a business. For accounts WITH history: returns aggregated metrics by audience type, top performing creatives, and comparable CPL ranges. For NEW accounts with NO history: returns is_cold_start=true with industry benchmarks. Use this as the FIRST step in campaign planning — feed the result into zuckerbot_recommend_campaign_structure.

Fetch real-time performance metrics for a ZuckerBot campaign. Legacy campaigns return a flat metrics summary (impressions, clicks, leads, spend, CPL, CTR). Intelligence campaigns additionally return tier-by-tier and ad-by-ad Meta insights, daily breakdowns, CAPI attribution totals, and AI-recommended next actions. Use this to monitor an active campaign or to diagnose underperformance.

Fetch historical Meta ad account performance for a connected business over a date range. Returns spend, clicks, impressions, CTR, CPM, CPC, and frequency aggregated daily or monthly. Useful for top-level budget reporting and month-over-month trend analysis without opening Ads Manager.

Query campaign, ad set, or ad-level performance for any campaign in the connected Meta ad account — including campaigns not created by ZuckerBot. Tags each row with is_zuckerbot so you can benchmark ZuckerBot campaigns against manually managed ones. Supports date range filtering, campaign name search, status filters, time-series breakdowns, and multi-column sorting. For deduped truth use meta_result / cost_per_meta_result (Meta's Ads Manager \"Results\" for any objective) or conversion_leads / meta_leads — not the inflated, deprecated leads / cpl. meta_result and conversion_leads are most reliable on campaign-level, non-time-incremented queries.

Check whether the user's Facebook/Meta account is connected to ZuckerBot. Returns connection status, connected ad accounts, and a connect URL if not yet linked. Always call this before attempting to launch a campaign to confirm Meta credentials are available.

Fetch the current Conversions API configuration for a business: whether CAPI delivery is enabled, CRM source, currency, stage-to-event mappings, action source, and webhook URL. Use this before configuring CAPI to see what is already set, or to audit the current event mapping.

Get 7-day and 30-day CAPI delivery statistics for the business: total events sent, events by type (Lead/Contact/Purchase), match quality breakdown, and attribution counts. Use this to confirm CAPI is functioning and that events are being matched by Meta.

Send a synthetic CAPI test event through the business configuration to verify the full pipeline: stage mapping, hashing, and Meta Graph API delivery. Logs as a test event (does not affect real attribution). Use after setting up or updating CAPI config to confirm events are flowing.

Fetch live Meta performance and downstream CAPI attribution for a launched audience portfolio. Returns enriched tier rows with ad breakdowns, daily metrics, CPA vs. target comparisons, and autonomous evaluation outputs. Use this to monitor a running portfolio and decide whether to rebalance.

Generate a campaign structure recommendation: audience tiers, budget allocation, creative mix. For accounts WITH history: uses Claude to generate data-driven recommendations. For NEW accounts (cold start): generates conservative defaults from industry benchmarks + safe 2-tier structure (broad 60% / interest 40%). Always returns comparable_historical_cpl with source (account_history or industry_benchmarks) and a disclaimer — NEVER a CPL projection. Lead campaigns default to Meta Instant Form; for leads driving to a website landing page rather than Meta Instant Form, set lead_destination='website'. Present the recommendation to the customer for approval before proceeding.

Generate a detailed creative brief from an approved campaign structure. SAFE — pure function, no Meta API calls, no money spent. Automatically pulls brand context and historical creative patterns (or uses brand context alone for cold-start accounts). Returns per-slot creative directions: for static ads, specific ad template + headline/body/CTA + hero image prompt; for video ads, hook concept + voiceover direction + visual style. After brief is generated, present it to the customer, then call zuckerbot_generate_static_ad / zuckerbot_generate_video_ad for each slot.

Build a complete Meta campaign from an approved Campaign Architect session. IMPORTANT: dry_run defaults to TRUE. When dry_run=true, returns the exact campaign structure that WOULD be created without calling Meta — safe, free, no side effects. Present this to the customer first. Only set dry_run=false after explicit customer approval. When dry_run=false, creates live Meta objects (campaign + ad sets + ads) in PAUSED state. Generated videos get linked for rejection tracking automatically.

Generate a zero-cost campaign preview from any business URL. Scrapes the site, writes AI-generated headlines and body copy, and generates ad images — all without a Meta account or live budget. Use this as the first step to show a user what their ads could look like before committing to a full campaign.

Create a new campaign draft for a business. In intelligence mode (preferred when a business_id is available) this returns context-aware audience tiers, creative angles, budget guidance, projected CPL, and phased next steps. Does NOT spend money or create anything on Meta — it's purely a planning step. Use zuckerbot_launch_campaign to go live after strategy approval.

Fetch the full details of a ZuckerBot campaign by ID: intelligence workflow state, approved strategy, stored creatives, audience tier executions, and performance status. Use this to inspect a campaign at any stage of the lifecycle.

Approve the AI-generated intelligence strategy for a campaign, optionally narrowing to specific audience tiers and creative angles. This locks in the plan before creative production starts. Required before calling zuckerbot_request_creative or zuckerbot_upload_creative.

Activate the ready audience tiers for an intelligence campaign after strategy approval and creative upload. Turns on paused Meta ad sets for each approved tier. Only tiers with valid paused executions and uploaded creatives are activated. Use this as the final step before a campaign goes live on Meta.

Launch a draft campaign on Meta (Facebook/Instagram). THIS IS THE MONEY ENDPOINT — it creates real ads on the user's Meta ad account and immediately begins spending their budget. Stored Meta credentials are auto-resolved when available. Set launch_all_variants=true to launch every creative variant as separate ads for A/B testing (Meta auto-optimizes for the winner). Always confirm the user has budget available and Meta is connected (zuckerbot_meta_status) before calling.

Pause or resume a running Meta ad campaign. Pausing stops ad delivery and spend immediately — the campaign stays in Meta but goes dark. Resuming restarts delivery without relaunching. Use pause when creative needs refreshing, budget is exhausted, or the user asks to stop spending.

Generate creative production briefs based on the business's tagged ad-performance patterns. Each brief specifies hook type, visual style, copy tone, CTA, and script guidance weighted toward the top-performing creative attributes. Use after running zuckerbot_creative_analysis to know which patterns to bias toward.

Build a Meta custom audience from hashed CAPI user data stored for a business, filtered by CRM lifecycle stage (e.g., 'lead', 'customer'). Use this as the first step to create retargeting or reactivation audiences from your own first-party CRM data.

Create a Meta lookalike audience from a stored seed audience. Expands a first-party seed (e.g., 'customer' stage) into a 1%, 3%, or 5% prospecting audience that Meta will target based on similarity. Typically used for the prospecting tier of an intelligence campaign.

List all stored Meta audiences for a business: seed audiences, lookalike audiences, sizes, delivery statuses, and CAPI source details. Use this to see what audiences are available before launching a campaign, or to find audience IDs for refresh and delete operations.

Rebuild a stored audience from fresh data. For seed audiences: re-hashes the latest CAPI events for the source CRM stage. For lookalike audiences: syncs the current size and delivery status from Meta after the seed refreshes. Use this when CAPI has received new events since the audience was last built.

Fetch the current Meta delivery status, size, and readiness for a stored audience. Updates the local audience registry row. Use this to check if an audience is large enough to use in a campaign before launch.

Permanently delete a stored audience from both Meta and ZuckerBot's local registry. This cannot be undone. Use when an audience is stale, was created in error, or you need to free up Meta audience slots.

Create a multi-tier audience portfolio for a business from a shared template (e.g., 'Local Services', 'eCommerce') or a custom tier array. Portfolios split the total budget across prospecting, retargeting, and reactivation tiers with per-tier CPA targets. After creating, call zuckerbot_launch_portfolio to launch all tiers on Meta.

Fetch the configuration and current performance snapshot for an audience portfolio by ID. Returns tier definitions, budget allocations, CPA targets, and live performance data. Use this to inspect a portfolio before launching or rebalancing.

Update the name, total daily budget, active status, or tier configuration of an existing audience portfolio. Changes to budget and tiers take effect on the next autonomous evaluation cycle. Use this to adjust a portfolio without relaunching all tiers.

Dry-run or execute a budget rebalance across portfolio tiers based on each tier's actual vs. target CPA. With dry_run=true (default) returns recommendations without making changes — useful for review before committing. With dry_run=false updates Meta ad set budgets and local records in one operation.

Launch all tiers in an audience portfolio on Meta. Creates separate Meta campaigns for each tier (prospecting, retargeting, reactivation) using the portfolio's budget allocations and CPA targets. Stored Meta credentials are auto-resolved. Tiers that lack required data (e.g., retargeting without a pixel, lookalike without enough seed events) are skipped with a reason.

Generate a brand-aware 1080×1080 static ad image. Automatically injects brand context (logo, colors, brand name, value props, social proof) from the business profile when business_id is provided — no need to pass brand data manually. Templates: stat_hook (statistic + supporting copy), pain_headline (bold headline + benefit bullets), testimonial (customer quote + portrait), feature_showcase (product + benefits). Returns a public image URL and QA scores. Present the image to the customer for approval; to generate more variants, call again with different parameters.

Generate a video ad through ZuckerBot's video generation pipeline (AI scripting → AI video → captioned overlay → hosted upload). ASYNC operation: returns a job_id immediately. Poll with zuckerbot_get_video_ad_status every 30 seconds for completion. Brand context is loaded server-side. Typical generation time: 5-15 minutes. Note: AI-generated video ads may face Meta ad review scrutiny — rejection tracking is built in.

Check the status of an async video ad generation job. Returns current status and, when complete, the final video URL. Also surfaces Meta ad review status and rejection reasons if the ad has been submitted to Meta. Poll every 30 seconds until status is 'completed' or 'failed'.

Dispatch a creative production request for an approved intelligence campaign. If a creative-production webhook is configured on the business, ZuckerBot generates full video scripts and fires the production payload. Use this when you want ZuckerBot to handle creative production end-to-end rather than uploading your own assets.

Generate standalone ad creative variants (images or video) using AI image and video models. Works independently of campaign creation — useful for quick mockups, creative testing, or building assets before attaching them to a campaign. If the description mentions video, reels, UGC, or TikTok, the tool auto-routes to the video model.

Upload finished creative assets (images or videos) to an approved intelligence campaign. ZuckerBot queues the Meta upload and ad-creation jobs asynchronously, then polls until they complete or the polling window expires. Use this when you have your own creative assets ready.

Check the asynchronous upload queue for an intelligence campaign to see if Meta ad-creation jobs are complete. Poll this after zuckerbot_upload_creative when the initial response shows creative_status='uploading'. Returns all_complete=true when every queued job has finished and the campaign is ready to activate.

Analyse creative performance patterns for a business by grouping ads by hook type, visual style, product focus, setting, CTA type, copy tone, or opening element. Returns average CPL/CTR/CPC/frequency per group, per-group trend direction, a structured insight object with recommendations, and can optionally include the top and bottom individual ads for the selected metric. Use this before generating new briefs to inform the creative strategy.

Cross two creative dimensions to find winning combinations. Example: hook_type × visual_style can reveal that curiosity + ugc outperforms pain_point + stock. Returns a performance matrix, best and worst combinations, and an actionable insight string.

Score proposed creative variants against the business's historical top-performing patterns. Accepts raw creative specs (copy, headline, CTA, asset URLs, frame URLs for video) and returns a pattern-match score for each. Use this before producing expensive creative assets to pre-validate concepts against what has historically worked.

Tag Meta ads with creative attributes (hook type, visual style, product focus, CTA type, copy tone, setting) by providing ad metadata and optional asset URLs. ZuckerBot uses Claude vision to analyze the creative and store structured tags. These tags feed the zuckerbot_creative_analysis pipeline. Run this after launching new ads to keep the creative intelligence database current.

Send downstream conversion quality feedback to Meta via CAPI. When a ZuckerBot-sourced lead converts (sale, appointment, qualified call) or bounces (uncontactable, bad fit), reporting it here teaches Meta's algorithm to find more (or fewer) people like them — improving lead quality over time. Call this from your CRM when a lead status changes.

List Meta Pixels available on the currently selected ad account and show which is currently selected for conversion tracking. Optionally select a pixel by providing select_id. The selected pixel is used for all future conversion tracking and CAPI attribution.

List Meta lead forms (Instant Forms) available on the selected Facebook Page and show which is currently selected. Optionally select a form by providing select_id to persist it for future lead generation campaign launches. Use this before launching a leads-objective campaign so ZuckerBot reuses the business's CRM-connected form rather than creating a new one.

Update the Conversions API configuration for a business. Set stage-to-event mappings (e.g., 'lead' → Meta Lead event), enable/disable delivery, change the CRM source, currency, optimisation target, or action source. Changes take effect immediately for new CAPI events. Use zuckerbot_capi_test to verify the updated config works.

Manually send a Conversions API event for a business contact/lead. Useful for debugging CAPI pipelines, testing stage mappings with real user data, or sending events from custom integrations not covered by the webhook. Authenticates with the business API key OR with an x-zuckerbot-webhook-secret header if using the webhook path.

Crawl a business website and extract structured intelligence used by campaign planning: company description, services, pricing signals, testimonials, location data, and brand tone. Run this before creating a campaign when the business has not been enriched yet, or use force_refresh after a website update to refresh stale context.

Return only the creative angles and audience tiers for a campaign draft — a lightweight alternative to zuckerbot_get_campaign when you need just the strategy summary without the full campaign payload, stored creatives, or tier execution details.

Fetch review intelligence for a business by name. Searches Google and Yelp to surface star rating, review count, recurring sentiment themes, and standout customer quotes that can be used directly in ad copy. Use before creating a campaign to identify proof points and objection-handling angles.

Scrape Meta Ad Library and search the web to analyse competitor ads in a given industry and location. Returns competitor positioning, common creative hooks, and exploitable gaps. Use before creating a campaign to benchmark against the competitive landscape and find differentiation opportunities.

Get market size, addressable audience estimates, and Meta ad benchmarks (CPL, CTR, CPM) for an industry and location. Use before creating a campaign to set realistic budget expectations and understand how large the targetable audience is. Also useful for proposals and client presentations.

Redeem a ZuckerBot lifetime licence code (format ZB-XXXXX-XXXXX-XXXXX) purchased on Dealify or AppSumo. Codes stack on one account: 1 code = Lifetime Tier 1 (1 ad account, 2,500 calls/mo), 2 codes = Tier 2 (3 accounts, 10K calls/mo), 3 codes = Tier 3 (10 accounts, 30K calls/mo). Redeeming upgrades ALL of the account's API keys to the new tier immediately.

Upload a text document (ad performance data, brand guidelines, customer data, sales data, or competitor analysis) so ZuckerBot can extract structured planning insights from it. Accepts raw text content — not binary files. Use this when the business has existing performance data or brand docs that should inform campaign strategy.

List all uploaded business-context files for a business along with their extracted summaries. Use this to confirm what planning documents are loaded before creating a campaign, or to check whether a previous upload was processed successfully.

List Meta ad accounts available to the connected user and show which is currently selected for launches and reporting. Optionally select an ad account by providing select_id — this clears the stored page selection so you can pick a matching page. Call this during setup or when switching between multiple ad accounts.

List Facebook Pages available to the connected Meta account and show which is currently selected for ad delivery. Optionally select a page by providing select_id. The selected page is used as the ad identity for all future launches.

Resolve and validate all stored Meta launch credentials for the authenticated user: access token, ad account, page, and pixel. Reports whether autonomous launch (no credential params needed at launch time) is possible. Call this after completing the setup sequence to confirm everything is ready before launching a campaign.