MCP Tool Catalog

The NativeAds MCP server exposes 44 tools. This page lists each one with its purpose, key inputs, and behavior hints. See the MCP Guide to set up a client, and the REST API Guide for the underlying HTTP shapes.

New to the platform? Call get_started first for orientation, then follow the Recommended workflow below. It is the order that produces on-brand results.

Reading the annotations

Each tool carries hints that clients use to decide how to present it:

• Read-only — does not change any state.
• Idempotent — calling it again with the same input has the same effect.
• Destructive — overwrites or permanently removes data. Six tools are destructive: update_brand, update_brand_dna_version, patch_brand_dna_version, rerun_brand_dna_version, cancel_brand_dna_version and delete_brand_dna_version. Only the last two delete a row; the others replace content with no history, which the hint covers as well.
• Open-world — reaches something outside the platform, so its result is not fully predictable: it fetches a URL you supplied, or calls a generative model. Eleven tools are open-world.
• Async — returns a task id; poll get_task until terminal is true. Nine tools are async.

Unless noted, string ids are required. Optional inputs are marked.

Recommended workflow

Brand DNA is the platform's model of a brand's visual and verbal identity, and it is what makes generated creative on-brand. Create it before generating.

Guide, do not one-shot. When a human is present, do not silently create a brand and extract DNA end to end. Explain what you are about to do, ask what the user can provide (above all their logo and brand assets), and recommend the choices that raise quality. Confirm with the user before every meaningful action, creating the brand, starting Brand DNA, uploading assets, and generating; propose and wait for a yes rather than acting silently.

0. Orient — call get_started for the plan, whether Brand DNA is available, whether a brand exists, and a suggested next action. Read its choices block before generating: it lists every option the generation tools accept, the default that applies when you send nothing, what each call costs, and an ask level per decision (ask, propose, default) saying how hard to put that decision to the user. The options live there rather than in the tool schemas because the schemas ship on every session and this is fetched once.
1. Create the brand — ask the user for the brand name and their logo, propose an industry and a short description, and confirm these before calling create_brand (only name is required; or find an existing brand with list_brands). Do not upload the logo or other files yet: asset upload needs the brand to exist, so it happens in step 2.
2. Add Brand DNA and activate it — Brand DNA is the platform's model of the brand's visual and verbal identity and the single biggest driver of output quality, the core of what makes NativeAds on-brand. Explain this to the user, then guide them to get the most out of it: recommend the full set together, their logo and brand assets (images and videos), any brand-guideline PDFs, and their website URL(s). Do not assume a URL alone is enough or quietly fall back to URL-only. Call get_active_brand_dna; if it returns nothing, the brand has none yet. Confirm what the user will provide, add each asset and PDF by URL (import_asset_from_url, with isLogo: true for the logo; the server fetches it, there is no client-side upload), then call create_brand_dna_version with those assetIds and the website urls together. Proceed with a smaller set, or skip Brand DNA, only when the user explicitly declines; tell them the output will be off-brand, then it is their call. Poll get_brand_dna_version until its status is ready (get_task reports the workflow as completed, not ready). Then review it with the user: state the confidence score and any missing fields, and if the DNA is weak or missing the logo or brand colors, recommend adding it and offer to re-run with rerun_brand_dna_version. Correct wrong content via patch_brand_dna_version / update_brand_dna_version, then activate_brand_dna_version. Generation without active Brand DNA still runs, but output will be off-brand.
3. Enhance the prompt (recommended) — enhance_scene_forge_prompt / enhance_img2video_prompt, poll get_task until terminal, then read the result with get_scene_forge_prompt_enhancement / get_img2video_prompt_enhancement and review the enhanced prompt before generating.
4. Generate — scene_forge (images) or image_to_video (video); pass promptIsEnhanced: true when you use an enhanced prompt (for video, as userPrompts: [enhancedPrompt]). Feature the real product via productAssetIds (+ environmentAssetId); a Scene Forge image makes a strong startImageAssetId for every video model except seedance-2.5-pro. For seedance-2.5-pro (reference-to-video), upload reference images and/or videos, pass them as referenceImageAssetIds / referenceVideoAssetIds, and omit start/end/intermediate frames — those fields are rejected. Brand DNA is applied by default for scene_forge, but must be requested with useBrandDna: true for image_to_video and enhance_img2video_prompt. Newly uploaded assets must reach status complete (poll list_assets) before you reference them.
5. Retrieve output — poll get_task until terminal; the submit result's resultTool names the reader. A completed scene_forge returns several variations sorted best-first: present them all, relay each variation's warnings verbatim as non-fatal advisories, and skip any variation carrying an errorCode. Hand the user each variation's asset.assetUrl as a markdown link; those urls are signed and expire a few hours after they are minted, so call the reader again for fresh ones rather than reusing older link text. download_asset is for inspecting an asset yourself or fetching a file to save, not for showing one: on Claude web and Desktop a tool-result image never reaches the reply, and for a video asset download_asset returns no image block at all.

Clients that render MCP Apps show the output directly. Twenty-two tools declare a panel. Twenty of them follow one rule: if a result hands you a loadable media url, it renders. The other two, open_generation_options and open_brand_dna_options, compose a request rather than displaying a result — the user picks the model, length, audio and framing in one, and which assets and site URLs Brand DNA should read in the other, and each submits on their behalf, so those values never pass through the assistant. Generated variations, brand assets, logos, saved extraction picks and single-asset reads all render as ui://nativeads/generation-gallery; extraction candidates keep their own ui://nativeads/extraction-gallery; Brand DNA renders as ui://nativeads/brand-identity, a palette and typography view rather than a grid. On Claude web, Claude Desktop and ChatGPT these appear inline, with video playing in place. The host tells you when it happened by appending a note that an interactive widget was rendered — read it rather than assuming either way. Claude Code and plain API-key callers get no panel at all, which is why the links still matter.

A newly declared panel reaches a claude.ai connector only once that connector's cached tool list refreshes, so on an existing connection some of these render and some do not. Nothing about the result itself changes either way.

get_task reports status only, never the result payload — always read the actual output with the get_*/list_* tool the submit result named.

Iterating. For a cohesive set, hold productAssetIds, environmentAssetId, and theme constant and vary only the prompt, reusing one confirmed enhanced prompt across siblings. For more of the same look, prefer extend_scene_forge / extend_generated_videos_group over a fresh call. There is no seed or negative-prompt field; write "avoid X" into the prompt.

Choosing options. aspectRatio maps to placement: 9:16 stories/reels, 1:1 square feed, 3:4 portrait, 16:9 display/YouTube, 21:9 wide banner (2:3/3:2/4:3 also available). Choose deliberately; a mismatch can raise a hard-spec warning. image_to_video dimension takes pixels, but only their ORIENTATION reaches the renderer: taller than wide renders 9:16, anything else including a square renders 16:9. The presets are 1280x720 and 720x1280; a square or bespoke size is accepted, echoed back unchanged in the response, and still rendered as one of those two ratios, and the start frame is cropped to fit. Video has no equivalent of the eight image ratios. For seedance-2.5-pro, prompts bind references as @Image N / @Video N in the order of referenceImageAssetIds / referenceVideoAssetIds; dimension still applies.

Handling failures. A failed task carries an error class: UserRequestError (including content-policy) means fix inputs and do not resubmit unchanged (its message is safe to show); ModelProviderError is transient, retry later; NativeAdsSystemError, surface generically. get_task's retryable reflects this. On a tool error, data.type guides you: upgrade_required (plan lacks the feature, e.g. Brand DNA, or a limit is reached), payment_required (billing inactive or past due), conflict (re-read and retry), invalid_argument, not_found.

Connection errors happen before a tool runs (HTTP, not tool errors): 401 = missing/expired/revoked key or OAuth token; 403 = the credential is not a machine principal (mint a per-user API key); 429 = org rate limit, back off and slow polling.

Do not let a default stand silently. Several inputs apply a server default that changes the artifact or the bill, and get_started's choices names each one. The four that catch people out: model also sets the duration (the MCP default, seedance-2.5-pro, renders 8 seconds, where kling-v3-omni-pro renders 15), and it also decides which assets the call takes: seedance-2.5-pro is reference-to-video, so it needs referenceImageAssetIds and rejects startImageAssetId, while every other model requires a first frame; enableAudio defaults to false, so a video is silent unless you ask for sound, and grok-imagine-video ignores the flag entirely; scene_forge and extend_scene_forge each render and bill four images per call, with no way to ask for fewer; and partner defaults to default, which spec-checks nothing. Pass the same model, duration and enableAudio to enhance_img2video_prompt and image_to_video — the enhancer writes the prompt for the values it was given, so a mismatch means the approved prompt paces a different film than the one that renders.

isLogo deserves its own warning: it sets the asset's type at upload time and nothing can change it afterwards. An image uploaded without it can never be attached as a brand logo (update_brand rejects it as "not a logo"), and the only remedy is uploading the same file again. Ask before uploading, every time.

Language. This MCP surface currently returns English-canonical Brand DNA and enhanced prompts; there is no per-request output language yet. For video, the prompt is also translated to English immediately before rendering, so a prompt approved in another language is not the prompt that renders.

Brands

Tool	Purpose	Key inputs	Hints
create_brand	Create a brand in your organization. Only name is required.	name; optional industry, description, mission, values[], tone[], voice[], logoAssetId	write
list_brands	List brands, with optional filters.	optional industry, name, sortBy, page, limit	read-only
get_brand	Fetch a single brand.	brandId	read-only
update_brand	Update brand fields; only fields you pass change.	brandId; optional name, industry, description, mission, logoAssetId, values[], tone[], voice[]	idempotent

Brand DNA

Brand DNA is extracted asynchronously from uploaded assets and/or URLs. Exactly one version is active at a time; creating a version does not activate it, call activate_brand_dna_version once it is ready.

Every tool in this section requires a plan that includes Brand DNA, the read-only ones as well as the writes. Below that plan they all return upgrade_required, and get_started reports brandDnaAvailable: false. Check that field before offering the feature rather than discovering it on the first call.

Tool	Purpose	Key inputs	Hints
create_brand_dna_version	Start a new Brand DNA extraction from assets/URLs.	brandId; optional name, assetIds[], urls[]	async
rerun_brand_dna_version	Replace a version's source set and re-run extraction. Permanently discards that version's current DNA payload, including manual edits, and deletes its stored files. No undo, no prior revision to read back. Accepts a version that is currently active, which blanks the brand's live DNA until the new run finishes and is activated — prefer create_brand_dna_version to keep the existing one.	brandId, versionId; optional assetIds[], urls[]	destructive, async
activate_brand_dna_version	Make a version the active one (must be ready).	brandId, versionId	idempotent
cancel_brand_dna_version	Cancel an in-progress extraction.	brandId, versionId	destructive, idempotent
get_brand_dna	Fetch the active Brand DNA payload for a brand.	brandId	read-only
get_active_brand_dna	Fetch the active DNA version's detail.	brandId	read-only
get_brand_dna_version	Fetch a specific version's detail.	brandId, versionId	read-only
list_brand_dna_versions	List all DNA versions for a brand.	brandId	read-only
update_brand_dna_version	Rename and/or overwrite a version's canonical DNA payload (optimistic lock).	brandId, versionId, updatedAt; optional name, dna	destructive
patch_brand_dna_version	Apply a partial JSON Merge Patch to the DNA payload.	brandId, versionId, patch	destructive
delete_brand_dna_version	Permanently delete a version. Not reversible.	brandId, versionId	destructive

The urls input on create_brand_dna_version and rerun_brand_dna_version accepts only public http/https addresses.

Assets

The MCP transport never carries file bytes, so there are four ways to add a file — pick the one your client can do. None of them require anything client-specific from you.

1. The user has a public link → import_asset_from_url. The server fetches it.
2. Your client can make HTTP requests → initiate_asset_upload, PUT the bytes to the returned uploadUrl, then confirm_asset_upload. This is the standard presigned-upload pattern, and the cheapest for large files: bytes go straight to storage and never pass through the model's context.
3. Your client renders MCP Apps UI → open_asset_uploader. An upload panel appears in the conversation and the user drops the file into it; the panel reserves, uploads and reports the asset itself, so do not call initiate_asset_upload or confirm_asset_upload after it. Use this when a PUT is not possible — notably Claude web and Claude Desktop, where the code sandbox's egress allowlist blocks the upload host outright.
4. Neither is possible → initiate_asset_upload also returns uploadPageUrl. Show it to the user; they upload in a browser and it confirms itself. No confirm_asset_upload needed.

A file the user attached to the conversation is a special case. On ChatGPT it is handed to import_asset_from_file directly. No Anthropic client exposes an attachment's bytes or a fetchable URL to a server, and none can today: the mechanism that would allow it (the MCP File Uploads working group's file inputs) is not yet in the specification. On those clients, use open_asset_uploader and let the user drop the file into the panel.

Tool	Purpose	Key inputs	Hints
import_asset_from_url	Fetch a file from a URL and commit it as an asset.	brandId, url; optional fileName, isLogo, categoryId	write, open-world
import_asset_from_file	Commit a file the user attached in the conversation.	brandId, file (download_url, file_id; optional file_name, mime_type); optional isLogo, categoryId	write, open-world
initiate_asset_upload	Reserve an upload; returns uploadUrl and uploadPageUrl.	brandId, files[] — each needs fileName and fileType only; optional fileSize, dimension (width, height), duration (seconds; send it for a video used as a Seedance 2.5 reference), isLogo. Optional categoryId	write
confirm_asset_upload	Confirm after you PUT to uploadUrl.	uploadId; optional categoryId	write
open_asset_uploader	Show an upload panel in the conversation; it uploads and reports the asset itself.	brandId; optional isLogo, categoryId	write
get_asset	Read one asset by id.	assetId	read-only
list_assets	List assets with optional filters. type includes logo — a brand logo is stored as logo, not image.	optional brandId, type, status, tags[], campaignId, page, limit	read-only
download_asset	Return a short-lived presigned download URL.	assetId	read-only

import_asset_from_url derives the file type and image dimensions from the fetched bytes, so you do not declare them. Supported types: JPEG, PNG, GIF, TIFF, MP4, QuickTime, PDF, DOC, DOCX, and the TTF/OTF/WOFF/WOFF2 fonts. Maximum 500 MB.

The URL must be a public http(s) address. Requests to loopback, private, link-local, and other reserved ranges are refused, at submit time and again on every redirect. The same guards apply to the download_url inside import_asset_from_file.

Turn a page URL into assets

When the user has a page rather than a file (a product page, a property listing, a service page), this finds the images on it, ranks them by how central they are to the page's subject, and stages them for review. Nothing becomes an asset until the user picks.

Tool	Purpose	Key inputs	Hints
extract_assets_from_url	Scrape and rank a page's images. Runs in the background.	brandId, url; optional purpose, media	async, open-world
get_url_extraction	Read status and ranked candidates, best first.	extractionId; optional includeRejected	read-only
commit_url_extraction_candidates	Save chosen candidates as assets on the brand.	extractionId; optional items[] (candidateId, isLogo)	write, idempotent

The flow is submit, poll, show, commit. extract_assets_from_url returns a task id: poll it with get_task, then call get_url_extraction. A run scores at most 40 unique images, fetching more than that if the page serves the same photo at several sizes. truncated reports how many heuristic survivors it never got to — the page had more candidate images than one run scores. Near-identical shots the ranker held back are NOT counted there; they come back with kept: false under includeRejected=true and are still committable.

Candidates come back as inline images so you can see and describe them, plus a signed url each. Two shared budgets bound how many render as images; when they bind, the result carries a line reading Showing N of M candidates as images and the rest are text-only. Read that line rather than assuming you saw everything. Present them all and let the user choose rather than picking on their behalf. Note that some clients show tool-result images only inside the collapsed tool-use view, so describe what you see rather than assuming the user is looking at the same thing.

Each candidate's url expires 4 to 8 hours after it was minted. Call get_url_extraction again to mint a fresh one rather than storing the value.

Omit items on the commit to save every kept candidate. Commit-all never includes rejected candidates — a rejected one can only be saved by naming its candidateId explicitly. There is no commit-nothing shape, so never call the tool when the user has selected nothing. Pass items to save a subset and to mark one as the brand logo; isLogo also stores the asset as a logo and skips the image-processing pass, so it is complete as soon as the commit returns rather than needing a poll. Flag it on the first commit — setting it later on an already-saved candidate does nothing.

Committing is idempotent per candidate, so a retry returns the assets it already created instead of duplicating them. It is not atomic across candidates: the first failure returns immediately and leaves the earlier ones saved, which is exactly why retrying is the right recovery.

purpose tunes ranking and how many candidates come back. scene_forge favours clean, isolated, croppable product shots and returns at most 10; video allows scenic and establishing shots; any has no lean, and is what an omitted or blank value means. Matching ignores case, hyphens and spaces, so Scene Forge reaches the scene_forge profile.

Anything else is free text and is used, not discarded: it keeps any's thresholds and limit while the text itself goes to the ranker as a statement of intent, so it re-tunes the ordering. "Facebook ad creative for first-time buyers" is a valid purpose and ranks differently from sending none. Capped at 300 characters. Nothing is ever rejected here.

media defaults to both; video extraction is not available yet, so an explicit videos is refused rather than silently returning images. Until it ships images and both are identical — only <img> elements are read, and every candidate comes back with mediaType: image.

Uncommitted candidates are not charged, not quality-assessed, and not visible in the asset library. Their staged copies expire 30 days after the run.

Withdrawing a scrape is REST-only

To remove an extraction and its uncommitted staged copies immediately, call DELETE /v1/assets/extract-from-url/{extractionId}. There is no MCP tool for it — assets already committed are unaffected, so nothing an agent produced is at risk from its absence.

Use import_asset_from_url instead when the user already has a direct link to the file itself.

import_asset_from_file takes the file object your client supplies for a user-attached file and fetches its download_url server-side. If the client hands over only a file id with no download_url, the file cannot be retrieved and the tool says so — ask the user for a link and use import_asset_from_url instead.

Uploading bytes directly

The same flow is on REST for API-key callers: POST /v1/assets/initiate-upload → PUT → POST /v1/assets/confirm-upload, plus POST /v1/assets/cancel-upload/{uploadId} to abandon a reservation. cancel_asset_upload is REST-only.

uploadPageUrl is short-lived and single-use, and is omitted entirely in environments where URL signing is not configured.

Generation

Tool	Purpose	Key inputs	Hints
scene_forge	Start a Scene Forge image generation.	brandId, blendingPrompt; optional promptIsEnhanced, useBrandDna, theme, aspectRatio, productAssetIds[], environmentAssetId, partner	async
open_generation_options	Show a panel where the user picks the model, length, audio and framing, with the cost stated, and submits the run themselves. Prefer it over calling a generation tool with values the assistant chose. The panel submits, so do not call scene_forge / image_to_video after it — poll get_task. It renders no asset picker, so a first frame or Seedance 2.5 references must be passed in here; picking seedance-2.5-pro with no references disables the submit rather than failing the call, as does opening it with no first frame for a model that needs one. The review screen shows the prompt in an editable box, so the user can correct the wording before spending; pass promptIsEnhanced: true when those words should render as written, and the panel forwards it through the edit.	brandId, kind (video | image), prompt; optional startImageAssetId, referenceImageAssetIds (max 30), referenceVideoAssetIds (max 10), promptIsEnhanced	panel
open_brand_dna_options	Show a panel where the user chooses which assets and which site URLs Brand DNA should read, then presses Build or Skip. Open it to offer Brand DNA rather than starting one: the panel submits create_brand_dna_version itself, so do not call that after it. Brand DNA is recommended and optional — Skip is a complete answer, it blocks nothing, and generation still works without it. The URL field is editable because the page a user pastes and the page worth crawling are not always the same, and the panel states that the crawl reads that page plus up to 29 pages linked from it.	brandId; optional assetIds (pre-ticked), urls (pre-filled)	panel
generate_environment	Generate a background/setting image from a description, for use as scene_forge's environmentAssetId. The web app offers both an Upload and a Generate-from-prompt tab for the backdrop; this is the generate half. Costs image quota.	brandId, prompt	async
get_environment_generation	Read a generate_environment run. Once completed it carries the generated asset, whose id goes to scene_forge as environmentAssetId.	environmentGenerationId	read-only
enhance_scene_forge_prompt	Enhance a Scene Forge prompt.	brandId, originalPrompt; optional productAssetIds[], environmentAssetId, useBrandDna, partner	async
image_to_video	Start image-to-video generation. seedance-2.5-pro is reference-to-video (refs-only).	brandId, userPrompts[], dimension; startImageAssetId (required except seedance-2.5-pro); optional endImageAssetId, intermediateImageAssetIds[], referenceImageAssetIds[], referenceVideoAssetIds[], model, duration, enableAudio, useBrandDna, promptIsEnhanced, partner	async
enhance_img2video_prompt	Enhance an image-to-video prompt. seedance-2.5-pro is refs-only.	brandId, originalPrompt, aspectRatio (16:9 or 9:16 only); startFrameAssetId (required except seedance-2.5-pro); optional endFrameAssetId, intermediateFrameAssetIds[], referenceImageAssetIds[], referenceVideoAssetIds[], model, duration, enableAudio, useBrandDna	async
get_scene_forge_prompt_enhancement	Fetch an enhancement's result (optimizedPrompt, theme) to review before generating. promptEnhancementId is the task id enhance_scene_forge_prompt returned.	brandId, promptEnhancementId	read-only
get_img2video_prompt_enhancement	Fetch an enhancement's result (enhancedPrompt) to review before generating. promptEnhancementId is the task id enhance_img2video_prompt returned.	brandId, promptEnhancementId	read-only
extend_scene_forge	Add more image variations to a completed Scene Forge, reusing its recipe (prefer over a fresh scene_forge for more of the same look).	sceneForgeId	async
extend_generated_videos_group	Add one more video variation to a completed group, reusing its recipe. Call it again for another.	groupId	async
list_scene_forges	List Scene Forge generations for a brand.	brandId; optional status, partner, page, limit, sortBy, sortOrder	read-only
list_generated_video_groups	List image-to-video generation groups for a brand.	brandId; optional partner, page, limit, sortBy, sortOrder	read-only

Video model options: seedance-2.5-pro (the MCP default; refs-only / reference-to-video), veo-3.1, veo-3.1-fast, kling-v3-pro, kling-v3-omni-pro, grok-imagine-video, seedance-1.5-pro, seedance-2.0-pro, pixverse-v6, optimized. The REST default stays seedance-2.0-pro: only the MCP surface defaults to 2.5, because 2.5 rejects the first frame the REST flow normally sends.

seedance-2.5-pro is reference-to-video. Pass referenceImageAssetIds (bound as @Image N in list order) and/or referenceVideoAssetIds (bound as @Video N in list order), at least one reference total. Omit startImageAssetId, endImageAssetId, and intermediateImageAssetIds on image_to_video, and omit startFrameAssetId, endFrameAssetId, and intermediateFrameAssetIds on enhance_img2video_prompt; those fields are rejected for 2.5. Do not send the reference arrays on any other model; they are rejected there.

2.5 reference limits depend on the plan tier. The absolute ceilings, which no plan exceeds, are 30 reference images and 10 reference videos. Lower tiers allow fewer reference images, no reference videos at all, and a shorter maximum duration, so a video-only job is not available on every plan. Exceeding the caller's tier returns upgrade_required instead of a video. Call get_started to read the organization's plan before promising a reference-video job.

Reference asset requirements, all enforced at submit before any generation is booked. Reference images: JPEG or PNG, 120MB or smaller, uploaded as an image, logo, or environment asset (an asset NativeAds generated for you reports fileType as the bare category image and is accepted as-is). Reference videos: MP4 or QuickTime, 200MB or smaller, 1.8 to 30.2 seconds each, 30.2 seconds combined, 23.8 to 60 FPS. A reference video whose duration has not been measured yet is rejected rather than queued: conflict while it is still processing, which is worth retrying, and invalid_argument once it reports complete without a duration, which needs a re-upload.

useBrandDna defaults differ by media: it is on by default for scene_forge and enhance_scene_forge_prompt, but off by default for image_to_video and enhance_img2video_prompt — pass useBrandDna: true to apply Brand DNA to video.

Brand DNA requires a plan that includes it. On a plan that does not, every Brand DNA tool returns upgrade_required, reads included, and the two paths through useBrandDna differ on purpose: sending useBrandDna: true fails with upgrade_required, while omitting the flag resolves it to false and the generation runs without Brand DNA. Nothing fails for a caller who never asked for the feature, but the output is generic — so read brandDnaAvailable from get_started before you promise a user on-brand results. When Brand DNA is not on the plan, the choices block omits the useBrandDna row entirely.

Orientation, tasks and usage

Tool	Purpose	Key inputs	Hints
get_started	Orientation for a cold start: plan, subscription/lockout, whether Brand DNA is available, whether a brand exists, role, a plain-language nextAction, the industries vocabulary, and a choices block giving every generation option, its default, its cost and how hard to ask the user about it. Call it first.	none	read-only
get_task	Fetch an async task's status. Poll until terminal is true; succeeded marks a clean finish, and retryable (on failure) says whether resubmitting may help.	taskId; optional wait (seconds, max 90)	read-only
list_recent_tasks	List recent async tasks to recover task ids lost after a disconnect (including enhancement ids, which have no other list tool). Each task_id is the id the matching get_*/list_* tool consumes.	optional kind (scene_forge, image_to_video, enhance_scene_forge_prompt, enhance_img2video_prompt, brand_dna_version, extract_assets_from_url), status (pending, processing, completed, failed, cancelled), limit. There is no brandId filter	read-only
get_feature_usage	Read your organization's consumption versus plan caps (image and video pools).	none	read-only

Working with async tools

The ten async tools (create_brand_dna_version, rerun_brand_dna_version, extract_assets_from_url, scene_forge, extend_scene_forge, enhance_scene_forge_prompt, image_to_video, extend_generated_videos_group, enhance_img2video_prompt, generate_environment) return a task id immediately. Poll get_task with that id until terminal is true (workflow status becomes completed, failed, or cancelled — note get_task reports completed, not the brand-DNA-version word ready), then read the finished resource with the tool the submit result named in resultTool. Pass wait to block instead of spinning: get_task with wait=90 holds the request open until the task is terminal or 90 seconds pass, so one call replaces about twenty status reads and you never need to sleep between them. If it comes back with terminal: false, call it again. wait is capped at 90 because the MCP route's own timeout is 120s; a larger value is clamped, not rejected. Omitting it keeps the old immediate-return behaviour.

A write tool's submit result also carries a settings block: used is what the run will actually render with (the resolved model, the resolved duration, the aspect ratio that will really be produced), defaulted names the inputs the caller never chose, and billed states the cost in pool units. Tell the user what is under defaulted and offer to change it before generating again — a re-run costs the same as the first run. A fully specified call carries no defaulted list at all.

The result's nextStep tells you when to stop rather than leaving you to judge it: while the task is still within a budget set from how long its kind can legitimately take, nextStep says to keep waiting; past that it switches to a hand-back. Those budgets differ by an order of magnitude — a prompt enhancement is capped in seconds, a seedance-2.5 video in tens of minutes — so do not substitute a cadence of your own.

The finished resource per async tool: Brand DNA → get_brand_dna_version / get_active_brand_dna; URL extraction → get_url_extraction; prompt enhancements → get_scene_forge_prompt_enhancement / get_img2video_prompt_enhancement (this is where the enhanced prompt text lives — get_task does not carry it); generations → list_scene_forges / list_generated_video_groups, which render the generation gallery panel and carry each variation's asset.assetUrl.