Forge function reference

Use the quickstart first. Every call uses the active brand and normal MCP sign-in and access rules. Checked 2026-11-09: 17 query actions and 19 management actions. These are contract entries, not a promise that every source format or client can execute them. Fetch only the action you need with help_describe {tool, action}. Some connectors advertise an older action enum. If your client cannot represent an action, refresh its tool discovery or use a client that exposes the current contract; do not silently substitute another action. The operation index supplies compact routing facts. Full inputs stay in runtime discovery. Fields marked required below include action-specific validator requirements that a flat JSON schema may omit. Successful Forge results use {status: "ok", action, result}; read the fields below inside result.

render_preview is a preflight, not a pixel render. Inspect saved delivery settings: omitted settings inherit. Show the person the rows, destinations and any spend before confirming. Use the exact confirmationToken returned by the Forge action.

At a glance

Action	What it does	Role
`forge_query.templates`	List granted or built render templates.	Viewer or higher
`forge_query.template`	Read exposed variables, required values, budgets, outputs and contractHash.	Viewer or higher
`forge_query.sets`	List saved sets, optionally filtered by templateKey.	Viewer or higher
`forge_query.set`	Read saved rows, inherited effective values and delivery settings.	Viewer or higher
`forge_query.set_revisions`	Read kept states of a set.	Viewer or higher
`forge_query.destinations`	Read delivery and approval destinations.	Viewer or higher
`forge_query.jobs`	List render jobs, optionally filtered by templateKey, setId, batchId or status.	Viewer or higher
`forge_query.job`	Refresh a single render job and its output files.	Viewer or higher
`forge_query.batch`	Read a batch, waiting briefly for its jobs to settle.	Viewer or higher
`forge_query.scenes`	List accessible 3D scenes and their fillable keys.	Viewer or higher
`forge_query.set_diff`	Compare two rows or two kept states as rendered.	Viewer or higher
`forge_query.template_tree`	Read branches, revision history, publications and the default variant.	Viewer or higher
`forge_query.template_layers`	Read editable compositions and layers of a revision.	Viewer or higher
`forge_query.template_revision`	Read a revision and its source identity.	Viewer or higher
`forge_query.template_diff`	Compare edits of two revisions of one template.	Viewer or higher
`forge_query.template_run`	Read the publishing run for this exact revision source.	Viewer or higher
`forge_query.sources`	List the brand’s uploaded template sources and parse/build state.	Viewer or higher
`forge_manage.set_create`	Save rows for one template.	Operator or higher
`forge_manage.set_update`	Update a saved set with a revision check.	Operator or higher
`forge_manage.set_fork`	Copy the current set or one of its kept states.	Operator or higher
`forge_manage.set_delete`	Delete a saved render set.	Operator or higher
`forge_manage.suggest_rows`	Draft values from a brief, documents or media.	Operator or higher
`forge_manage.apply_suggestions`	Append selected draft rows once.	Operator or higher
`forge_manage.source_begin`	Create a signed-in mixed-file upload handoff.	Operator or higher
`forge_manage.source_status`	Read upload readiness and classified resource IDs.	Operator or higher
`forge_manage.source_figma`	Import Figma frames as design templates, or list the frames in a Figma file.	Operator or higher
`forge_manage.render_preview`	Validate selected rows and show where each result will go.	Operator or higher
`forge_manage.render_confirm`	Redeem the reviewed preflight token and queue the batch.	Operator or higher
`forge_manage.scene_fill`	Fill an accessible scene from the brand and brief.	Operator or higher
`forge_manage.scene_render`	Redeem a reviewed scene fill and queue its outputs.	Operator or higher
`forge_manage.rows_patch`	Upsert or remove selected rows with a revision check.	Operator or higher
`forge_manage.set_retarget`	Pin an existing set to a published template revision.	Operator or higher
`forge_manage.template_preview`	Preview proposed edits without saving a revision.	Operator or higher
`forge_manage.template_save`	Save edits as a new immutable revision.	Operator or higher
`forge_manage.template_forge`	Start or advance publication of an eligible revision source.	Admin or Owner
`forge_manage.template_set_default`	Choose the variant everyone opens by default.	Admin or Owner

Sources

`forge_query.sources`

List the brand’s uploaded template sources and parse/build state.

Contract	Behavior
Required inputs	`action`
Conditions	Use only identifiers returned for this brand.
Returns	items: assetId, family, parseState, forgeState; more
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"sources"}.

`forge_manage.source_begin`

Create a signed-in mixed-file upload handoff.

Contract	Behavior
Required inputs	`action`
Conditions	Use only identifiers returned for this brand.
Returns	`upload_intent_id`, `open_url`, `expires_at`, `max_files`
Role	Operator or higher
Side effects	Creates an upload intent; completing an eligible source upload can start automatic preparation.
Potential spend	No generation started by this call.
Confirmation	Explain automatic preparation and smoke-render spend and obtain permission BEFORE completing an eligible source upload; waiting for `template_forge` does not prevent it.
Completion	Returns inline; upload, parsing and eligible preparation continue separately.
Retry	Do not retry blindly: another call creates another handoff.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_manage","action":"source_begin"}.

`forge_manage.source_status`

Read upload readiness and classified resource IDs.

Contract	Behavior
Required inputs	`action`, `upload_intent_id`
Conditions	Use only identifiers returned for this brand.
Returns	documentIds, mediaAssetIds, templateAssetIds, `source_refs`, sources
Role	Operator or higher
Side effects	Reads the handoff; saves nothing.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again while processing.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_manage","action":"source_status"}.

`forge_manage.source_figma`

Import Figma frames as design templates, or list the frames in a Figma file.

Contract	Behavior
Required inputs	`action`, `figmaUrl`
Conditions	Uses the brand’s Figma connection and the signed-in person’s Continuum session. Read `forge_query` sources until parsed, then `forge_query` template for its text columns.
Returns	File link without figmaNodeIds: fileKey, fileName, frames, next (nothing imported). Frame link or figmaNodeIds: fileKey, assets, templateAssetIds, templateKeys (web: plus the asset id), next
Role	Operator or higher
Side effects	A file link lists its frames and imports nothing. A frame link, or figmaNodeIds (up to 5), imports each frame into the Library as a design template that renders as its templateKey with no build.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	If the call times out, repeat it with the same arguments: it joins the import still running.
Errors	`INTEGRATION_REQUIRED`: connect Figma for the brand; `PERMISSION_DENIED`: the brand’s Figma account can’t open this file; `NOT_FOUND`: no such Figma file or frame; UNAUTHENTICATED: no signed-in session; import from the Forge page instead; `VALIDATION_ERROR`: not a figma.com/design link

Schema: help_describe {"tool":"forge_manage","action":"source_figma"}.

Template revisions

`forge_query.templates`

List granted or built render templates.

Contract	Behavior
Required inputs	`action`
Conditions	Use only identifiers returned for this brand.
Returns	items: key, bindingId, sourceAssetId; nextCursor
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"templates"}.

`forge_query.template`

Read exposed variables, required values, budgets, outputs and contractHash.

Contract	Behavior
Required inputs	`action`, `templateKey`
Conditions	Use bindingId from discovery when the key matches multiple workspaces.
Returns	Template contract; layout is omitted
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"template"}.

`forge_query.template_tree`

Read branches, revision history, publications and the default variant.

Contract	Behavior
Required inputs	`action`, `assetId`
Conditions	Use only identifiers returned for this brand.
Returns	templateId, defaultVariantId, variants[].revisions
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"template_tree"}.

`forge_query.template_layers`

Read editable compositions and layers of a revision.

Contract	Behavior
Required inputs	`action`, `revisionId`
Conditions	Use only identifiers returned for this brand.
Returns	Layer inventory and supported edits
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"template_layers"}.

`forge_query.template_revision`

Read a revision and its source identity.

Contract	Behavior
Required inputs	`action`, `revisionId`
Conditions	Use only identifiers returned for this brand.
Returns	Revision: id, variantId, sourceAssetId, sourceVersionId, edits
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"template_revision"}.

`forge_query.template_diff`

Compare edits of two revisions of one template.

Contract	Behavior
Required inputs	`action`, `revisionId`, `toRevisionId`
Conditions	Use only identifiers returned for this brand.
Returns	from, to, edits
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`VALIDATION_ERROR`: revisions must belong to one template

Schema: help_describe {"tool":"forge_query","action":"template_diff"}.

`forge_query.template_run`

Read the publishing run for this exact revision source.

Contract	Behavior
Required inputs	`action`, `assetId`
Conditions	Use only identifiers returned for this brand.
Returns	run (may be null), state and needs when present
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"template_run"}.

`forge_manage.template_preview`

Preview proposed edits without saving a revision.

Contract	Behavior
Required inputs	`action`, `assetId`, `parentRevisionId`, `edits`
Conditions	Read `template_layers` first. Edits are also checked against the revision edit contract.
Returns	Edited layer values, svgBytes, next; no SVG body
Role	Operator or higher
Side effects	Validates and previews; saves nothing.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Re-read state after an uncertain response; no general replay guarantee.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_manage","action":"template_preview"}.

`forge_manage.template_save`

Save edits as a new immutable revision.

Contract	Behavior
Required inputs	`action`, `assetId`, `parentRevisionId`, `edits`
Conditions	Exactly one of name (new branch) or variantId (extend its current head). Requires a signed-in user session.
Returns	revision (id, variantId, sourceAssetId), replayed
Role	Operator or higher
Side effects	Writes a source/version and revision; preserves the Original. Eligible saved sources can automatically prepare and publish.
Potential spend	Yes: parsing the saved package can start automatic preparation and smoke-render spend.
Confirmation	Obtain explicit permission for saving and its automatic preparation/spend BEFORE `template_save`; there is no separate render-preview token for this path.
Completion	Returns inline.
Retry	Same save derives a replay key; optional UUID idempotencyKey. Re-read after a head conflict.
Errors	`PERMISSION_DENIED`: signed-in session required; CONFLICT: branch head changed

Schema: help_describe {"tool":"forge_manage","action":"template_save"}.

`forge_manage.template_forge`

Start or advance publication of an eligible revision source.

Contract	Behavior
Required inputs	`action`, `assetId`, `step`
Conditions	step=start needs templateName; step=decisions needs decisions. Native HTML/components/Blender do not use this action.
Returns	source or run, next; inspect `template_run`
Role	Admin or Owner
Side effects	Changes publishing state; can run smoke renders and publish automatically.
Potential spend	Yes: smoke renders can spend provider budget, including after start.
Confirmation	Obtain explicit permission for this publishing run and its smoke-render spend before starting; this action has no `render_preview` token.
Completion	Returns inline; inspect `template_run` while the run continues.
Retry	Read `template_run` first. Step in only where parked; on CONFLICT re-read instead of replaying steps.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_manage","action":"template_forge"}.

`forge_manage.template_set_default`

Choose the variant everyone opens by default.

Contract	Behavior
Required inputs	`action`, `assetId`, `variantId`
Conditions	Use only identifiers returned for this brand.
Returns	templateId, defaultVariantId
Role	Admin or Owner
Side effects	Changes the default template variant.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Re-read `template_tree` before retrying; confirm the intended default.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_manage","action":"template_set_default"}.

Render sets

`forge_query.sets`

List saved sets, optionally filtered by templateKey.

Contract	Behavior
Required inputs	`action`
Conditions	Use only identifiers returned for this brand.
Returns	Saved render sets
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"sets"}.

`forge_query.set`

Read saved rows, inherited effective values and delivery settings.

Contract	Behavior
Required inputs	`action`, `setId`
Conditions	Use only identifiers returned for this brand.
Returns	id, revision, rows, resolved, settings, template revision pin
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"set"}.

`forge_query.set_revisions`

Read kept states of a set.

Contract	Behavior
Required inputs	`action`, `setId`
Conditions	Use only identifiers returned for this brand.
Returns	Kept set revisions for `set_fork` or `set_diff`
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"set_revisions"}.

`forge_query.set_diff`

Compare two rows or two kept states as rendered.

Contract	Behavior
Required inputs	`action`, `setId`
Conditions	Supply rowIds=[a,b], or fromRevision with optional toRevision (default: current).
Returns	Differences in effective values and render settings
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"set_diff"}.

`forge_manage.set_create`

Save rows for one template.

Contract	Behavior
Required inputs	`action`, `templateKey`, `name`, `rows`
Conditions	Use bindingId when ambiguous; templateRevisionId, when supplied, must identify a published revision.
Returns	Saved set: id, revision, rows and template pin
Role	Operator or higher
Side effects	Creates a saved set; queues no renders.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	No general replay guarantee; discover existing sets after an uncertain response.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_manage","action":"set_create"}.

`forge_manage.set_update`

Update a saved set with a revision check.

Contract	Behavior
Required inputs	`action`, `setId`, `expectedRevision`
Conditions	settings merges named keys; null clears nullable settings. Prefer `rows_patch` for surgical row changes.
Returns	Saved set with its new revision
Role	Operator or higher
Side effects	Writes supplied fields; rows replaces the ENTIRE row list.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	On `render_set_revision_conflict`, re-read set and reconcile; never replace expectedRevision blindly.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_manage","action":"set_update"}.

`forge_manage.set_fork`

Copy the current set or one of its kept states.

Contract	Behavior
Required inputs	`action`, `setId`
Conditions	Use only identifiers returned for this brand.
Returns	New set: id, revision and rows
Role	Operator or higher
Side effects	Creates a separate set; optional revision selects a kept state.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	No general replay guarantee; inspect sets after an uncertain response.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_manage","action":"set_fork"}.

`forge_manage.set_delete`

Delete a saved render set.

Contract	Behavior
Required inputs	`action`, `setId`
Conditions	Use only identifiers returned for this brand.
Returns	deleted: set ID
Role	Operator or higher
Side effects	Deletes the set.
Potential spend	No generation started by this call.
Confirmation	Ask for an explicit yes before calling. This action directly deletes; it does not issue its own confirmationToken.
Completion	Returns inline.
Retry	Do not retry blindly; re-read the set after an uncertain response.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_manage","action":"set_delete"}.

`forge_manage.suggest_rows`

Draft values from a brief, documents or media.

Contract	Behavior
Required inputs	`action`
Conditions	Provide setId or templateKey, and prompt or documentIds or mediaAssetIds. parentRowId requires setId.
Returns	Unsaved suggested rows with stable draft IDs and field evidence
Role	Operator or higher
Side effects	Uses AI; saves nothing.
Potential spend	AI drafting may consume model budget.
Confirmation	Use only when the person’s request authorizes AI drafting and its potential model spend; that request is sufficient consent. No server confirmation token is issued.
Completion	Returns inline.
Retry	Another call drafts again; retain selected draft IDs for `apply_suggestions`.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_manage","action":"suggest_rows"}.

`forge_manage.apply_suggestions`

Append selected draft rows once.

Contract	Behavior
Required inputs	`action`, `setId`, `expectedRevision`, `rows`
Conditions	Every selected row must retain its draft id.
Returns	setId, revision, appliedRowIds, replayed
Role	Operator or higher
Side effects	Appends the selected drafts, preserving other rows.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Selected draft IDs provide replay protection; on a genuine revision conflict, re-read and reconcile.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_manage","action":"apply_suggestions"}.

`forge_manage.rows_patch`

Upsert or remove selected rows with a revision check.

Contract	Behavior
Required inputs	`action`, `setId`, `expectedRevision`
Conditions	Supply nonempty rows or removeRowIds. Ask for explicit consent before removing rows.
Returns	Updated set and resolved rows
Role	Operator or higher
Side effects	Changes only selected rows; omitting a row ID appends a new row.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Use stable row IDs; re-read on a revision conflict. ID-less appends can duplicate on retry.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_manage","action":"rows_patch"}.

`forge_manage.set_retarget`

Pin an existing set to a published template revision.

Contract	Behavior
Required inputs	`action`, `setId`, `expectedRevision`, `templateRevisionId`
Conditions	Use only identifiers returned for this brand.
Returns	Updated set and template revision pin
Role	Operator or higher
Side effects	Changes the template pin after validating existing rows.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Re-read on revision conflict; do not substitute an unpublished or unrelated revision.
Errors	`VALIDATION_ERROR`: `template_revision_unpublished`; CONFLICT: `render_set_revision_conflict`

Schema: help_describe {"tool":"forge_manage","action":"set_retarget"}.

Rendering

`forge_query.destinations`

Read delivery and approval destinations.

Contract	Behavior
Required inputs	`action`
Conditions	Use only identifiers returned for this brand.
Returns	Slack/approval destinations, Meta account IDs, next
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"destinations"}.

`forge_query.jobs`

List render jobs, optionally filtered by templateKey, setId, batchId or status.

Contract	Behavior
Required inputs	`action`
Conditions	Use only identifiers returned for this brand.
Returns	items containing job IDs and status
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"jobs"}.

`forge_query.job`

Refresh a single render job and its output files.

Contract	Behavior
Required inputs	`action`, `jobId`
Conditions	Use only identifiers returned for this brand.
Returns	Render job, status and available outputs
Role	Viewer or higher
Side effects	Refreshes stored status; starts no new render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"job"}.

`forge_query.batch`

Read a batch, waiting briefly for its jobs to settle.

Contract	Behavior
Required inputs	`action`, `batchId`
Conditions	Use only identifiers returned for this brand.
Returns	batchId, done, counts, jobs[].outputs
Role	Viewer or higher
Side effects	Refreshes stored status; starts no new render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Bounded wait: waitSeconds 0–55; use 50 in a background task until done=true.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"batch"}.

`forge_manage.render_preview`

Validate selected rows and show where each result will go.

Contract	Behavior
Required inputs	`action`, `setId`
Conditions	Omitted delivery/final settings inherit from the saved set; inspect them. null slackDestinationId disables posting. final=true requires Admin/Owner.
Returns	Readiness, destinations, confirmationToken, next
Role	Operator or higher
Side effects	Preflight only; queues no renders.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Refresh after changed inputs or an expired token. Override a refusal only after the person agrees to its named flag.
Errors	`VALIDATION_ERROR`: `render_fonts_missing`; CONFLICT: `render_set_revision_conflict`

Schema: help_describe {"tool":"forge_manage","action":"render_preview"}.

`forge_manage.render_confirm`

Redeem the reviewed preflight token and queue the batch.

Contract	Behavior
Required inputs	`action`, `confirmationToken`
Conditions	Use only identifiers returned for this brand.
Returns	batchId and render job records
Role	Operator or higher
Side effects	Queues rendering and the reviewed delivery/approval work.
Potential spend	Yes: rendering can spend provider budget.
Confirmation	Show readiness, rows and destinations; wait for the person’s yes, then pass the exact returned confirmationToken.
Completion	Returns a batch immediately; read `forge_query` batch/job.
Retry	Single-use token. After an uncertain response inspect existing jobs; do not obtain another token and blindly render twice.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_manage","action":"render_confirm"}.

Scenes

`forge_query.scenes`

List accessible 3D scenes and their fillable keys.

Contract	Behavior
Required inputs	`action`
Conditions	Use only identifiers returned for this brand.
Returns	items: assetId, versionId, outputs, field keys
Role	Viewer or higher
Side effects	Reads state; starts no render.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	Safe to read again.
Errors	`needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason

Schema: help_describe {"tool":"forge_query","action":"scenes"}.

`forge_manage.scene_fill`

Fill an accessible scene from the brand and brief.

Contract	Behavior
Required inputs	`action`, `assetId`, `versionId`
Conditions	Use assetId/versionId/output IDs returned by scenes.
Returns	values, outputs, confirmationToken; nothing rendered
Role	Operator or higher
Side effects	Reads brand inputs and signs the proposed fill; renders nothing.
Potential spend	No generation started by this call.
Confirmation	None for this action.
Completion	Returns inline.
Retry	On `scene_version_stale` re-read scenes; a new fill creates a fresh confirmation.
Errors	CONFLICT: `scene_version_stale`; `VALIDATION_ERROR`: `scene_output_unknown`

Schema: help_describe {"tool":"forge_manage","action":"scene_fill"}.

`forge_manage.scene_render`

Redeem a reviewed scene fill and queue its outputs.

Contract	Behavior
Required inputs	`action`, `confirmationToken`
Conditions	The service reloads the current scene at submission; immutable scene-version execution is not guaranteed. Recheck scenes before confirming; if it changed, fill/review again.
Returns	assetId, values, jobs[], next
Role	Operator or higher
Side effects	Queues one scene render per output into the Library.
Potential spend	Yes: scene rendering can spend provider budget; this response does not supply a price estimate.
Confirmation	Show filled values and outputs, explain potential spend (estimate may be unavailable), wait for a yes, then pass the exact `scene_fill` token.
Completion	Scene jobs use the template’s scene history in Forge and the Library; they are not Forge render-set batches.
Retry	Token is single-use; after an uncertain response inspect history before another fill/render.
Errors	`VALIDATION_ERROR`: `expired_confirmation`; CONFLICT: `confirmation_spent`

Schema: help_describe {"tool":"forge_manage","action":"scene_render"}.

Recover from a refusal

Revision conflict: re-read the set or template head, reconcile the intended change, and preview again. A set’s numeric expectedRevision is different from a template revision UUID.
Ambiguous template key: select the discovered bindingId; do not guess a workspace.
Insufficient role: preserve needs_role or PERMISSION_DENIED and request the appropriate brand role. final=true and template publication need Admin or Owner.
Expired or spent token: inspect existing jobs first if submission may have succeeded. Otherwise preview/fill again and obtain a new yes; never turn an uncertain response into an automatic second render.
Missing fonts or another overridable refusal: pass a flag only when details.overrides names it and the person explicitly accepts that specific problem. Other refusals remain blocking.
Partial or failed batch: inspect each job. done=true means settled, including failures; it does not mean every output succeeded. Preserve job IDs and reasons.
Scene jobs: use the template’s scene history in Forge and the Library. Do not pass a scene job ID to the render-set job API without a supported contract.

No Forge webhook subscription or cancellation action is established by this catalog. Your host application starts MCP calls and retains their identifiers.

Example call sequences

These are sequential MCP tools/call parameters, not an executable batch. UUIDs, tokens, template and variable keys are illustrative: substitute the exact discovered values. Populate required template fields before preflight. Obtain permission for automatic preparation/spend before completing a source upload or saving a revision; pause for the person’s yes before render confirmation. A render price estimate may be unavailable. Keep each returned identity for the next call. After publication, rediscover the matching template key/binding and use the published revision UUID. For scenes, recheck the version before confirming; the service still reloads the current scene. Follow the individual action’s conditions above.

An existing template

The discovered binding is 666…; set_create returns set id 555…; render_confirm returns batchId 777…. Replace each with its actual returned value. The illustrative headline key must also be replaced by an exposed variable key.

[
  {
    "name": "forge_query",
    "arguments": {
      "action": "template",
      "templateKey": "discovered-template-key",
      "bindingId": "66666666-6666-4666-8666-666666666666"
    }
  },
  {
    "name": "forge_manage",
    "arguments": {
      "action": "set_create",
      "templateKey": "discovered-template-key",
      "name": "Example set",
      "rows": [
        {
          "id": "22222222-2222-4222-8222-222222222222",
          "parentId": null,
          "label": "Example",
          "overrides": {
            "headline": "Your message"
          }
        }
      ],
      "bindingId": "66666666-6666-4666-8666-666666666666"
    }
  },
  {
    "name": "forge_query",
    "arguments": {
      "action": "set",
      "setId": "55555555-5555-4555-8555-555555555555"
    }
  },
  {
    "name": "forge_manage",
    "arguments": {
      "action": "render_preview",
      "setId": "55555555-5555-4555-8555-555555555555",
      "slackDestinationId": null,
      "final": false
    }
  },
  {
    "name": "forge_manage",
    "arguments": {
      "action": "render_confirm",
      "confirmationToken": "token-returned-by-render-preview"
    }
  },
  {
    "name": "forge_query",
    "arguments": {
      "action": "batch",
      "batchId": "77777777-7777-4777-8777-777777777777",
      "waitSeconds": 50
    }
  }
]

A supported source revision

Upload intent: 888…. Uploaded source asset: 111…. Observed parent revision: 222…. template_save returns revision.sourceAssetId=333… and revision.id=444…. Use 333… for template_run/template_forge, and the published 444… for templateRevisionId. After publication, rediscover templateKey and bindingId (666…). The template_forge start example is CONDITIONAL: skip it if a run already exists. Wait for publication before set_create.

[
  {
    "name": "forge_manage",
    "arguments": {
      "action": "source_begin"
    }
  },
  {
    "name": "forge_manage",
    "arguments": {
      "action": "source_status",
      "upload_intent_id": "88888888-8888-4888-8888-888888888888"
    }
  },
  {
    "name": "forge_query",
    "arguments": {
      "action": "sources"
    }
  },
  {
    "name": "forge_query",
    "arguments": {
      "action": "template_tree",
      "assetId": "11111111-1111-4111-8111-111111111111"
    }
  },
  {
    "name": "forge_query",
    "arguments": {
      "action": "template_revision",
      "revisionId": "22222222-2222-4222-8222-222222222222"
    }
  },
  {
    "name": "forge_query",
    "arguments": {
      "action": "template_layers",
      "revisionId": "22222222-2222-4222-8222-222222222222"
    }
  },
  {
    "name": "forge_manage",
    "arguments": {
      "action": "template_preview",
      "assetId": "11111111-1111-4111-8111-111111111111",
      "parentRevisionId": "22222222-2222-4222-8222-222222222222",
      "edits": {}
    }
  },
  {
    "name": "forge_manage",
    "arguments": {
      "action": "template_save",
      "assetId": "11111111-1111-4111-8111-111111111111",
      "parentRevisionId": "22222222-2222-4222-8222-222222222222",
      "edits": {},
      "name": "Example variant"
    }
  },
  {
    "name": "forge_query",
    "arguments": {
      "action": "template_run",
      "assetId": "33333333-3333-4333-8333-333333333333"
    }
  },
  {
    "name": "forge_manage",
    "arguments": {
      "action": "template_forge",
      "assetId": "33333333-3333-4333-8333-333333333333",
      "step": "start",
      "templateName": "example-template"
    }
  },
  {
    "name": "forge_manage",
    "arguments": {
      "action": "set_create",
      "templateKey": "discovered-template-key",
      "name": "Example set",
      "rows": [
        {
          "id": "22222222-2222-4222-8222-222222222222",
          "parentId": null,
          "label": "Example",
          "overrides": {
            "headline": "Your message"
          }
        }
      ],
      "bindingId": "66666666-6666-4666-8666-666666666666",
      "templateRevisionId": "44444444-4444-4444-8444-444444444444"
    }
  }
]

An accessible scene

scenes supplies assetId 111… and versionId 222…. scene_fill returns the reviewed token; scene_render returns separate jobs[].jobId values. Recheck the scene before confirmation; the current service does not enforce the token’s source version at render time.

[
  {
    "name": "forge_query",
    "arguments": {
      "action": "scenes"
    }
  },
  {
    "name": "forge_manage",
    "arguments": {
      "action": "scene_fill",
      "assetId": "11111111-1111-4111-8111-111111111111",
      "versionId": "22222222-2222-4222-8222-222222222222",
      "brief": {
        "headline": "Your message"
      }
    }
  },
  {
    "name": "forge_manage",
    "arguments": {
      "action": "scene_render",
      "confirmationToken": "token-returned-by-scene-fill"
    }
  }
]

At a glance

Sources

forge_query.sources

forge_manage.source_begin

forge_manage.source_status

forge_manage.source_figma

Template revisions

forge_query.templates

forge_query.template

forge_query.template_tree

forge_query.template_layers

forge_query.template_revision

forge_query.template_diff

forge_query.template_run

forge_manage.template_preview

forge_manage.template_save

forge_manage.template_forge

forge_manage.template_set_default

Render sets

forge_query.sets

forge_query.set

forge_query.set_revisions

forge_query.set_diff

forge_manage.set_create

forge_manage.set_update

forge_manage.set_fork

forge_manage.set_delete

forge_manage.suggest_rows

forge_manage.apply_suggestions

forge_manage.rows_patch

forge_manage.set_retarget

Rendering

forge_query.destinations

forge_query.jobs

forge_query.job

forge_query.batch

forge_manage.render_preview

forge_manage.render_confirm

Scenes

forge_query.scenes

forge_manage.scene_fill

forge_manage.scene_render

Recover from a refusal

Example call sequences

What’s next

Agent quickstart

Design systems

`forge_query.sources`

`forge_manage.source_begin`

`forge_manage.source_status`

`forge_manage.source_figma`

`forge_query.templates`

`forge_query.template`

`forge_query.template_tree`

`forge_query.template_layers`

`forge_query.template_revision`

`forge_query.template_diff`

`forge_query.template_run`

`forge_manage.template_preview`

`forge_manage.template_save`

`forge_manage.template_forge`

`forge_manage.template_set_default`

`forge_query.sets`

`forge_query.set`

`forge_query.set_revisions`

`forge_query.set_diff`

`forge_manage.set_create`

`forge_manage.set_update`

`forge_manage.set_fork`

`forge_manage.set_delete`

`forge_manage.suggest_rows`

`forge_manage.apply_suggestions`

`forge_manage.rows_patch`

`forge_manage.set_retarget`

`forge_query.destinations`

`forge_query.jobs`

`forge_query.job`

`forge_query.batch`

`forge_manage.render_preview`

`forge_manage.render_confirm`

`forge_query.scenes`

`forge_manage.scene_fill`

`forge_manage.scene_render`