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. The legacy agent tool names are retired; use this dispatcher.

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 it replaces the older social-data branches named below. discover trends (trends) across TikTok, Instagram, YouTube, and Kick; search comments server-side with sentiment (comments); synthesize scoped TikTok, Instagram, or YouTube comment themes and prose as a normalized table card (comment_mining: target is an @creator, a #hashtag — a bare word is read as a hashtag — or a video URL; platform optional, default TikTok), or analyze one video (video_analysis: video_url accepts a social video link or a public HTTPS .mp4/.mov/.webm/.m4v/.mkv file; for analysis-only requests about framing, shots or timing, use video_analysis with include_video_analysis=true. This watches the existing video without creating clips or drafts; include_video_analysis=false requests social metadata only). Both synthesis actions submit one owner-scoped job with an idempotency key and GET-only polling, not inline legacy cards. Read the DW aggregate trend report (report); and run bounded web research findings (research_web; save:true keeps the run as a Research Warehouse brief, save:false/omitted is one-shot). Analyze source videos for requested clips with clip_moments (1–10 social links, public HTTPS video files, GEN assets or numeric GEN video IDs; optional clip count, duration bounds, mode, presentation, aspect ratio, reframe, speed and enrich; one paid request returns per-source clips and failures). User-selected timestamp windows are exact media edits: use the existing media editor with the owned original source; clip_moments must carry source_start_seconds/source_end_seconds and refuses discovery for that selection. Do not replace a failed selected edit with viral discovery. The DW social warehouse is served directly too: search_posts (DEPRECATED — superseded by collect; still served; the GEN-3096 keyword search — the TikTok cached keyword path by default and the cross-platform search when platforms name more than tiktok, with the Common filter set on the entry), analyze_account (DEPRECATED — superseded by collect; still served: one account's profile + followers), transcribe and transcribe_status (DEPRECATED — superseded by collect url/id; still served: social video transcription by platform and its status), upload_by_ids (upload the stored media), comments_online (DEPRECATED — superseded by collect comments; still served: the live comment fetch beside the cached comments read), monitor_status (the DW monitoring read) and aura_user_stats (AURA stats by emails). hooks returns hook_text/pattern rows plus hook_clusters (pattern clusters) and a truthfulness block (returned, thin_result, note), and needs a scoped target: an @handle, #hashtag or keyword (HOOKS_TARGET_REQUIRED otherwise; HOOKS_UNAVAILABLE when the analyst is off). creators runs the same analyze job door and is served here. One call carries one or more typed actions. trends/hooks take query/mode/target/platform plus the reused CommonFilters bundle (no new dialect), an optional relevance_query, and a raw flag — results are analyzed by default and raw=True opts out to unanalyzed rows. comments takes a scope (query | video_ids | creator | hashtag) plus optional sentiment, days and limit; report takes window (1 | 7 | 30) and limit; research_web takes query plus optional mode (news|social|web|all), research-source platforms (x|news|web|reddit), days, limit, reddit_subreddits and save. A single URL reads its page; extract_assets discovers files, import_assets imports them, and asset_urls selects files. mode social is the community sources, X and Reddit. Research tie-break: 'Research X' the user wants kept or followed up is gen_analyze research_web with save:true (kept as a Research Warehouse brief); research_web is one-shot by default and never persists without save:true. research_scrape scrapes any source on the first call with bounded caps: source is a platform (tiktok, instagram, youtube, x/twitter, pinterest, kick, web) or any public URL, and input names the scrape target (keyword | hashtag | user… [4495 more characters not shown]

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 retired; use this dispatcher.

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 used when blank) and voice {voice_id, provider} defaults to the character's primary voice; with neither a voice nor a primary voice the call is refused. edit_talking_character saves a NEW talking character from a generated one and keeps the original: send the full clip list in the new order (reorder by order, delete by leaving a clip out), where {from_position} keeps that clip of the source. A kept clip whose prompt, duration and aspect_ratio are unchanged is reused: no render, no charge; give it a new prompt or duration to regenerate it. A {prompt, duration} item without from_position is a new clip and renders. The source's aspect_ratio applies unless one is sent. Every talking character carries aspect_ratio (9:16 | 16:9 | 1:1, or null when an uploaded video is none of them). Both are paid jobs priced before they run; they answer generation_id to poll with gen_discover generation, and op=get lists the talking character under generating_talking_characters until it is ready. Library characters are read-only: copy_to_mine makes your own copy, and create_talking_character or edit_talking_character on a library character saves into your copy. rename takes character_id and name, plus look_id or talking_character_id to rename that item instead. set_primary_voice sets the voice pre-selected for this character (voice {voice_id, provider}). delete_character, delete_look (its talking characters stay) and delete_talking_character are permanent: the first call answers CONFIRMATION_REQUIRED with would_destroy and confirm_token; repeat the call with confirm_token only after the user agrees. A talking-head video from an existing character is instead gen_vidsheet_action op generate, creation_card_type video_from_avatar (avatar_id = the character_id + video_url + audio_url).

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 already-authored scenes and caption lines in scenes (scene_number, time_range, duration, action, dialogue, text_overlays), and spoken words in full_script; captions alone do not imply speech. Then use create_video_from_idea with its returned idea_id and creation_mode=draft for Draft only. This uses the same manifest writer and compiler as saved ideas: never generate a batch of ideas, clone a template manually, or hand-write cell/layer edits to build that Draft. A saved idea's Draft/Full always uses create_video_from_idea with idea_id or idea_title and creation_mode=draft|full, never generic gen_vidsheet_action create_sheet/actions[] create or an invented template_slug. Use idea_title for a named saved idea; MCP resolves a unique match on agent_id and asks one plain question for several matches. Do not ask the user for a UUID. Its attached resources stay with the saved idea. create_video_from_idea uses gen-agentic's deterministic idea-to-Vidsheet compiler, in creation_mode draft | full (the idea card's Draft only / Create full video). Draft requires credits for LLM cost plus markup; no paid subscription is required. Media generation is billed separately; full bills credits for generated media, and omitting creation_mode defaults to billed full. With vidsheet_id the idea is added to that Vidsheet as a new row, or built into an existing row_id of it; otherwise a new Vidsheet is created. recreate_video turns a video into one expanded idea that recreates it shot for shot; reimagine_video turns a recreate idea (or a video) into several new ideas with the same pacing and a different subject; build a row from any of them with create_video_from_idea. recreate_video and reimagine_video return the job ({job_id, status}) and their ideas land in the gen_discover content.ideas view. Read the accepted job with gen_discover domain=content view=idea_job and the original job_id, as for generate_ideas. Every idea read returns next_steps with the exact calls it currently allows. set_idea_status moves it through generated | approve_to_create | ready_for_review | change_idea | change_video | rejected | approved_to_post | posted. One call carries one or more typed actions. Deleting is permanent — confirm the file with the user first. Read-only content access is gen_discover domain=content (resource | list | ideas | idea); this family's branch fields are gen_discover domain=content view=actions (target=<branch action>). The legacy content-resource and content-ideas tool names are retired; use this dispatcher. Ideas, scripts, trends and stats come only from GEN calls: never invent them, call GEN.

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.

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 Google sign-in is refused with reauthentication_required, and that change is made in the browser profile (gen_sign_in_link opens it). The legacy platform tool names are retired; use this dispatcher.

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 dispatcher. platform: tiktok | instagram | facebook | youtube | x | linkedin. Per-platform scheduling rules (also the gen_discover publish.rules view): tiktok: media required, video/image, 1 item, text <= 2200 chars; requires tiktok_privacy_level, tiktok_disable_comment, tiktok_disable_duet, tiktok_disable_stitch instagram: media required, video/image, up to 10 items, text <= 2200 chars; options via instagram_music (mode, track_url) facebook: media required, video, 1 item, text <= 63206 chars; title <= 255 chars youtube: media required, video, 1 item, text <= 5000 chars; title <= 100 chars; requires title; options via youtube_options (category_id, made_for_kids, notify_subscribers, shorts, tags, visibility) x: text or media, video/image, up to 4 items, text <= 280 chars linkedin: text or media, video/image/document, up to 9 items, text <= 3000 chars; title <= 400 chars; options via linkedin_options (alt_text, carousel, visibility) Update a post that is ALREADY LIVE via update_published_post — fix a typo, retitle, change tags or category. What each platform can still change once published: tiktok: no post-publication edit instagram: no post-publication edit facebook: no post-publication edit youtube: title, description, tags, category_id x: no post-publication edit linkedin: description Sparse: send only the fields you want changed and every other field on the live post is preserved. The reply carries one result per platform: `updated` (with the readback), `unsupported_after_publish` (the network has no edit path — nothing was touched), `reauthorization_required` (the user must reconnect that account) or `failed` with the platform's reason. Delete a post that is ALREADY LIVE via delete_published_post — it is two-phase: the first call previews and returns a CONFIRMATION_REQUIRED confirm_token, and only the exact retry presenting that token deletes. The reply carries one result per platform: `deleted`, `already_deleted` (GEN already removed it), `unsupported_after_publish` (the network has no delete path — nothing was touched), `reauthorization_required` (the user must reconnect that account) or `failed` with the platform's reason. timezone_offset on schedule_post_<platform> is the local UTC offset in hours (e.g. -7 for LA daylight); on publish_content it is minutes.

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.

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_id} (or the cell id) with values.value; row targets only take position, row_height and video_settings. Use gen_discover(domain='vidsheet', view='actions') for the full action schema. Card fields come from gen_discover view=card_schema. Creation-card generate accepts FE cards; job cards: sound_matching (overlays or row_id), recommend_song (audio_url — a PAID cover/remix of that one reference track, not a recommendation: for suggested songs read gen_discover view actions audio_library=recommended), song (prompt and duration, default 240), video_from_avatar and source_video_analysis. A whole column generates with the envelope {"action":"generate","target":{"kind":"column","vidsheet_id":..,"id":<column id>}}; Rails quotes the total first, refuses when credits cannot cover it, and returns per-row dispatched/failed/skipped. Prompt preview: creation_card_inputs.<text field>.ai.previewOnly=true; retry with the same idempotency_key while generating. Callers may delete layers, rows, cells and columns in Vidsheets they can edit. UI clients receive Rails' two-phase confirmation preview; headless clients send auto_confirm=true with each delete on its own to complete Rails' content-bound confirmation in one tool call. Export/render the final video = op generate, creation_card_type final-video, target the row's FINAL VIDEO cell; poll with gen_discover generation. This renders the VIDEO, not spreadsheet CSV export (envelope 'export' → Vidsheets::CsvExport). creation_card_inputs is optional; omitted, the row's layers build it. Call generate first for 'generate the intro' / 'talking-head' / 'title card', before reading the sheet — a 'title card' is creation_card_type text. Narration/voiceover of a video goes to gen_generate create_video, not a vidsheet cell op, unless the user names a sheet cell. A draft build or any edit that must not start paid dependent regeneration sends auto_regenerate=false: the batch performs only its writes, and Rails answers auto_regeneration: 'skipped'.

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.

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.

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.

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.

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.

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 tools/list never hides a branch's fields. Vidsheet domain (29 views) reads the editable video workspace; the other domains fold the legacy get/list tools: agent (detail | capabilities | core | settings | profile | profile_photos | list | shares | monitoring | execution_access) · asset (analysis | detail | libraries | list) · billing (balance | generation_access | usage | receipt | plans) · content (resource | list | ideas | idea | idea_job | video_job | directions) · location (countries | cities) · media (last_operation | operations | recommended_sounds | sound_library) · platform (me | organization | organizations | conversation | conversations | request_tree | preferences | api_keys | backups | members) · publish (post_status | rules | connect_url | connections | scheduled) · task (job | job_locator | run_status | list) · voice (list | mine | resource | preview_status | sample_status) · watchlist (detail | list) · social (comments | job; user_info/video_info/posts return typed unavailable with a live gen_analyze collect next step) · analyze (job — GET-only owner-scoped status/result for a gen_analyze trends/hooks/creators/research_web job by job_id; collect_enrichment — read the accepted collect enrichment job and its admitted analysis by job_id and agent_id; never resubmit either branch). Each view takes the id it names (resource_id, conversation_id, post_id, job_id, ...) plus that read's optional filters; publish.connect_url is the one non-pure view: the URL it returns STARTS the platform OAuth flow, so surface it to the user as a step. Social comments and job are provider-free DW reads. Social user_info, video_info and posts are not served as read-only data views because their legacy DW routes can refresh providers; they return a typed direction to the explicit live gen_analyze collect action. Social collection (typed, live, billed) is gen_analyze collect, never a view here. comments reads cached TikTok comment rows by video_ids; job reads one DW job status/result by job_id without resubmitting. The paid DW writes are NOT here: import URLs, live social scrapes and the wide general scrape are gen_analyze's import_urls / analyze_socials branches (they write S3 and bill). Vidsheet views: sheet (summary by default, include=["full"] for the whole dump) | rows | row | columns | cell | video (a row's video_settings + layers) | layers | layer | layer_analysis (one target's placement, media properties and the free read; the paid analysis is its own gen_analyze layer_analysis branch, one synchronous attributed model call behind a single-use confirm_token that answers the projected scene cuts, dead head/tail spans and suggested trim in/out in frames at 30 fps directly — no job to poll) | variables | available_variables | operations | last_operation | engine | template | templates | layout_validation | card_types (keyed by FE card type; produces/container/model filters) | card_schema (one creation card by FE card type, its job type, or the final-video render card) | card_matrix (the full Rails creation-card matrix: cards, models, per-model field rules, limits, talking_loop, song_max_duration_seconds — verbatim) | input_bindings (bind saved-input source_references into a card's fields through the served schema: returns bound_inputs + typed warnings, refuses an incompatible kind before any write) | card_from_job (map a completed job to a card without writing) | actions (the action envelope: every Rails action+target pair with its fields and one worked example, plus named workflows; focus one pair with target="<action>:<kind>", e.g. "update:column"; with a layer_type or audio_library filter it instead asks Rails' live discovery and returns that body — caption/text font: view actions with layer_type=caption lists the allowed styles.fontFamily values, set it with values.settings.styles.fontFamily; song recommendations: view actions with audio_library=recommended returns media with library_reference, put one on a sound layer with update value… [4249 more characters not shown]