Code mode (preview): the AI writes a script against a typed foundry.* API and runs it in a sandbox.
Scored across 3 tools
docs, query, and execute have clearly distinct purposes: reference material, read-only script execution, and full read/write/delete script execution. The boundary between query and execute is explicitly stated, so an agent should never be uncertain which tool to call.
All tool names are single lowercase words, so the style is consistent and predictable. The minor deviation is that 'docs' is a noun while 'query' and 'execute' are verbs, but this does not create confusion given how well the descriptions map to the names.
Three tools is a minimal but complete surface for a code-mode MCP server: learn, read, and write. Each tool earns its place and there is no bloat or missing scaffolding.
The set covers the full script lifecycle: docs provides the API reference, query handles read-only exploration, and execute handles writes, deletes, and mixed workflows. The allowPartial flag and per-script limit reporting in execute also address operational edge cases, leaving no obvious dead ends.
Reference for the foundry.* API used in query and execute scripts. No arguments: the index — every domain with its methods; 🔒 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 indicate readOnly, idempotent, and non-destructive. The description adds behavioral detail: it returns an index, declarations, or a named type depending on arguments, and notes the 🔒 tier marker. It does not contradict annotations. Minor gap: it does not specify behavior if both domain and type are provided, which is a small transparency shortfall.
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 efficient and well-structured. It opens with the purpose, then quickly explains the three invocation modes, each in a concise clause. Every sentence adds value, and the tier marker note is front-loaded. No filler or redundancy.
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?
Given the tool's complexity (three modes) and lack of output schema, the description covers the key behaviors: what each mode returns, the tier marker, and the API's calling convention. It does not cover error cases or ambiguous input (both domain and type), but for a reference tool, it is nearly complete. The sibling context is also addressed by mentioning query and execute scripts.
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 baseline is 3. The description adds semantic meaning beyond the schema: it explains that domain yields TypeScript declarations and type yields a named type, and that no args yields the index. This clarifies how each parameter affects the response, going beyond the schema's basic string descriptions.
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 clearly states the tool is a reference for the foundry.* API, used in query and execute scripts. It specifies three distinct invocation modes (no args, domain, type) and what each returns, distinguishing it from the execution-focused sibling tools. The verb 'reference' and resource are explicit, and it is not a tautology.
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 says to 'Read the domain declarations before writing a script,' which implies using this tool before writing code with the API. It explains how to invoke it with domain or type, giving clear context on when to use it. It does not explicitly mention alternatives or exclusions, but the purpose inherently separates it from execute/query tools.
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.
Live React design-system APIs, patterns, and code validation so AI agents build real UI, not slop.
Run Python code in a secure sandbox without local setup. Declare inline dependencies and execute s…
Add one secure layer between your agents and this server.
