foundry-rest-api-mcp-server

Modify Foundry Actor

foundry_modify_actor

Modify Foundry VTT actors by giving or removing items, adjusting numeric attributes, or killing them (setting HP to zero).

Instructions

Give/remove items, increase/decrease numeric attributes, or kill (set HP to 0) an actor. Use action to select the operation.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "foundry_modify_actor"
  }
}

Input Schema

Name	Required	Description
`uuid`	No	[increase/decrease/kill] UUID of the target actor
`action`	Yes	Operation: give/remove items, increase/decrease a stat, or kill
`amount`	No	[increase/decrease] Amount to change
`toUuid`	No	[give] UUID of the actor receiving the item
`userId`	No	Override the default userId. Omit for GM-level access.
`clientId`	No	Override the default clientId (which connected world to target)
`fromUuid`	No	[give] UUID of the actor to transfer the item from
`itemName`	No	[give/remove] Name of the item (if UUID unknown)
`itemUuid`	No	[give/remove] UUID of the item
`quantity`	No	[give/remove] Quantity
`selected`	No	[increase/decrease/kill/remove] Use current selection
`actorUuid`	No	[remove] UUID of the actor to remove the item from
`attribute`	No	[increase/decrease] Dotted attribute path, e.g. system.attributes.hp.value

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Aug 6, 2026

TDQS

A3.6/5.0

Behavior3/5

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

The description adds one meaningful behavioral detail: 'kill (set HP to 0)' clarifies the exact effect of the kill action. However, it does not disclose other behavioral traits like whether give/remove permanently alter inventories, whether changes are reversible, or whether permissions beyond openWorldHint are required. Since annotations only include openWorldHint, the description carries a moderate transparency burden and meets it only partially.

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 two sentences, immediately lists the core operations, and avoids redundant filler. It is front-loaded with the most critical info and earns its place without unnecessary detail.

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

Completeness2/5

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

Despite the schema covering parameters, the tool is complex with 13 parameters and no output schema. The description does not explain return values, error conditions, or how the action determines required parameters beyond a one-liner. It also omits preconditions like whether the actor must exist or be in the world. For a tool that can kill or remove items, this level of incompleteness is a notable gap.

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

Parameters3/5

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

The input schema already provides 100% coverage for parameter descriptions, so the description adds little semantic value. It does reinforce that 'action' selects the operation, but the schema already enumerates the actions with descriptions. The mapping between action and parameter groups is handled by bracket prefixes in the schema, not the description, so the description does not significantly enhance parameter understanding.

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 clearly identifies the tool as modifying Foundry actors, listing specific operations (give/remove items, increase/decrease attributes, kill/set HP to 0). This distinguishes it from sibling tools like foundry_delete_entity or foundry_update_entity by focusing on actor mutations rather than entity lifecycle management.

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

Usage Guidelines3/5

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

The phrase 'Use action to select the operation' provides some guidance on how to invoke the tool, but it does not explicitly state when to use this tool versus alternatives such as foundry_update_entity or foundry_create_creature. There is no mention of exclusions or fallback conditions, so the usage context is implied rather than clearly delineated.

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

Deploy Server