> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adstellar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Reference

> Every tool exposed by the AdStellar MCP server, with scopes and parameters.

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

<Note>
  Image and video generation tools consume AI credits from your team's balance; ad copy and every read-only tool below are free. Costs are per-model — use `list_models` to see them, and `get_credit_balance` to check your balance.
</Note>

<Note>
  **Workspaces.** A credential is granted access to specific workspaces (chosen on the consent screen or when the API key is created). Call `list_workspaces` to see which ones you can act on. Workspace-scoped tools accept an optional `workspaceId` — pass one to target a single workspace, or omit it to span every workspace the credential can access (writes default to the primary workspace).
</Note>

## 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`

## 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`

ElevenLabs TTS voices. **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)

<Note>Performance data is as fresh as the team's sync schedule — check `last_synced_at` in `list_ad_accounts`.</Note>

## 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. Charges image credits per generation (aspect ratio × variations).
**Scope:** `creatives:write` · **Params:** `aspectRatios` (required: `1:1`/`4:5`/`9:16`/`16:9`), `instructions?` (required without references), `variationCount?`, `referenceAssetIds?`, `brandKitId?`, `productId?`, `renderMode?` (`express`/`studio`)
**Returns:** `batchId`, `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 `batchId` (image) or `projectId` (video). Returns per-generation statuses, asset/video URLs when complete, errors when failed.
**Scope:** `assets:read` · **Params:** `batchId?`, `projectId?`

## Launch drafts

Launching real campaigns publishes ads and spends money — that stays a human action in the dashboard. Agents prepare drafts; humans launch.

### `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`

## Coming next

* Campaign mutation tools (pause/resume/budget) with explicit-confirm flow