Skip to main content
Glama
Txpple

fvtt-mcp-molten5e

by Txpple
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

update-token

Edit placed tokens on a scene—set rotation, scale, image, elevation, hidden, nameplate, bars, and per-token HP. Resolve by scene, token IDs, or actor names; batch updates with auto-unlock and image verification.

Instructions

Edit one or more PLACED tokens on a scene — a token INSTANCE already dropped on the map, NOT the actor's prototype token (that's update-actor). Resolve the scene by id/exact name (default: the ACTIVE scene), then target tokens by tokenIds and/or actorIds (an actor id OR exact name — updates EVERY placed copy of that actor, e.g. all "Dead Guard" corpses). Patch any of: rotation (or randomizeRotation for an independent per-token angle), scale (token art size — sets texture.scaleX/scaleY together), imagePath (RESKIN the placed instance — new token art, still image or animated video, existence-checked so a 404 never breaks working art; no more delete+re-place), elevation, hidden, lockRotation, x/y, name, displayName (nameplate visibility), displayBars (resource-bar visibility), bar1/bar2 (which resource each bar tracks — the health bar is bar1 = attributes.hp), ring (dynamic token ring on/off), and hp (this token's CURRENT hit points, per-token on its own delta — so two copies of one actor can be wounded differently, which update-actor cannot do) — all matched tokens update in one batch. GOTCHA handled for you: a token whose actor had auto-rotate OFF carries lockRotation:true, which HIDES a set rotation — so when you rotate a locked token the tool auto-unlocks it and warns. Reports matched/updated counts + any unresolved ids. GM-only.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
xNoNew token X in absolute canvas pixels.
yNoNew token Y in absolute canvas pixels.
hpNoSet THIS placed token's hit points on its own actor — PER-TOKEN, so two copies of the same actor can differ (e.g. a band wounded to different HP). Writes system.attributes.hp.* on the token's (unlinked) delta, NOT the prototype/statblock — the right home for a token's current HP. For a linked token it writes the shared base actor. Only the sub-fields you pass change; 0 is valid (a downed creature).
bar1NoBar 1 resource attribute path (health bar is "attributes.hp"); "" clears it.
bar2NoBar 2 resource attribute path (e.g. "attributes.hp"); "" clears it.
nameNoRename the placed token (its nameplate).
ringNoDynamic token ring: false = plain token (the house default), true = ring on. Sets ring.enabled on the placed token.
scaleNoToken ART scale (sets texture.scaleX and scaleY together). 1 = normal, 1.5 = 50% larger.
hiddenNoHide (true) or reveal (false) the token from players.
actorIdsNoActor id OR exact actor name — updates ALL placed copies of each (e.g. every "Dead Guard" token on the map). Combined (union) with tokenIds.
rotationNoFacing in degrees (0–359), applied to every matched token.
tokenIdsNoPlaced-token ids to update (from list-tokens). Combined (union) with actorIds.
elevationNoToken elevation in grid-distance units (e.g. feet).
imagePathNoRESKIN the placed token(s): new token art (texture.src) — a world-relative path (e.g. "assets/tokens/morgash.png") or URL; a still IMAGE or an animated VIDEO (.webm/.mp4) both work on a token. Applied to every matched token; the path is existence-checked first, and a 404 leaves the current art unchanged (with a warning) instead of breaking it. Changes ONLY the placed instance(s) — the actor's portrait/prototype art is set-actor-art.
displayBarsNoResource (health) bar visibility, same modes as displayName: none | control | owner-hover | hover | owner | always.
displayNameNoNameplate visibility: none | control (only when selected) | owner-hover | hover | owner (always, to owners) | always (always, to everyone).
lockRotationNoLock the token art from rotating. NOTE: lockRotation:true HIDES any `rotation` you set, so when you rotate a locked token and omit this, the tool AUTO-UNLOCKS it (and warns) so the angle is visible.
sceneIdentifierNoScene id or exact name holding the token(s). Omit to use the ACTIVE scene.
randomizeRotationNoGive each matched token its OWN random angle (0–359) instead of one shared `rotation` — e.g. to strew corpses naturally. Overrides `rotation` when true.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.1.3
    • addedInput schema / properties / imagePath
      Added value: +{
+  "description": "RESKIN the placed token(s): new token art (texture.src) — a world-relative path (e.g. \"assets/tokens/morgash.png\") or URL; a still IMAGE or an animated VIDEO (.webm/.mp4) both work on a token. Applied to every matched token; the path is existence-checked first, and a 404 leaves the current art unchanged (with a warning) instead of breaking it. Changes ONLY the placed instance(s) — the actor's portrait/prototype art is set-actor-art.",
+  "minLength": 1,
+  "type": "string"
+}
  2. Addedv1.3.0

TDQS

A4.8/5.0
Behavior5/5

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

No annotations are present, so the description carries the full disclosure burden and meets it. It discloses the auto-unlock gotcha for lockRotation, the existence-check on imagePath (404 leaves art unchanged), per-token hp deltas, batch behavior, and the returned report of matched/updated counts and unresolved ids. It even states GM-only.

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

Conciseness4/5

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

The description is dense but every clause contributes: core scope, non-goals, parameter semantics, gotcha, and reporting. The single-paragraph structure makes it harder to scan than a bulleted list, but it is front-loaded and contains no filler.

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?

For a 19-parameter tool with no annotations and no output schema, the description covers all non-obvious behavior: scene resolution, targeting strategies, batch update, per-token HP, reskin semantics, and the lockRotation gotcha. The schema already documents every parameter exhaustively, so the description only needs to add interactions and context, which it does.

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?

Schema coverage is 100%, so the baseline is 3; the description pushes above it by explaining cross-parameter interactions: randomizeRotation overrides rotation, scale sets texture.scaleX/scaleY together, lockRotation:true hides rotation and triggers auto-unlock, and hp is written per-token. It also clarifies bar1/bar2 semantics with the health-bar example.

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?

Opens with 'Edit one or more PLACED tokens on a scene', naming the verb, resource, and scope. Immediately contrasts with 'NOT the actor's prototype token (that's update-actor)', distinguishing it from a key sibling. The list of patchable fields makes the tool's purpose unmistakable.

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?

Explicitly names update-actor as the alternative for prototype tokens and set-actor-art for changing actor art, and states the condition for using this tool ('PLACED tokens'). Explains when to use actorIds vs tokenIds (every placed copy vs specific instances) and that randomizeRotation overrides rotation. This is strong routing guidance.

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

Deploy Server

Other Tools