GEN

Manage assistants and their profiles. One call carries one or more typed actions: set_profile (flat brand_name | description | competitors | identity_type | goal | target_platforms | shortform | longform | look | personality | persona_inspirations | research_topics | content_themes | monitored) | set_name (name) | set_location (catalog_version + country_code + city_id, sent alone) | set_primary_voice (default_user_voice {voice_id, source}) | set_primary_photo (the agent profile photo: profile_photo_url; null removes) | add_reference_images | remove_reference_images (agent reference images) | add_linked_account | remove_linked_account | complete_profile (description + linked_accounts) | create_agent | update_agent | delete_agent | create_agent_avatar | delete_agent_avatar (agent profile photos, read with gen_discover agent.profile_photos; an avatar with looks and talking characters is gen_characters) | add_agent_inspiration | create_look | connect_agent_elevenlabs | reset_agent_profile. Every settings field is the agent-core AgentCorePatch field of the same name and an unknown field is refused before any call. delete_agent/update_agent/set_name act on the named agent — call this tool first, even when the agent is only loosely named ('the draft agent I made yesterday'); the action names the agent_id field to supply. Do not list agents via gen_discover agent.list first. Setting which platforms the agent posts to — 'make me post on YouTube and TikTok' with no content or schedule to ship — is set_profile target_platforms here, not gen_publish_action. Read settings with gen_discover agent.settings (GET /core) and the location options with gen_discover location.countries / location.cities. Agent sharing is manager/owner-gated (share_agent, set_agent_share_role, revoke_agent_share, transfer_agent_ownership); revoke_agent_share and transfer_agent_ownership return a CONFIRMATION_REQUIRED preview and confirm first, and set_project_share (public | private) needs editor access.

Analyze real social data and research the web: collect is the typed collection seam — one synchronous DW /collect call per request, answered as model-visible evidence + a per-target coverage summary + result cards (never a job id, never PENDING). For a request to analyze N videos, use collect with count:N and enrich:"full"; listing or showing posts leaves enrich omitted. Omitted enrich collects post metadata only and does not analyze video footage. Report the collected and actually analyzed counts separately, preserving any admission/exclusion disclosure; never claim collected rows were analyzed videos. With enrich:"full" collect waits on the DW's full-enrichment job (transcript, hooks, visual analysis on every row) and answers GEN's written analysis plus one display card per row (thumbnail, @handle, view/like/comment counts, post date, post URL); the enriched per-video fields stay server-side unless include names them (transcript|hooks|visual_description|description|stats), and a job still running when the budget expires answers a PENDING receipt whose collect_enrichment_status action ({job_id}) polls the completed rows in the same shape. For other research and trends requests, use research_web, trends, hooks, creators, comment_mining or video_analysis directly; these jobs own collection and synthesis, so do not collect separately first. It takes targets [{platform, scope, target}] over scope user|hashtag|keyword|search|url|id|asset|account|creators|comments|sounds|ads and platform tiktok|instagram|youtube|pinterest|twitter|kick|twitch|meta_ads|tiktok_ads and freshness live (the default) or cache_then_live_deficit (cache_then_live_deficit serves stored rows free and fetches only the missing count live; cache_only is refused; every account target is paired in the same call with the same handle's user scope for that account's latest posts unless options.profile_only=true, and a comments action scoped only by video_ids is served live by collect's comments scope), and

Ask GEN anything in plain words: a question, or a build goal for the composer. gen_ask is for durable multi-step work and scheduled or recurring work: GEN plans it, pauses for approval and keeps it in one conversation. For a single action, call that action's typed tool directly. A chat sent without a conversation_id starts one; the result returns conversation_id and request_id, so send that conversation_id on the follow-up. gen_ask accepts any edit of existing media — trim/cut a time range, crop, reframe, extract audio, merge, speed, concat or overlay — run in GEN's compute environment, returning the produced file URL or draft. NOT record lookup: 'what did I ask/say before' is chat history — gen_discover platform.conversations — and when you already hold an id, use gen_discover. One call carries one or more typed actions: ask (question) | chat (message: a multi-step build goal; payment, publishing and other gated steps pause for approval via gen_task_action decide_agent_run). Content ideas are gen_content_action (generate_ideas | expand_idea | set_idea_status) and research is gen_analyze (research_web | report) — neither is served here. Uploaded files are analyzed on request — an image, video, audio, document or spreadsheet attachment — and a YouTube watch/shorts link is analyzed the same way; the answer comes back as text. ask and chat start agent runs and poll to completion by default; wait=false returns the run_id to poll with the gen_discover task.run_status view. A message into an active workflow conversation is refused with REQUEST_ACTIVE; ask/chat mode is refused there with WORKFLOW_INPUT_UNSUPPORTED. Legacy conversations may queue a message; the separate steer action, cancel_pending and stop drive that queue and the live run; reading the queue or the thread is a gen_discover platform.conversations / platform.conversation / platform.conversation_pending view, never a branch here. Do NOT ship posts here: gen_publish_action ships. The legacy ask tool names are

Manage the agent's asset library: analyze any asset_id or file url with kind video/image/audio (quoted, confirmed DW enrichment; documents are refused until DW supports them; cached repeats are free), poll the job with gen_discover domain=asset view=analysis, or upload a file in two steps (create_direct_upload, then complete_asset_upload with the signed_id), import a public video URL (import_asset_from_url), or delete an asset (delete_asset). Import takes a public HTTPS YouTube, TikTok, Instagram, or Kick video; arbitrary CDN/direct-file URLs are not supported. One call carries one or more typed actions. Deleting an asset is destructive — confirm with the user first. Read-only assets are gen_discover domain=asset (analysis | detail | list | libraries); this family's branch fields are gen_discover domain=asset view=actions (target=<branch action>). run_computer (command, optional profile default|media, secrets, egress_allowlist, run_id): run code in GEN's isolated computer — ffmpeg/ffprobe, Python with Pillow, a shell — to trim, cut, crop, reframe, overlay, merge, extract audio or transcode existing media, or any custom script no other tool covers; write produced files to /workspace/outputs/ and they come back as durable URLs in outputs; network is off unless egress_allowlist names hosts, and hosts other than GEN's asset hosts need a confirm_token round. The legacy asset tool names are retired; use this dispatcher.

Open a Stripe payment page for a workspace plan or credit pack with open_checkout (organization_id, credit_plan_id from billing.plans). Use open_checkout when the user asks to open checkout or subscribe to a plan; it creates a payment link and never charges a saved card. Do not use gen_sign_in_link for checkout: Stripe needs no GEN sign-in. prepare_funding_recovery (agent_id) returns the ready, non-charging checkout Rails names for a workspace a funding refusal stopped, reusing one still open. Buy GEN credits on the saved card with buy_credits or create and settle an x402 crypto purchase (create_x402_credit_purchase, settle_x402_credit_purchase). One call carries one or more typed actions. Buying credits spends real money — always confirm the plan and price with the user first. When the user asks to buy/top up/add credits, buy_credits is the first call — do not read billing.plans or billing.balance first; if the plan is not yet chosen the action names the credit_plan_id to supply next. Read owned workspaces' subscription status and Stripe invoice history with list_owned_subscriptions and list_owned_invoices; these never change billing. Credit balance, usage and plans are gen_discover domain=billing views. This family's branch fields are gen_discover domain=billing view=actions (target=<branch action>). The legacy billing tool names are retired; use this dispatcher.

Characters: one person each, with looks (images of the person) and talking characters (talking videos of the person with their voice, generated from a look or uploaded). For 'create a character', op=create is the first call — do not list characters or read gen_discover agent.profile_photos first (those are the agent profile photos, not characters). Reads (a viewer is enough): list (source my | library | all, default my; query searches names), get (character_id: its looks, each look's talking characters, the uploaded talking characters, the talking characters still generating and the primary voice), get_talking_character (one talking character with its clips). create makes a character from an image content resource (its original look) or a video of a person: the video becomes an uploaded talking character, its first frame the first look (the cover), and its audio is cloned into the character's primary voice. Cloning is a paid job priced before it runs (it needs 30 seconds of speech); clone_voice false skips it. clone_voice true refuses a video without audio or too short; without clone_voice such a video is created without a voice and voice_clone_message says why. create answers look_id, talking_character_id, voice_id (null until the clone finishes, then the character's primary_voice), user_job_ids (poll with gen_discover generation) and voice_clone_status. name defaults to the file name. upload_look adds an image and upload_talking_character adds a video to a character (clone_voice true also clones its voice into that character's primary voice, same rules and answer fields as create; off by default); upload or import the file first with gen_asset_action. create_talking_character makes a talking character from a look, lip-synced so it is saved with its voice: clips is 3 to 10 clips, each {prompt, duration 5 or 10}, and the look is the start and end frame of every clip; aspect_ratio 9:16 | 16:9 | 1:1 sets its shape (default 9:16). script is optional (a default line is

Manage an agent's content: its content resource files — create one from an uploaded file (create_content_resource), rename one (update_content_resource), or permanently delete one (delete_content_resource) — and its content ideas. generate_ideas is the content-ideas handshake: its first call answers needs_input (the fields to supply), a proposal (proposal_id + summary + plan) or running; reply with proposal_id + feedback for a new proposal, or proposal_id + confirm:true + count to start the idea job (use the user's final count, or the approved plan count if unchanged) (then poll gen_discover content.idea_job with that returned job_id for the batch's persisted ideas; 'ideas from run X' is gen_discover content.ideas with run_id=<X>, never idea_job). confirm=true without proposal_id is a fresh request, with the same needs_input/proposal/running behavior as omitting confirm; the response explicitly says so. A new batch takes brief/count/video_type/requirements/sheet_rows (optionally grounded in source_content_resource_id, source_analysis_job_id for ideas based on an existing gen_analyze result (a trends/hooks/creators/research_web job id, read with gen_discover domain=analyze view=job), or a target_duration_seconds); a refine takes from_ideas + feedback. Send prompt verbatim, all attachments with roles, content_idea, style, content, reference_video, format and cast when provided. Thread conversation_id on every call, and pass external chat words in conversation_context. Proposals offer exactly confirm or text feedback; needs_input is an error with questions. set_content_preference and remove_content_preference use scope long_term or session (24 hours). content.directions reads prior directions. expand_idea fleshes one saved idea out with idea_id or idea_title; idea_id takes precedence when both are supplied. An authored request ('make a Draft with these scenes') first uses save_idea with the user's brief verbatim, title, video_type_id, duration and canvas. Preserve alre

READ-ONLY. Live per-request JSON Schema forms: domain=contracts view=form target=<tool>[.<branch>] or a published output kind (StoryboardV1 aliases BuildPlanV1), agent_id required. Forms use the accepted tool contract and live choices. Versioned stage/job/delivery schemas: domain=contracts view=schemas (optional target model name). NEVER call this before an action and never to look up a target, plan, connection or id first: when the user asks to create/update/delete/publish/buy/top up/generate/clone/pause/resume/revoke/rename/train/transcribe, or asks a watchlist what it found ('what did my watchlist say/find'), call the matching action tool as the FIRST call — gen_generate (create_image/create_video/create_song/create_song_mix/transcribe), gen_vidsheet_action (any sheet edit or creation-card generate: title card, intro, talking-head), gen_characters (list/create characters), gen_ask, or the gen_<noun>_action family (billing, platform, task, agent, voice, watchlist, publish, content, asset). Call the action first even when an id, sample, plan or connection is not yet known: the action returns the missing field or the options. Use gen_discover only for a pure read. EXISTING-VIDSHEET TEXT-LAYER EDIT EXCEPTION: when changing a text layer that already exists on a Vidsheet, read that row's vidsheet.layers view first to bind the exact layer, save with gen_vidsheet_action, then read the same vidsheet.layers view again to verify the exact saved text — the save's own response is not proof of the sheet's current state. Step 3 (Read anything): THE discovery tool — every GEN read is a domain + view here. Every action family's branches are readable the same way: domain=<family domain> view=actions lists them with one line each, and target=<branch action> (for example domain=content view=actions target=reimagine_video) returns that branch's fields — name, type, required, enum values, description and default — from the same model the family validates an entry with, so a cached too

Send feedback about GEN (a bug, an idea, praise) from the user to the GEN team. Call it whenever the user wants to report a problem, complain, suggest something or say thanks. Pass the user's words verbatim in message. The agent, the recent GEN calls of this session and the client are attached automatically; never ask the user for them. Always relay the returned thank-you to the user.

Create media with GEN: generate an image (create_image), a video clip (create_video), an original song (create_song), a DJ-style song mix (create_song_mix), or transcribe audio or video into text (transcribe). One call carries one or more typed actions. Paid generations spend credits and each result carries generation_id, user_job_id and estimated_credits — poll the gen_discover generation view with generation_id until completed. create_image/create_video/create_song/create_song_mix/transcribe is the first call for those verbs (transcribe = any audio/video→text request, create_video = 'narrate a slideshow / make a video' — a plain narration/render belongs here, while a layered sheet/canvas edit is gen_vidsheet_action, create_song = 'make a song') — do not read gen_discover to find a resource, avatar or job first. Output is a standalone asset in the agent's library, not placed in a Vidsheet cell; to generate into a cell or layer use gen_vidsheet_action op=generate with creation_card_type. Narration/voiceover of a video goes to gen_generate create_video, not a vidsheet cell op, unless the user names a sheet cell. The legacy media tool names are retired; use this dispatcher.

Compose the weekly We Believe report's source-grounded ideas through the one billed content-ideas generator (the same path gen_content_action generate_ideas uses; this tool never calls a model directly). The caller injects the master playbook text, the measured comments and the verified first-party reference corpus with explicit freshness. The playbook text, the selected comment and the relevant verified references and peer evidence ground the one billed generation. This tool selects the unused comments at or above the like floor inside the rolling half-open window, runs one confirmed count=1 generation per selected comment with a stable idempotency key, reads exactly one saved idea back by that run's full run_id, and attaches the caller-known source identity and the approved alignment references. It never trusts a source key or citation the model echoes back. A missing, ambiguous or wrong-cardinality run refuses the whole build and leaves the last-good report untouched, and a credit refusal starts no generation. Ideas, scripts, trends and stats come only from GEN calls: never invent them, call GEN.

Workspace and access admin for an agent: create, rename, or delete an organization (create_organization, update_organization, delete_organization), upgrade its workspace plan (upgrade_workspace), manage its Personal Access Tokens (create_api_key, update_api_key, revoke_api_key, revoke_all_api_keys), set per-conversation session preferences (update_session_preferences), and back up GEN assets to Walrus for Proof of Genesis (create_proof_of_genesis_backup, remove_proof_of_genesis_backup). One call carries one or more typed actions. Deleting an organization, revoking all API keys, and upgrading a workspace are irreversible or spend money — always confirm with the user first. create_organization/update_organization/create_api_key/revoke_api_key act on the named workspace or key — call this tool first even when the id or new value is not yet known, and do not reply with a question before calling; the action names the missing field. Do not inventory organizations or api_keys with gen_discover first. Read-only platform views are gen_discover domain=platform (me | organization | organizations | conversation | conversations | preferences | api_keys | backups | members); this family's branch fields are gen_discover domain=platform view=actions (target=<branch action>). Workspace membership and roles are owner/manager-gated (invite_member, set_member_role, remove_member, leave_workspace); transfer_workspace_ownership, start_seat_checkout and upgrade_workspace return a CONFIRMATION_REQUIRED preview and confirm first. The first sign-in email of an agent-created account is added with request_email_link_code(email) then verify_email_link_code(request_id, code): the API emails a six-digit code, ask the user to read it from their inbox and pass it as a TEXT string, using resend_email_link_code(request_id) if it did not arrive. GEN never reads the inbox and never emits a code. Only an account with no email and no linked identity can link one; an account that already has an email or G

Step 5 (Export & Publish): Ship posts to social platforms — schedule, publish, update, or remove posts. One call carries one or more typed actions: schedule_post_<platform> (media_url and that platform's fields; schedule_type 'now' or 'specific_time' with scheduled_time; a field of another platform is rejected) | publish_content (platform + media_url + description + schedule_type) | update_scheduled_post (post_id + fields) | delete_scheduled_post (post_id) | update_published_post (post_id + at least one of title/description/tags/category_id) | delete_published_post (post_id; removes a post that is ALREADY LIVE and is two-phase — resend with confirm_token) | disconnect_social (platform; disconnects that account and is two-phase — resend with confirm_token). Reconnecting or refreshing an account is gen_discover publish.connect_url only — never disconnect_social first; connecting again replaces the old token. Publishing is irreversible: confirm destination and content with the user first. Do NOT edit videos here — the vidsheet action owns the canvas, and it is never the ship path. publish_content / schedule_post_<platform> / disconnect_social is the first call for those verbs, even when the user says 'all connected socials' or has not attached the post content yet — publishing resolves the connected accounts and the action names any missing media_url/description; 'disconnect my <platform>' is disconnect_social here, never a publish.connections read. Setting which platforms the agent posts to — 'make me post on YouTube and TikTok' with no content or schedule to ship — is gen_agent_action set_profile target_platforms, not schedule_post here. Read gen_discover publish.connections or publish.rules only when the user asks what is connected or what a rule is, not before publishing or disconnecting. Publishing is asynchronous even for 'now' — poll the gen_discover publish.post_status view with the returned post_id. The legacy publish tool names are retired; use this dispatche

Create a one-time GEN sign-in link for the caller's own account so its owner can open GEN in a browser. Requires the self-serve account owner's agent PAT. Use it when the user asks to sign in to GEN, open GEN, or get into the agent-created account from this client. For a plan or credit-pack checkout, use gen_billing_action open_checkout instead; Stripe needs no GEN browser sign-in. Pass the GEN URL they should land on, for example 'https://gen.pro/projects/123?view=editor#clip'; the same path, query and anchor are kept in the link. The link is valid for five minutes and works once, so treat it as a private handoff for the intended user alone: never post it publicly or send it to anyone else, because whoever opens it first signs in as this account. GEN applies its normal browser access checks when the link is opened, and the browser profile popup then offers to add an email address or link a Google account.

Run the task control plane: create, update, pause, resume, delete, duplicate, and run-now recurring jobs ('daily tasks' — a schedule plus a saved prompt), manage content-monitoring jobs, and approve or reject a gated agent run (decide_agent_run). One call carries one or more typed actions. pause_recurring_job/resume_recurring_job/delete_recurring_job act on the named job (update_recurring_job too) — call this tool first even when the job is only described ('my weekly report job'): name it by job_id OR by its exact display name (name; current_name on update_recurring_job, where name is the new title). Do not list jobs via gen_discover task.list first. The API resolves the name: several tasks with that name refuse with AMBIGUOUS_TASK_NAME and list candidates, so retry with one job_id; no match is NOT_FOUND. delete_recurring_job is two-phase: the first call only previews and returns a confirm_token; resend the same call with it to delete. Task results carry the API's card (a task_node with name, schedule_text, status, task_id) — show it. create_recurring_job answers reused=true when the task already exists (say it is already set up, do not report a new task) and conflict.fields when the request differed from the existing task (offer update_recurring_job). Hourly is a supported cadence; an unsupported cadence refuses with CADENCE_UNSUPPORTED and a suggested cadence. Read-only task views are gen_discover domain=task (list | job | run_status); this family's branch fields are gen_discover domain=task view=actions (target=<branch action>). The legacy task tool names are retired; use this dispatcher.

Upload a file into an agent's owned asset library without sending the bytes through the MCP call. One tool, three phases. phase=request_upload (default) takes agent_id, filename and content_type and returns upload_id, a same-origin signed PUT URL, a ready-to-run curl command and a browser drop_url; the signed capability expires in about 5 minutes and is single use. phase=create_drop returns the same thing framed for a browser when a client cannot run curl or hand over a host file. phase=status takes upload_id and returns the owned asset (id, url, filename, content_type, byte_size, checksum) once the bytes have landed, or an honest pending/unknown/expired/failed state. Claude and other sandboxed clients: put the bytes with the returned curl from the client sandbox. That requires mcp.gen.pro to be allowed in the Organization's Capabilities settings; change no customer setting, and use phase=create_drop if the PUT is blocked. Grok/Muse: there is no assumed laptop or sandbox path — use phase=create_drop. Local CLI: run the returned curl against a file you already have; the server never reads a path you name. ChatGPT and hosts that supply a file parameter: pass `file` with download_url, file_id and optionally mime_type/file_name; the server fetches it from the allow-listed host and returns the owned asset. Native file references are limited to 10 MiB; use create_drop for larger files. If the host gives no downloadable reference (or a 'chat_upload' placeholder), this answers with a create_drop fallback instead of guessing. Never send file bytes, a base64 blob or a local filesystem path through this tool.

Vidsheet: skill://gen/vidsheet-mcp/SKILL.md; host-approved resources/read or prompt vidsheet-mcp. Step 4 (Edit & Generate): the Vidsheet write tool for the editable video workspace. A direct saved idea draft/full uses gen_content_action action=create_video_from_idea; a separately authored scene-form storyboard uses apply_storyboard on one owned row. Generic create_sheet/actions[] create must not receive an idea_id. Discover template_slug with gen_discover vidsheet view=templates. Flat ops: create_sheet, clone_template, create_engine, duplicate_sheet, import_asset, validate_layout, continue_generation, refund_unused_output (service-only; completed output never delivered by an errored build; Rails owns eligibility and refund amount; requires agent_id, generation_id and idempotency_key), stop_generation (the provider may keep rendering and billing after an unconfirmed stop), add_column, set_cell, add_layer, update_layer and generate. apply_storyboard is MCP-only: applies a BuildPlanV1 to an owned row with read-back. Requires agent_id, vidsheet_id, storyboard, idempotency_key and row_id or row_position; recover=true reads without writes. A talking-head video from an existing avatar is the job card video_from_avatar (avatar_id + video_url + audio_url); the FE card video-from-talking-avatar generates a new talking-avatar video from a script and a voice — use video_from_avatar for a talking-head from an avatar, video-from-talking-avatar only when the user gives a script/voice or names that card. duplicate_sheet (name renames the copy) supports target_agent_id cross-agent copies. add_column validates position; set_cell validates media/take/song bindings and refuses job cards; add_layer/update_layer keep layer_row placement; trims send userHasTrimmed=true. Other edits use canonical actions[]; Rails validates with indexed errors. A row's column content (POST DESCRIPTION, IDEA, SCRIPT, any text or media cell) is a cell: update target {kind:'cell', vidsheet_id, row_id, column_i

Build a custom voice for an agent: clone one from an audio sample (clone_voice), design one from a scripted prompt flow (generate_voice_script, generate_voice_description, generate_voice_samples, design_voice), audition one with a spoken preview (preview_voice), or remove one you own (delete_voice). One call carries one or more typed actions. Deleting a voice is permanent — confirm which voice first. clone_voice/design_voice is the first call for 'clone/design my voice' — call it even if the user has not attached the sample yet; the action names the missing field to supply next. Do not inventory voices via gen_discover voice.mine first. Output is a standalone asset in the agent's library, not placed in a Vidsheet cell; to generate into a cell or layer use gen_vidsheet_action op=generate with creation_card_type. Read-only voice views are gen_discover domain=voice (list | mine | resource | preview_status | sample_status); this family's branch fields are gen_discover domain=voice view=actions (target=<branch action>). The legacy voice tool names are retired; use this dispatcher.

Run one or more watchlist operations in a single call: create, update, pause, resume or delete a watchlist, add or remove a monitoring source, or ask a question about a watchlist (query_watchlist starts an agent run and returns a run_id to poll). One call carries one or more typed actions. Deleting a watchlist or removing a source is destructive — confirm with the user first. delete_watchlist is two-phase like the vidsheet deletes: the first call returns a CONFIRMATION_REQUIRED preview with a single-use confirm_token and deletes nothing; resend the same call with that confirm_token to delete. remove_watchlist_source is two-phase the same way. Every branch that acts on one watchlist takes watchlist_id, or watchlist_name (a display name or its @list mention slug) as an alternative: a case-insensitive exact name or an equal @list mention slug as one candidate set, then a unique prefix. An ambiguous name returns the candidate watchlists and changes nothing. Any question about a watchlist ('what did my watchlist say…', 'summarize it', 'did it find anything') is query_watchlist and is the first call — it starts a run; gen_discover watchlist.list only enumerates saved watchlist records. Listing and fetching watchlists are gen_discover domain=watchlist (list | detail); this family's branch fields are gen_discover domain=watchlist view=actions (target=<branch action>). The legacy watchlist tool names are retired; use this dispatcher.