Skip to main content
Glama

Foundry MCP

by com.foundry-mcp
OverviewDiscussionsAdmin

token-create

Place a token on the scene for an actor. Coordinates are pixels (top-left corner of the grid cell): pixel = gridCoord * gridSize; scene-get gives gridSize, actor-list or actor-filter the actorId.

Input Schema

NameRequiredDescriptionDefault
xYesX in pixels
yYesY in pixels
scaleNoToken scale multiplier (default 1)
hiddenNoHide token from players
actorIdYesActor ID (from actor-list or actor-filter)
sceneIdNoScene ID; default the active scene
rotationNoRotation in degrees (0-360)
actorLinkNotrue = shares the actor, false = independent copy (module 8.14+)
elevationNoElevation in game units

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / properties / actorId / description
      Previous value: -"Actor ID to create token for (use actor-list to find)"New value: +"Actor ID (from actor-list or actor-filter)"
    • changedInput schema / properties / elevation / description
      Previous value: -"Elevation in game units (for flying, multi-level)"New value: +"Elevation in game units"
    • changedInput schema / properties / sceneId / description
      Previous value: -"Scene ID (uses active scene if omitted)"New value: +"Scene ID; default the active scene"
    • changedInput schema / properties / x / description
      Previous value: -"X position in pixels"New value: +"X in pixels"
    • changedInput schema / properties / y / description
      Previous value: -"Y position in pixels"New value: +"Y in pixels"
  2. Changed1 schema field changed
    • addedInput schema / properties / actorLink
      Added value: +{
+  "description": "true = shares the actor, false = independent copy (module 8.14+)",
+  "type": "boolean"
+}
  3. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare non-readOnly, non-destructive, non-idempotent behavior, so the bar is lower. The description adds genuinely new behavioral context: the coordinate system is pixel-based measured from the grid cell's top-left corner, and it depends on prior scene/actor lookups. It doesn't say what happens on duplicate placement or whether GM permission is required.

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?

Two compact clauses, front-loaded with the action, followed by the coordinate math and ID sources. Every sentence carries information needed to call the tool correctly; no filler.

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

Completeness4/5

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

Covers the two nontrivial aspects of a 9-parameter mutation tool (coordinate space, prerequisite lookups) and the remaining optional fields are fully documented in the schema. With no output schema, it could still say whether the created token's ID is returned, which matters for chaining into token-update or token-move.

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 baseline is 3, but the description earns a bump by explaining the pixel coordinate system and anchor point beyond the schema's bare 'X in pixels'. It also explains where the required actorId comes from, rather than just restating the field description.

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

Purpose4/5

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

States a specific verb and resource ('Place a token on the scene for an actor'), which is clearly distinct from token-move and token-update. It never explicitly names those siblings as alternatives, but the creation semantics are unambiguous.

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

Usage Guidelines4/5

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

Provides concrete workflow guidance: coordinates are in pixels, the conversion formula is given, and it points to scene-get for gridSize and actor-list/actor-filter for actorId. It doesn't state when not to use this tool or how it differs from token-update, but the prerequisites are explicit.

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

All Foundry MCP toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources