fvtt-mcp-molten5e

Overview Schema Source Related Servers Discussions Admin

update-scene

Modify an existing Foundry VTT scene's settings: rename, swap background, adjust grid, dimensions, token vision, fog, lighting, weather, navigation, and linked resources.

Instructions

Update an existing Scene document — rename, swap its background image (Data-relative path), toggle navigation, set the navigation label, change dimensions/grid (size/type/distance/units)/padding, token vision, fog mode, lighting (darkness, global light), weather, a nav thumbnail, or the linked playlist/journal ("" clears a link). Also (parity with create-scene) deep-merges a full environment{}/fog{} mood object, re-points the saved camera (initial{x,y,scale}), or re-stamps document flags on an existing scene. Scene-document only: never touches placeables (walls/lights/tokens) and never activates the scene. GM-only.

Input Schema

TableJSON Schema

Name	Required	Description
`fog`	No	A v12+ scene's full fog{} object (exploration, overlay, colors), carried whole (deep-merged).
`name`	No	New scene name.
`flags`	No	Document flags namespaced by scope — e.g. {"tom-cartos-import":{sourceModule,sourceId}} for import provenance/dedup. Deep-merged over any existing flags (re-stampable on update).
`thumb`	No	Data-relative path to a pre-rendered navigation thumbnail (e.g. an uploaded <id>-thumb.webp shipped by a map pack). Foundry may regenerate it on a later in-app edit, so treat it as a nice-to-have, not load-bearing.
`width`	No	Scene width in pixels.
`height`	No	Scene height in pixels.
`fogMode`	No	Fog of war: disabled \| individual (classic per-player) \| shared (party-wide).
`initial`	No	The saved initial camera view {x,y,scale} to restore on scene load (deep-merged).
`journal`	No	JournalEntry id or exact name to attach as scene notes. "" clears it.
`navName`	No	Navigation label shown in the scene nav bar.
`padding`	No	Scene padding fraction (0–0.5).
`weather`	No	Weather effect key (e.g. rain, snow, fog, leaves, rainStorm, blizzard). "" = none.
`darkness`	No	Darkness/day-night level: 0 = full daylight, 1 = full night.
`gridSize`	No	Grid size in pixels.
`gridType`	No	Foundry grid type (0 gridless, 1 square, 2+ hex).
`playlist`	No	Playlist id or exact name to auto-play on scene activation. "" clears it.
`gridAlpha`	No	Grid line opacity 0–1 (e.g. 0.2 for a faint grid).
`gridColor`	No	Grid line color as a hex string, e.g. "#000000".
`gridUnits`	No	Distance unit label per cell, e.g. "ft" (dnd5e default).
`navigation`	No	Whether the scene appears in the navigation bar.
`environment`	No	A v12+ scene's full environment{} mood object, carried whole (darknessLevel, globalLight{...}, cycle, base, dark{hue,luminosity}…). Deep-merged, so a partial mood patch layers onto the scene; prefer this over the flat darkness/globalLight knobs when importing or re-mooding a pack scene.
`globalLight`	No	Globally illuminate the whole scene (turn the lights on).
`tokenVision`	No	Require token line-of-sight to see the scene. Turn OFF for overland/illustration maps.
`gridDistance`	No	Real-world distance per grid cell (dnd5e default 5).
`backgroundPath`	No	Data-relative path to a new background/map image.
`sceneIdentifier`	Yes	Scene id or exact name.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.1.3Sep 16, 2026
- removedInput schema / properties / fog / properties / overlay / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedInput schema / properties / fog / properties / overlay / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed4 schema fields changedv1.3.0Jul 5, 2026

addedInput schema / properties / environment

Added value: +{
+  "additionalProperties": {},
+  "description": "A v12+ scene's full environment{} mood object, carried whole (darknessLevel, globalLight{...}, cycle, base, dark{hue,luminosity}…). Deep-merged, so a partial mood patch layers onto the scene; prefer this over the flat darkness/globalLight knobs when importing or re-mooding a pack scene.",
+  "properties": {
+    "cycle": {
+      "type": "boolean"
+    },
+    "darknessLevel": {
+      "maximum": 1,
+      "minimum": 0,
+      "type": "number"
+    },
+    "globalLight": {
+      "additionalProperties": {},
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

addedInput schema / properties / flags

Added value: +{
+  "additionalProperties": {},
+  "description": "Document flags namespaced by scope — e.g. {\"tom-cartos-import\":{sourceModule,sourceId}} for import provenance/dedup. Deep-merged over any existing flags (re-stampable on update).",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

addedInput schema / properties / fog

Added value: +{
+  "additionalProperties": {},
+  "description": "A v12+ scene's full fog{} object (exploration, overlay, colors), carried whole (deep-merged).",
+  "properties": {
+    "exploration": {
+      "type": "boolean"
+    },
+    "overlay": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "type": "object"
+}

addedInput schema / properties / initial

Added value: +{
+  "additionalProperties": {},
+  "description": "The saved initial camera view {x,y,scale} to restore on scene load (deep-merged).",
+  "properties": {
+    "scale": {
+      "type": "number"
+    },
+    "x": {
+      "type": "number"
+    },
+    "y": {
+      "type": "number"
+    }
+  },
+  "type": "object"
+}

First observedv1.2.2Jun 30, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral disclosure burden. It details deep-merge behavior for environment/fog, re-pointing of initial, re-stamping flags, empty-string clearing for playlist/journal links, the GM-only permission, and the explicit non-effects on placeables and activation. This goes well beyond what the schema or annotations alone would convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every clause maps to a real parameter set or boundary condition, and the opening phrase 'Update an existing Scene document' is front-loaded. For a 26-parameter tool, it is appropriately sized and avoids restating schema-level details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and high tool complexity, the description covers the full call surface: all updateable field groups, deep-merge semantics, target identity, GM-only permission, and explicit non-effects. The only minor omission is return value details, but with no output schema and this level of behavioral coverage, the agent has enough to invoke the tool correctly and understand the outcome.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 26 parameters already have schema descriptions, so the baseline is 3. The description adds meaningful cross-parameter semantics by grouping fields into functional categories and by clarifying that environment/fog/initial/flags are deep-merged or re-stamped with parity to create-scene, rather than flat overwrites. It does not add syntax details per parameter, but the schema already covers those.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description leads with a specific verb and resource: 'Update an existing Scene document' and enumerates the exact field categories it can change, from name and background to environment/initial/flags. It also draws a clear boundary with 'Scene-document only: never touches placeables (walls/lights/tokens) and never activates the scene,' which distinguishes it from create-scene, activate-scene, and placeable-specific update tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes when/when-not explicit: it targets an existing document, is marked 'GM-only', and explicitly says it never activates the scene and never touches placeables, signaling that activation or wall/light/token edits belong elsewhere. 'Parity with create-scene' also gives an alternative anchor for the same environment/fog/initial/flags semantics.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

update-scene

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools