Agent Flow

Recommended Flow

1. Call get_workspace.
2. Call list_generation_catalog and list_workspace_assets.
3. If the user needs a voice, call recommend_voice.
4. If the user wants a template look, call list_generation_catalog again with section and template_slug, then choose a built-in preset_id or saved custom_reference_inspiration_id.
5. If the user provides reference media, use suggest_reference_template_targets, ask for the target if needed, then call create_reference_inspiration.
6. Call the matching create tool.
7. Poll the matching status tool until the result is completed or failed.
8. Only say the asset is ready when the final answer includes a visible preview, direct URL, or local file path.

Local Or Rendered Media

When the user or agent already has a rendered image, audio file, or MP4:

1. If the file is already reachable over HTTPS, call upload_editor_media with source_url.
2. Prefer upload_editor_media_from_url when the MCP client exposes it, because the URL source is explicit in the tool name.
3. If the file only exists on the agent machine, first upload it through the REST multipart endpoint or expose a temporary signed HTTPS URL.
4. Use the returned My Media media.id for publish_media_to_social, add_editor_media, or media-id fields in create_generation.

The hosted MCP server cannot fetch /local/path/file.mp4 or file:// URIs from the client machine. Do not place those strings in media.data; that field is only for base64 bytes or data URLs.

Prompt Handling

For template generations, preserve the user's prompt.

Pass it as-is or minimally trim tool-routing words. Do not expand a short request into a full creative brief unless the user asks.

Use built-in presets and saved reference inspirations as internal routing details. Do not expose raw ids unless the user asks for API or debugging details.

Retries

For paid create tools, pass idempotency_key when retrying.

Reuse the same key for the same paid action.

Do not create backup or variant generations unless the user asks for them.