Code mode (preview): the AI writes a script against a typed foundry.* API and runs it in a sandbox.
Scored across 3 tools
The three tools occupy clearly separate roles: docs is a static reference lookup, query is read-only script execution, and execute allows writes. Descriptions explicitly cross-reference each other (docs for the API, query says 'use execute' for writes), leaving no realistic path to misselection.
All names are short, lowercase, single-token, and predictable, but 'docs' is a noun while 'query' and 'execute' are verbs, a minor stylistic deviation from a uniform verb pattern.
Three tools is exactly right for a code-mode server: one reference surface, one read path, one write path. Each tool has a distinct, non-redundant purpose and nothing feels padded or missing at the surface level.
Reference discovery, read execution, and write execution are all covered, including truncation and partial-failure signals in the trace. Minor gaps exist: no explicit rollback/transaction tool and no discovery of available worlds or connection state, though docs mitigates the former by instructing continuation from traces.
Reference for the foundry.* API used in query and execute scripts. No arguments: the index — every domain with its methods for this world's game system; 🔒 marks methods above your tier. With domain (e.g. "actors"): the TypeScript declarations of that domain with parameter and result types. With type (e.g. "ActorSummary"): one named type. Read the domain declarations before writing a script; every method takes one object argument and returns a Promise.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Named type from a domain declaration, e.g. "ActorSummary" | |
| domain | No | Domain name from the index, e.g. "actors", "tokens" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safe read-only, idempotent profile, so the description's job is to add context. It does: the 🔒 marker discloses that some methods sit above the caller's tier (an auth/entitlement constraint absent from annotations), and the closing sentence discloses that every method takes one object argument and returns a Promise — a real behavioral detail for script authors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the single purpose, then three crisp mode clauses, then an instruction. It is dense but every sentence earns its place, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has no output schema, so the description carries the burden of describing returns, and it does so for all three call modes. The one gap is what happens if both domain and type are supplied and whether type requires a domain; that edge case is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by explaining how each parameter selects an output mode, including what an empty call returns. It gives example values for both parameters and treats them as mutually exclusive modes, which the schema does not state.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: a reference lookup for the foundry.* API used in query/execute scripts. It clearly distinguishes itself from its siblings execute and query, which run scripts, while this one documents the API those scripts call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit usage guidance by call mode (no args = index, domain = typed declarations, type = one named type) and directs the agent to 'Read the domain declarations before writing a script,' which establishes the when-to-use context. It does not explicitly say when not to use it, but the routing is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a script against the connected Foundry world with the full foundry.* API — reads, writes and deletes. code is the body of an async function (see docs): call foundry..({ ... }), use await, console.log, and return what you want back (JSON, size-limited). Before it runs, a static check refuses the script if it calls a method your tier lacks, an unknown method, or accesses foundry dynamically — the answer lists each with its line. allowPartial: true runs it anyway and each locked call fails inside the script. Writes count against per-script budgets (the limits line of the docs index); the trace lists every call with the ids it touched. Nothing is rolled back when a script fails part-way: the trace shows what already happened — continue from it rather than re-running everything.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Body of an async function, e.g. `const a = await foundry.actors.create({ name: "Guard", type: "npc" }); return a.id;` | |
| debug | No | Keep the script and its report for the world owner's diagnostics (default false) | |
| allowPartial | No | Run even if the static check finds locked or computed calls; each locked call then fails at runtime (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool destructive, but the description goes further, disclosing that nothing is rolled back on partial failure, that writes count against per-script budgets, and that a trace lists all calls with touched IDs. It also explains the static check's refusal behavior and the allowPartial fallback. These traits—especially non-rollback and budget limits—are critical for an agent to anticipate side effects and are not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence delivers distinct, essential information: purpose, code format, static check, allowPartial, budgets, trace, and rollback semantics. It front-loads the primary purpose before diving into nuance, and the structure follows a natural logical flow from what it does to how it behaves. No filler is present; the length is proportionate to the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool without an output schema and with three parameters, the description covers all necessary aspects: the execution environment, the required code format, the safety checks, error handling with allowPartial, resource limits, and the non-rollback behavior. It even points to the docs for budget limits. There are no obvious gaps an agent needs to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% parameter descriptions, including an example for `code`. The tool description adds substantial value by specifying that `code` is an async function body using the foundry.* API, requiring await and console.log for debugging, and that the return is size-limited JSON. It also clarifies `allowPartial` behavior beyond the schema's one-line description. Because the schema already covers the basics, a 3 is the baseline; the extra detail on code format and partial execution justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb-resource pair—'Run a script against the connected Foundry world'—and explicitly notes it covers reads, writes, and deletes. This distinguishes it from the sibling `query` tool, which presumably handles read-only access, and from `docs`. The specificity leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the mechanics of static checks and allowPartial, giving context on when to use them, but it never explicitly tells the agent when to prefer `query` for read-only operations. Given that `execute` counts writes against budgets, guidance to route simple reads to `query` would be valuable. Without that, the tool is presented as the go-to for any script, which may lead to overuse for read-only tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a read-only script against the connected Foundry world. code is the body of an async function: call foundry..({ ... }) (see docs), use await, console.log, and return the value you want back (JSON, size-limited). Only read methods are bound; writes are not available here — use execute. Every call counts against the per-script limits shown in the docs index (calls, wall time, CPU time, result size); an oversized call result arrives as { __truncated: true, bytes, limit, preview }.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Body of an async function: `const actors = await foundry.actors.list({}); return actors.length;` |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial value beyond these: it discloses per-script limits (calls, wall time, CPU time, result size), the truncation behavior with the exact shape { __truncated: true, bytes, limit, preview }, and the requirement to write an async function with await. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph, but every sentence earns its place. It front-loads the core purpose, then explains the code parameter, then the read-only restriction, then limits and truncation. It is slightly longer than necessary but remains efficient and well-ordered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only query tool, the description covers everything an agent needs: the async function format, the read-only scope, the alternative for writes, the limits, and the truncation behavior. It also references the docs for the API details. Even without an output schema, the agent can predict the return shape and error/truncation cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema's `code` property includes a concrete example. The description goes further by explaining the async function contract: 'call foundry.<domain>.<method>({ ... }), use await, console.log, and return the value you want back (JSON, size-limited).' This adds meaning about return values and syntax beyond the schema, so a 4 is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Run a read-only script against the connected Foundry world.' It immediately distinguishes itself from the sibling execute by stating only read methods are bound and writes require execute. The agent can tell exactly what this tool does and how it differs from its siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use context: it is for read-only queries. It explicitly states 'writes are not available here — use execute,' naming the alternative and the condition that selects it. It also points to docs for the API and mentions the per-script limits, so the agent knows what to expect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
docsexecutequeryBuild Apps and run code in 30 languages — sandboxed, with persistent sessions for agent loops.
Connect any AI to your Foundry VTT world: actors, combat, dice, journals, tokens, compendiums.
Governed app access for AI agents: 1,000+ apps & 12,000+ tools via Code Mode MCP.
Ephemeral single-task tool forged from examples, sandbox-proven, task-bound, expiring by design.
Add one secure layer between your agents and this server.
