Tool Reference

All tools run as your team. Results are JSON. Errors come back as MCP isError content with a human-readable message.

​

Org

​

get_team_info

Team name, plan, industry, member/workspace counts. Scope: org:read

​

get_credit_balance

Current AI credit balance (available, reserved, included, used). Scope: org:read

​

get_brand_kit

The team’s brand kit: colors, fonts, tone of voice, description, buyer profiles. Scope: org:read · Params: brandKitId? (omit for default kit)

​

list_products

Products with name, description, url, linked brand kit. Scope: org:read · Params: limit? (default 50)

​

list_projects

Projects (asset folders) with item counts. Scope: org:read · Params: limit? (default 50)

​

list_ad_accounts

Connected Meta ad accounts: id, name, currency, timezone, status, last sync. Scope: org:read

​

Setup

Create the things every other tool reads. All three are free (no AI credits, no ad spend) and write only into your own team. The URL tools run a live website scrape plus an AI pass, so expect 30-90 seconds per call.

​

create_workspace

Create a workspace in the team (one per client or brand). The acting user must be a team owner or admin; they are added as the workspace admin. A credential granted specific workspaces does not automatically gain the new one — add it to the API key or re-authorize; a credential granted all workspaces sees it on its next call (check accessibleByThisCredential in the result). Scope: org:write · Params: name, description?

​

create_brand_kit_from_url

Scrape a brand’s website and save a brand kit: name, colors, fonts, tone of voice, target demographic, aesthetic, positioning, industry, and the logo stored as a media asset. Buyer profiles generate in the background afterwards — poll get_brand_kit until buyer_profiles_status is completed. Unlinked products on the same domain are linked to the new kit. Scope: org:write · Params: url, name? (override), isDefault? (defaults to true only when the workspace has no kit), generateBuyerProfiles? (default true), workspaceId?

​

create_product_from_url

Scrape a product, store or landing-page URL and create a product: name, description, selling points, CTA, category, brand colors, logo and up to 12 product images stored as media assets, plus an AI customer profile. Auto-links a brand kit on the same domain. Call list_products first if the product may already exist. Scope: org:write · Params: url, workspaceId?

​

Models

​

list_models

The multi-model registry. Filter by capability: image | video | tts | lipsync. Returns id, provider, cost, and supported options per model. Pass a model’s id as the model param of generation tools. Scope: models:read

​

list_avatars

Stock + custom talking-actor avatars: id, name, portrait, gender, age range, style, default voice. Scope: models:read · Params: includeCustom? (default true), limit? (default 100)

​

list_voices

The curated cloned voices every actor’s default comes from (not the public ElevenLabs library). Scope: models:read · Params: search?, limit? (default 50)

​

Copy

​

generate_ad_copy

On-brand ad copy variants (headline, subheadline, CTA, optional offer + body). Free — no credits used. Scope: copy:write · Params: productId?, brandKitId?, count? (1–10, default 5), tone?, length? (short/medium/long), adGoal?, customInstructions?

​

Analytics

​

query_performance

Synced Meta ads performance grouped by breakdown (campaign / ad set / ad / creative component) over a date range. Includes spend, impressions, clicks, results, ROAS, and budget fields. Scope: analytics:read · Params: breakdown?, preset? (e.g. last_7d), startDate?/endDate? (YYYY-MM-DD), adAccount?, campaignId?, adSetId?, limit? (default 50)

​

Assets

​

search_assets

Search the media library by file type, favorites, or name substring. Scope: assets:read · Params: fileType? (image/video), favoritesOnly?, search?, limit? (default 25)

​

lookup_asset

Full metadata for one asset, including Meta upload hashes and dimensions. Scope: assets:read · Params: assetId (required)

​

Campaigns

​

list_campaigns

Campaigns launched through AdStellar: status, objective, budget, spend, dates. Scope: campaigns:read · Params: status?, limit? (default 50)

​

get_launch_status

Launch records with creative counts and goal tracking. Scope: campaigns:read · Params: launchId?, limit? (default 25)

​

Generation (async)

Long-running generation uses a job pattern: the generate call returns an id immediately, and you poll get_generation_status until it completes.

​

generate_image

Generate AI image ad creatives through the same pipeline the AdStellar agent uses. One batch per aspect ratio, all in one project. Charges image credits per generation actually started; variationCount is clamped to the image model’s per-batch limit (currently 4), so read generationCount and creditsConsumed from the response rather than assuming aspectRatios × variationCount. Each aspect ratio starts independently: if a later ratio fails to start, the earlier batches keep rendering and stay charged, and the error names how many started and the projectId to poll. referenceAssetIds must resolve to at least one image asset (videos are skipped) or the call fails before anything is charged. Scope: creatives:write · Params: aspectRatios (required: 1:1/4:5/9:16/16:9), instructions? (required without references), variationCount?, referenceAssetIds?, brandKitId?, productId?, renderMode? (accepted for compatibility, ignored) Returns: projectId, batchIds, generationIds, creditsConsumed

​

generate_video

Generate an AI video ad. approach: "exact" = talking actor reads your script (requires actorId, scriptText); approach: "realistic" = cinematic UGC from scenePrompt. Optional model id from list_models. Scope: videos:write · Params: approach (required), scriptText?, actorId?, voiceId?, scenePrompt?, model?, aspectRatio? (default 9:16), durationSeconds? (default 15), variationCount?, productId?, productImageUrl?, tone? Returns: projectId

​

get_generation_status

Poll a job: pass projectId (image or video) or a single image batchId. Returns per-generation statuses, asset/video URLs when complete, errors when failed. Scope: assets:read · Params: batchId?, projectId?

​

Launch drafts

Launch drafts are dashboard shells (ad account + templates) for people finishing a launch in the app. To build and publish a campaign from an agent, use the Launch tools below.

​

list_launch_drafts

List the team’s launch drafts. Scope: campaigns:read · Params: limit? (default 50)

​

create_launch_draft

Create a draft (ad account + creative/audience templates, or clone fromTemplateId). Requires an active subscription. Publishes nothing. Scope: launches:write

​

get_launch_draft

Full config of one draft. Scope: campaigns:read · Params: draftId

​

delete_launch_draft

Delete a draft (does not affect live campaigns). Scope: launches:write · Params: draftId

​

Two-step confirmation

Every tool below that changes a live ad, spends credits, or creates a rule works in two calls. Without confirmationToken it returns { status: "confirmation_required", action, preview, confirmationToken, expiresAt } and changes nothing. Show the preview to the user; once they approve, call the same tool with the same arguments plus confirmationToken. Tokens last 10 minutes and are bound to the credential, the tool and the exact arguments (target, amount, status), so a token cannot be replayed for a different change.

​

Optimization

​

lookup_campaign

Find launched or imported campaigns by name fragment; returns Meta campaign ids. Scope: campaigns:read · Params: query?, limit?, workspaceId?

​

pause_campaign / resume_campaign / archive_campaign

Change a campaign’s status on Meta. Archive cannot be undone from AdStellar. Scope: campaigns:write · Params: campaignId, campaignName?, workspaceId?, confirmationToken?

​

update_campaign_budget

Set a campaign’s daily budget (CBO: shared budget; ABO: every ad set). Scope: campaigns:write · Params: campaignId, dailyBudget, campaignName?, workspaceId?, confirmationToken?

​

pause_ad_set / resume_ad_set / update_ad_set_budget

One ad set only. Ids come from query_performance with breakdown: "ad_set". Scope: campaigns:write · Params: adSetId, adSetName?, dailyBudget (budget tool), workspaceId?, confirmationToken?

​

pause_ad / resume_ad

One ad only. Ids come from query_performance with breakdown: "ad". Scope: campaigns:write · Params: adId, adName?, workspaceId?, confirmationToken?

​

Launch

Building is free; launching costs the same AI credits as in the app and publishes paused unless status: "active" is passed.

​

get_launch_options

Pixels, Pages and apps connected to an ad account, plus the objective/destination rules. Scope: campaigns:read · Params: adAccountId, workspaceId?

​

build_campaign

Run the AI Campaign Builder into a reviewable draft. Returns jobId. Scope: launches:publish · Params: adAccountId, objective, dailyBudget, destinationUrl?, destination?, conversionLocation?, conversionEvent?, pixelId?, pageId?, appId?, campaignName?, creativeAssetIds?, approvedCopy?, geos?, languages?, instructions?, workspaceId?

​

get_campaign_build

Poll the build: phase is preparing, preview_ready (with preview and draftId), publishing, live or failed. Scope: campaigns:read · Params: jobId, workspaceId?

​

launch_campaign

Publish a preview_ready build to Meta (two-step). Scope: launches:publish · Params: jobId, status? (paused default / active), confirmationToken?, workspaceId?

​

Automations

Feature-flagged per team. Rules evaluate synced data on a schedule and either queue suggestions (suggest_only) or act on their own (auto_run, owners/admins only).

​

get_automation_rule_schema

JSON schema of a rule, valid metrics/operators/windows/scopes/action kinds, a valid example and authoring guidance. Scope: automations:read

​

list_automation_rules

Scope: automations:read · Params: activeOnly?, limit?, workspaceId?

​

preview_automation_rule

Dry-run a saved rule (ruleId) or a draft (rule) against current data. Scope: automations:read

​

create_automation_rule

Validate, dry-run and save a rule (two-step). Scope: automations:write · Params: rule, workspaceId?, confirmationToken?

​

set_automation_rule_active

Pause a rule immediately or activate it (two-step). Scope: automations:write · Params: ruleId, isActive, confirmationToken?, workspaceId?

​

list_pending_automation_actions

Suggested actions awaiting a decision, with the rule that produced them. Scope: automations:read · Params: limit?, workspaceId?

​

approve_automation_action / reject_automation_action

Apply a suggestion to Meta (two-step) or decline it with a reason that teaches the rule. Scope: automations:write · Params: matchId, confirmationToken? (approve) · matchId, reason, note? (reject)