Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@foundry-cli Create journal 'Raven's Lore' with category 'Settlements'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CLI and MCP server for managing Foundry VTT world content via Socket.io. Targets Foundry v14.
This tool manages the journal layer of a Foundry world: journal entries, their categories, and their pages. It also lists actors. It is intentionally narrow — no scene management, no compendium access, no system-specific mechanics.
The primary use case is AI-assisted world-building: an LLM writes lore entries via the MCP server while a GM reviews them in the Foundry UI in real time.
Related MCP server: World Anvil MCP Server
Requirements: Python 3.12+, uv, a running Foundry v14 instance with an active world.
git clone <repo>
cd foundry-cli
cp .env.example .env # fill in credentials.env keys:
Key | Description |
| Base URL of the Foundry instance, e.g. |
| HTTP Basic Auth username (if Foundry is behind a proxy) |
| HTTP Basic Auth password |
| The world name that must be active |
| Foundry user to authenticate as (must have GM role) |
| Password for that user |
uv run python foundry.py [COMMAND] --helpfoundry actor list [--json]foundry journal list [--json]
foundry journal upsert --title NAME [--folder FOLDER] [--public]
foundry journal delete --title NAMECategories are named tabs that group pages within a journal. Create them before assigning pages.
foundry journal category list --journal NAME [--json]
foundry journal category upsert --journal NAME --name NAME
foundry journal category delete --journal NAME --name NAMEfoundry journal page list --journal NAME [--json]
foundry journal page upsert --journal NAME --title NAME
[--category NAME] [--level 1-6]
[--before TITLE | --after TITLE]
[--public]
[--content HTML | --content-file PATH | stdin]
foundry journal page reorder --journal NAME # titles from stdin, one per line
foundry journal page delete --journal NAME --title NAMEContent input — exactly one of:
--content '<p>HTML</p>' — inline string
--content-file path/to/page.html — read from file
stdin — pipe HTML directly: cat page.html | foundry journal page upsert ...
Positioning — --before TITLE / --after TITLE insert the page relative to an existing page within the same category. All pages in the category are reindexed with clean sort values.
Level — controls sidebar indentation (1 = top-level, 2 = indented beneath the preceding level-1 page).
--public — sets OBSERVER ownership so players can see the entry/page. Default is INHERIT (follows the parent journal).
All upsert operations are idempotent — matched by name, safe to re-run.
# Create journal and categories
foundry journal upsert --title "Ravens — Lore"
foundry journal category upsert --journal "Ravens — Lore" --name "Settlements"
foundry journal category upsert --journal "Ravens — Lore" --name "NPCs"
# Add pages
echo "<p>A walled city on the northern coast.</p>" | \
foundry journal page upsert \
--journal "Ravens — Lore" --title "Thornwall" \
--category "Settlements" --level 1
echo "<p>The merchant district.</p>" | \
foundry journal page upsert \
--journal "Ravens — Lore" --title "Thornwall — Docks Quarter" \
--category "Settlements" --level 2 --after "Thornwall"
# Reorder pages
printf "Thornwall\nThornwall — Docks Quarter\nThornwall — Temple Quarter\n" | \
foundry journal page reorder --journal "Ravens — Lore"The MCP server exposes the same operations as tools so LLMs can manage journal content directly.
uv run python foundry_mcp.pyRegister in an MCP client config:
{
"mcpServers": {
"foundry": {
"command": "uv",
"args": ["run", "python", "/path/to/foundry_mcp.py"]
}
}
}Available tools: actor_list, journal_list, journal_upsert, journal_delete, category_list, category_upsert, category_delete, page_list, page_upsert, page_reorder, page_delete.
Tests run against a real Foundry instance spun up via Docker Compose. The test fixture starts the container, waits for the world to become active, then runs against it.
uv run pytestThe Docker environment lives in docker/. Tests create journals with a _pytest_ prefix and clean up on teardown.
foundryvtt-mcp is a JavaScript MCP server that runs inside Foundry as a module, calling the Foundry API directly from within the same process.
This project takes the opposite approach:
foundry-cli | foundryvtt-mcp | |
Runtime | External Python process | Foundry module (in-process JS) |
Protocol | Socket.io | Direct Foundry API calls |
Install footprint | Nothing installed in Foundry | Requires a Foundry module |
Interface | CLI + MCP server | MCP server only |
Scope | Journals and actors | Broader (scenes, actors, items, …) |
Why Socket.io instead of a Foundry module?
No Foundry module to maintain across Foundry version updates — the Socket.io wire protocol is stable.
Works with a remote or hosted Foundry instance without SSH or file system access.
The CLI is useful on its own for scripting and automation, independent of any AI tooling.
Trade-offs: The Socket.io modifyDocument API is not officially documented for external use, so it may break across major Foundry versions. Operations are limited to what that API surface exposes — complex queries or compendium access require a different approach.
List all actors in the active Foundry world.
Each actor includes _id, name, and type. Use Actor.<_id> as the UUID when linking to an actor sheet from journal content.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even without annotations, the description fully conveys the tool's behavior: it lists actors (read-only, no side effects). It adds context about the active world and the output structure, including a practical usage tip for linking.
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 two sentences, front-loading the core action and essential output details. Every sentence adds value without extraneous information.
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 parameterless tool with no output schema, the description provides sufficient information: what the tool does, what it returns, and how to use the output. It is complete for an agent to select and invoke 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?
There are no parameters, so the baseline is 4. The description adds no parameter information, which is appropriate given the empty input schema with 100% coverage.
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 'List all actors in the active Foundry world', specifying the verb (list), resource (actors), and scope (active world). It also details return fields and provides a usage hint for linking, distinguishing it from sibling tools that handle other entity types.
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 implicitly tells when to use this tool (when listing actors) and provides explicit guidance on using the output (Actor.<_id> as UUID for journal links). Since no sibling tool lists actors, alternatives are not needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a category from a journal by name. Returns False if not found.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| journal | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
States return behavior 'Returns False if not found', which adds transparency. No annotations provided; description does not mention side effects or error conditions beyond not found.
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?
Extremely concise single sentence that front-loads the action and resource. Every part is informative with no wasted words.
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?
Output schema exists (according to context) but not shown; description covers return value partially. Lacks information on success return value and prerequisites like journal existence.
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?
Parameter descriptions are missing from schema (0% coverage). Description adds only 'by name' and 'from a journal', providing minimal meaning beyond the schema.
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?
Clear verb 'Delete' and resource 'category from a journal' with identification method 'by name'. Distinguishes from sibling tools like category_upsert and category_list.
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?
No explicit guidance on when to use this tool or alternatives. No prerequisites stated (e.g., journal existence). Usage is implied but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all categories in a journal.
| Name | Required | Description | Default |
|---|---|---|---|
| journal | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation ('list'), but no annotations are provided. It does not disclose pagination, ordering, or potential side effects, which is acceptable for a simple listing tool.
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, concise sentence with no superfluous words. Every word contributes to stating the tool's purpose.
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 simple list operation with one parameter and no output schema, the description is adequate but could mention return format or typical use cases. The presence of sibling list tools suggests a need for more differentiation.
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 only parameter 'journal' lacks any description in the schema (0% coverage). The description adds minimal context by saying 'in a journal', but does not clarify if it expects an ID, name, or format.
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 verb 'List' and resource 'categories' scoped to 'a journal'. It distinguishes from sibling tools like category_delete and category_upsert, but does not differentiate from actor_list or page_list, which are also list tools.
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?
No guidance on when to use this tool versus alternatives (e.g., actor_list or page_list). No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a category within a journal. Idempotent.
Categories must exist before pages can reference them. Common names: NPCs, Settlements, Factions, Locations.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| journal | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It does disclose the key behavioral trait of idempotency. However, it does not mention permissions, rate limits, side effects, or whether the tool strictly creates or also updates. This leaves some uncertainty about its exact behavior.
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 concise at three sentences and front-loads the primary action. It avoids unnecessary verbosity but could be slightly more structured to prioritize key information.
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 has only two parameters and no output schema, the description covers the basic usage (idempotency, prerequisite for pages). However, it is missing details such as what the tool returns, whether it updates or only creates, and any constraints on input values.
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 description coverage is 0%, so the description should add meaning for the two parameters (name and journal). It only vaguely implies that journal is the parent entity and gives examples for name. It does not explain what each parameter specifically represents or any constraints, such as allowed formats or relationship to other resources.
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 states 'Create a category within a journal' which clearly defines the action and resource. It also notes idempotency, which aligns well with the 'upsert' semantics. However, it does not explicitly mention that it can also update an existing category, which is implied by the tool name but not stated.
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 provides context by stating that categories must exist before pages can reference them and lists common category names. However, it does not explicitly state when to use this tool versus alternatives (e.g., category_list or category_delete) nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a journal entry by title. Returns False if not found.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the return value for not found but lacks details on permissions, side effects, or idempotency. Adequate but not comprehensive.
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?
Two sentences with no wasted words. Information is front-loaded and efficient.
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 simple delete operation with one parameter and an output schema, the description is adequate but could elaborate on return value structure and error 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 0%, and the description only says 'by title', adding minimal meaning beyond the schema. It should explain allowable formats or constraints.
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 action (delete), the resource (journal entry), and the identifier (title). It distinguishes from siblings like journal_upsert and journal_list.
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 implies when to use (delete a journal by title) and notes the outcome if not found. However, it does not explicitly state when not to use or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all journal entries in the active Foundry world.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It implies a read-only operation by listing entries, but does not explicitly state that it is safe or disclose any behavioral traits like ordering or data freshness. The behavior is straightforward, but transparency is minimal.
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?
Single sentence, directly to the point, with no extraneous words. Highly concise and front-loaded.
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 simple list tool with no parameters and no output schema, the description is adequate. It covers the core purpose but could add context about the 'active Foundry world' scope or any implicit limitations (e.g., return all entries). Still, it is largely complete given the tool's simplicity.
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?
No parameters exist (0 params, 100% schema coverage), so the description rightly adds nothing about parameters. Baseline score of 4 is appropriate as no compensation is needed.
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 lists all journal entries in the active Foundry world. The verb 'list' and resource 'journal entries' are specific and distinguish it from sibling mutation tools like journal_delete and journal_upsert.
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?
No explicit guidance on when to use this tool versus other list tools (e.g., actor_list, page_list). Context implies it is the list tool for journals, but no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a journal entry by title. Idempotent.
public=True sets OBSERVER ownership so players can see the journal. folder is created automatically if it does not exist.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| folder | No | ||
| public | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions idempotency, public ownership, and auto-creation of folders, but fails to describe return values, error handling, or the update-creation distinction (e.g., what triggers an update vs. create).
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?
Three concise sentences with no redundant information. Each sentence adds value: core action, idempotency, and key parameter behaviors.
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 3 parameters, no annotations, and no output schema, the description is incomplete. It omits details about output, error conditions, idempotency guarantees, and the ownership model for non-public settings, leaving important context for the agent.
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 0%, so the description adds needed meaning: title used as identifier, public sets OBSERVER ownership, folder auto-created. However, it does not clarify folder path format or default behavior for non-public entries, leaving gaps.
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 'Create or update a journal entry by title' and mentions 'Idempotent', making the core action and method explicit. It distinguishes from sibling tools like journal_delete and journal_list by indicating it is an upsert operation.
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?
No explicit guidance on when to use this tool versus alternatives (e.g., journal_list+journal_delete+create). The idempotency hint is helpful for retry scenarios, but the description lacks context for choosing between upsert and other CRUD operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a page from a journal by title. Returns False if not found.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| journal | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description alone must disclose behavior. It states the tool is destructive and returns False if the page is not found, but fails to mention other important traits like idempotency, permissions, or side effects.
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 concise, consisting of one sentence that front-loads the primary action. The additional sentence about the return value is useful. However, it could include more beneficial details without being overly verbose.
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 two required parameters and an output schema, the description still feels incomplete. It lacks context on operation reversibility, required permissions, or any cascading effects. The output schema likely covers return values, but the description does not leverage that to reduce burden.
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 description adds the meaning that deletion is 'by title', clarifying that the title parameter identifies the page. However, with 0% schema description coverage, it does not describe the format of journal or title, leaving ambiguity.
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 that this tool deletes a page from a journal by title, distinguishing it from sibling delete tools for categories and journals. However, it does not explicitly contrast with other tools like page_upsert or page_list.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, such as verifying existence before deletion, or when to prefer other tools like page_upsert.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all pages in a journal.
Each page includes _category_name, title.level, and type fields.
| Name | Required | Description | Default |
|---|---|---|---|
| journal | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only, pagination, performance implications, or side effects.
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 concise with two short sentences, no fluff. However, it could be slightly more structured but is still efficient.
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 no output schema, no annotations, and a single parameter, the description lacks crucial information about return format, behavior, and usage constraints.
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 single parameter 'journal' has no description in the input schema (0% coverage) and the tool description does not explain its format, required status, or expected values.
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 it lists all pages in a journal and specifies included fields (_category_name, title.level, type). It is distinct from sibling tools like page_delete and page_reorder.
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?
No guidance on when to use this tool versus other list tools (e.g., actor_list, category_list). No context about prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set sort order for a list of pages. Returns the number of pages updated.
Assigns sort values 100000, 200000, ... to the listed pages in the given order. Pages not in the list are left untouched. Use this to establish ordering after bulk creation, or to fix sort conflicts.
| Name | Required | Description | Default |
|---|---|---|---|
| order | Yes | ||
| journal | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that pages not in the list are left untouched, assigns sort values in 100000 increments, and returns the number of pages updated. This provides essential behavioral context for a mutation tool.
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?
Three concise sentences: purpose and return, assignment details, usage guidance. No wasted words, well-structured with key information front-loaded.
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 simplicity (2 params, no annotations, has output schema), the description covers essential behavior: effect on listed and unlisted pages, sort value pattern, and return value. Minor omission: does not mention potential errors or idempotency, but adequate for the task.
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 0%, so description must compensate. It explains the 'order' parameter (list of page IDs in desired order) and implicitly what 'journal' is. However, it could be more explicit about the journal parameter. Adds value beyond bare schema.
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?
Clearly states the tool sets sort order for pages, with specific verb 'set' and resource 'sort order'. Distinguishes from sibling tools like page_list or page_upsert, which do not reorder. Explanation of assignment scheme adds clarity.
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?
Explicitly advises using this tool after bulk creation or to fix sort conflicts. While it does not list when not to use it, the sibling tools cover different operations, reducing ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a journal page. Idempotent.
content is HTML. level controls sidebar indentation (1=top, 2=indented under the preceding level-1 page). category must already exist — call category_upsert first. public=True sets OBSERVER ownership so players can see this page.
index: 0-based position within the category. When set, all pages in the category are reindexed with clean sort values so the page lands at that position. Omit to leave sort order unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | ||
| level | No | ||
| title | Yes | ||
| public | No | ||
| content | Yes | ||
| journal | Yes | ||
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses idempotency, side effect of reindexing when index is set, ownership change with public=True, and level semantics. Could better clarify how updates are identified (e.g., by title within journal/category), but overall transparent.
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?
Compact paragraph with no fluff. Each sentence conveys essential information. Front-loads purpose. Could use bullet points for readability but remains highly efficient.
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?
Covers most behavioral aspects: idempotency, preconditions, side effects, ownership, ordering. Without annotations or output schema, it still lacks return value specification and error handling. Slight gap in update identification mechanism, but overall adequate for a well-parameterized CRUD tool.
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 has 7 parameters with 0% description coverage. The description adds meaning for content (HTML), level (sidebar indentation with values), category (must pre-exist), public (ownership), and index (0-based, triggers reindex). However, it does not explain the journal parameter, which is required and not self-evident. Title is also unexplained but more intuitive.
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?
Clearly states it creates or updates a journal page and is idempotent. The verb-resource pair is specific and distinct from sibling tools like page_delete, page_list, and page_reorder, which handle different operations.
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?
Explicitly mentions prerequisite: category must already exist, with a call to use category_upsert first. Also provides guidance on when to set vs omit the index parameter. Lacks explicit negative guidance (when not to use) but context is clear.
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. Dates show when Glama detected each change.
v0.1.0actor_listcategory_deletecategory_listcategory_upsertjournal_deletejournal_listjournal_upsertpage_deletepage_listpage_reorderpage_upsertEach tool targets a unique resource-action pair (actors, categories, journals, pages) with no overlaps. Operations like list, delete, upsert, and reorder are clearly separated by resource type.
All tool names follow a consistent verb_noun pattern with lowercase underscores (e.g., actor_list, category_upsert, page_reorder). No mixing of styles.
11 tools cover the essential operations for journal management in Foundry VTT: listing, creating/updating, deleting, and reordering across three resource types plus a read-only actor list. The count is well-scoped.
The tool set provides full CRUD for journals, categories, and pages, plus reordering for pages. Actors are intentionally read-only for linking. No obvious gaps in the intended domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Official remote MCP server for Archivist AI TTRPG campaign memory: characters, sessions, and more.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
Remote MCP server for AIStoryHub: stories, chapters, story bible, Voiceprints, AI generation.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/allardhoeve/foundry-cli'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
