Foundry REST API MCP

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.5.0
Disambiguation5/5
Each tool targets a distinct resource and action, following a clear verb_noun pattern. Even with 53 tools, descriptions are specific enough to avoid confusion between similar-sounding operations like get_folder vs get_structure or get_entity vs search.
Naming Consistency4/5
All tools share the 'foundry_' prefix and use a consistent verb_noun structure. Minor inconsistencies exist, such as create_canvas_documents (plural) versus update_canvas_document (singular) and send_chat_as_user versus send_chat_message, but these do not undermine overall predictability.
Tool Count2/5
With 53 tools, the server is well beyond the typical well-scoped range of 3-15. While the Foundry domain is broad, the excessive number of tools could overwhelm agents and makes navigation harder. Some tools, like the multiple encounter turn/round controls, could be consolidated.
Completeness3/5
The tool set covers many core Foundry operations, including entities, scenes, tokens, encounters, effects, rolls, and chat. However, there are notable gaps: users can be listed and created but not updated or deleted, encounters can be started/ended but not created or deleted, and folders have no update operation. These missing lifecycle operations limit full workflow coverage.
Average 3.2/5 across 53 of 53 tools scored. Lowest: 1.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 9 commits in the last 12 weeks
- Last stable release on August 1, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides no behavioral details beyond the action 'start'. The annotation readOnlyHint=false indicates it is a mutation, but the description does not disclose side effects, state changes, permissions, or what happens to an already active encounter. No contradiction exists, but no additional transparency is offered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than effective conciseness. It conveys no useful information beyond the tool's name and does not earn its place as a meaningful description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a complex parameter surface (8 params), no output schema, and no additional context. The one-sentence description is wholly inadequate for an agent to select and invoke this tool correctly, especially given the many sibling encounter-related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 8 parameters and only 25% schema description coverage (userId and clientId), the description must compensate but offers zero information about parameters like name, tokens, rollAll, rollNPC, startWithPlayers, or startWithSelected. The agent cannot infer their meanings from the tool description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Start an encounter.' is nearly a direct restatement of the tool name 'foundry_start_encounter'. It does not clarify what 'start' means in the Foundry context, how it relates to existing encounters, or how it differs from sibling tools like foundry_end_encounter or foundry_next_turn.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool vs. alternatives. It does not mention prerequisites, such as creating or loading an encounter first, whether tokens should be added before starting, or any relationship with companion tools like foundry_list_encounters or foundry_add_to_encounter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=false in annotations, the description carries the burden of explaining behavior, but it merely says 'create', which does not clarify whether the message is sent immediately, requires permissions, or affects the game log. No additional behavioral context is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, but it is under-specified rather than concise. A single vague sentence fails to provide necessary detail, making it not appropriately sized for a tool with 8 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, no output schema, mutation behavior), the description is completely inadequate. It does not mention return values, side effects, or any operational context needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only userId and clientId have descriptions), and the tool description adds no explanation for parameters such as content, speaker, whisper, or chatType. The description does not compensate for the low schema coverage at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a chat message' names a verb and a resource but uses 'create' instead of 'send', which is vague and does not distinguish from the sibling tool foundry_send_chat_as_user. It lacks specifics about the chat context or how this differs from other chat-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like foundry_send_chat_as_user or foundry_list_chat_messages. There are no usage scenarios, constraints, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The only annotation is readOnlyHint=false, indicating a write operation. The description does not provide any additional behavioral details such as permissions required, potential for name conflicts, or whether it affects existing folders. It adds no value beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no filler, but it is under-specified to the point of near-tautology. It is concise but not informative, so a middle score is appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a 5-parameter tool, no output schema, and minimal annotations, the description is far from complete. It does not explain the purpose of folderType, how parentFolderId is used, or what happens on success or failure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description makes no mention of the five parameters. The schema has descriptions for only two parameters (userId and clientId), leaving name, folderType, and parentFolderId undocumented. The description does not compensate for this low coverage.
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?
The description clearly states the verb 'Create' and the resource 'Foundry folder', which distinguishes it from sibling read/delete folder tools. However, it lacks any detail about folder types or hierarchy, so it is clear but not fully specified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites like parentFolderId or folderType values. The description only gives a basic statement with no context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false. The description does not disclose side effects, such as whether selection is overwritten, whether it affects server state, or any permission requirements. No behavioral context beyond the annotation is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise in length, but it is under-specified for a tool with 7 parameters. It fails to earn its place as a useful guide.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, nested object, no output schema) and the availability of sibling tools, the description is severely incomplete. There is no explanation of return values, selection semantics, or parameter behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no information about the parameters. The schema has 7 optional properties with low coverage (43%), and the 'data' field is described only as 'JSON object accepted by Foundry,' which is unhelpful. The description does not explain how uuids, name, all, or overwrite work.
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?
The description states 'Select tokens in the Foundry client', giving a specific verb and resource. However, 'select' is ambiguous (set vs. retrieve) and no differentiation is made from sibling foundry_get_selected_tokens, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool, no mention of alternatives (e.g., get_selected_tokens), and no exclusions. It simply states what it does without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint: false already indicates a write operation, but the description adds no further behavioral context. It does not mention side effects, required permissions, or whether existing data is overwritten. No contradiction with annotations exists, but the description falls short of disclosing important traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, but it sacrifices clarity for brevity. The phrasing 'by ID, name, or active status' is confusing and omits critical details, making it under-specified rather than appropriately concise.
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?
With 6 parameters, a required nested object, no output schema, and minimal annotations, the description is insufficient. It does not explain how the tool behaves, what the response looks like, or how to structure the data parameter, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (data, userId, clientId have descriptions; name, active, sceneId do not). The description hints that name and active are relevant, but it fails to explain the required 'data' parameter and the role of sceneId. The ambiguous 'by ID, name, or active status' offers minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the core action 'Update a scene', which identifies the tool as a mutation operation on scenes, distinguishing it from siblings like create or delete. However, the phrase 'by ID, name, or active status' is ambiguous—it could mean selection criteria or fields to update—leaving the exact purpose unclear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as foundry_create_scene, foundry_switch_scene, or foundry_delete_scene. The description neither states prerequisites nor mentions any exclusions or fallback tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=false already indicates a mutation, and the description merely restates 'create' without adding extra behavioral details such as overwrite behavior, permission requirements, or effects on existing entities. It does not contradict annotations, but it also does not enrich them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is efficient, but its extreme brevity borders on under-specification, so it does not quite earn a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no output schema, and sparse annotations, a one-sentence description is grossly insufficient. It fails to explain the data format, valid entity types, folder/keepId/override semantics, or return behavior, leaving critical gaps for an agent to safely invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 43% (3 of 7 parameters), and the description provides no parameter information at all. Parameters like folder, keepId, override, and entityType are left unexplained both in the schema and description, so the description fails to compensate for the low schema coverage.
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?
The description clearly states the action (create) and resource (Foundry world entity), which is distinct from generic management tools. However, it does not differentiate among sibling create tools like foundry_create_scene or foundry_create_actor_embedded_documents, leaving ambiguity about what entity types are supported.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The description is a single generic statement with no situational context, prerequisites, or exclusions, making it hard for an agent to decide between this and other create tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral detail beyond the readOnlyHint annotation. It does not disclose what data is returned, what the 'all' or 'active' flags do, or any side effects. The agent must rely on the schema alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence and contains no wasted words. However, the brevity results in under-specification rather than effective conciseness, as it omits essential details about tool usage.
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?
With no output schema and 7 optional parameters, the description is inadequate. It fails to explain what a scene is, how filtering works, or what the return structure looks like, making the tool incomplete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29%, meaning most parameters lack descriptions. The tool description does not compensate by explaining how 'name', 'sceneId', 'viewed', or other parameters affect the query. It provides zero additional parameter clarity.
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?
The description clearly uses the verb 'Get' with the resource 'scenes', indicating a retrieval operation. However, it lacks differentiation from sibling tools like foundry_get_entity or foundry_get_canvas_documents, and does not define the scope of 'scenes'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, recommended scenarios, or exclusions, leaving the agent without context for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only restates the removal action without explaining consequences (e.g., whether tokens are deleted or just removed from the encounter), permission requirements, or the meaning of 'selected' vs 'named'. The readOnlyHint: false annotation already signals mutation, but the description adds no additional behavioral context and even introduces ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, easily readable sentence and is appropriately front-loaded with the primary action. However, it is too terse to be considered well-structured for a tool with 5 parameters, as it lacks necessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with 5 optional parameters, no output schema, and no required fields, the description is severely incomplete. It does not explain how to select an encounter, whether 'selected' refers to canvas selection, what 'uuids' represent (token IDs? actor IDs?), or what the result of the removal is. The agent cannot reliably invoke this tool correctly based solely on the provided information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 40% schema description coverage (userId and clientId), the description fails to compensate. The phrase 'selected or named tokens' hints at the 'selected' and 'uuids' parameters, but it does not clarify their semantics, mutual exclusivity, or how the 'encounter' parameter should be specified. This leaves significant gaps in parameter understanding.
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?
The description clearly identifies the action 'remove' and the resource 'tokens from an encounter', distinguishing it from sibling tools like foundry_add_to_encounter and foundry_remove_effect. However, 'selected or named tokens' is ambiguous because there is no 'name' parameter; the uuids array is the likely identifier but not explicitly tied to 'named'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as removing effects or ending an encounter. There are no mention of prerequisites, conditions, or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, but the description adds no behavioral context. It does not mention potential side effects like creating a chat message (createChatMessage parameter), whether the roll is asynchronous, or how results are returned. The description is minimal and does not disclose what happens when a roll is executed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, which aids front-loading, but it is under-specification rather than conciseness. A single sentence provides no structure or additional detail. For a tool with 7 parameters and no output schema, the description should be longer to be useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, no output schema, annotations minimal), the description is completely inadequate. It does not explain return values, side effects, or how to use the tool in context. Without this information, an agent cannot reliably invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29% (only userId and clientId have descriptions). The description does not explain the syntax of 'formula' (e.g., '2d6+1'), nor does it clarify the meaning of flavor, whisper, speaker, createChatMessage, or clientId. With such low coverage, the description fails to compensate, leaving the agent to guess parameter semantics.
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 states the action ('Roll') and the resource ('a dice formula'), which is specific and unambiguous. No sibling tool includes 'roll', so it is distinguished from read-only operations like foundry_get_last_roll and foundry_list_rolls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, relationship to get_last_roll/list_rolls, or when not to use it. The intended usage is only implied by the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=false is consistent with 'update', but the description adds no behavioral detail beyond that. It does not clarify whether the update is a partial patch or full replacement, what happens on failure, or any permission requirements, leaving significant ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy, but it is so minimal that it becomes under-specification rather than conciseness. It essentially restates the tool name without providing operational value, so it fails to earn its place.
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?
For a mutation tool with six parameters, nested objects, and no output schema, this description is severely incomplete. It lacks update semantics, data format guidance, error behavior, and any relationship to sibling tools, forcing the agent to guess or infer critical details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter semantics whatsoever. The critical 'data' parameter is only described in the schema as 'JSON object accepted by Foundry', which is vague, and the description does not explain how documentType, documentId, and data interact. Schema coverage is 67%, but the main payload remains underspecified.
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?
The description states a specific action (update) and resource (one canvas embedded document), which clearly differentiates it from the create/delete/get siblings. However, it lacks any additional context about document types or scope, though the schema enum provides that.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus create_canvas_documents, delete_canvas_document, or get_canvas_documents. There are no prerequisites, use cases, or exclusions mentioned, leaving the agent without direction on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=false appropriately flags this as a mutating operation, but the description adds no behavioral context about side effects, such as whether the encounter is deleted, whether combatants are removed, or whether the action is reversible. This is a significant gap for a state-changing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with zero wasted words. It is front-loaded and easy to parse, though its brevity sacrifices useful context.
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?
Given the lack of an output schema and minimal parameter descriptions, the description should explain the tool's effects and conditions (e.g., must be in an active encounter). None is provided, leaving significant gaps in an agent's understanding of the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes userId and clientId, but the encounter parameter lacks a description. The phrase 'End an encounter' only trivially suggests encounter is the target; it does not clarify requiredness, value format, or default behavior. With 67% schema coverage and no compensation from the description, this falls below the baseline.
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?
The description 'End an encounter' clearly states the action and object, and the verb 'end' distinguishes it from siblings like start_encounter and next_turn. However, it is extremely minimal and does not elaborate on what ending entails, so it is clear but not fully detailed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as foundry_start_encounter or foundry_next_turn, nor about prerequisites like needing an active encounter. The intended use is only implied by the verb 'end'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description aligns by stating 'Read'. The description adds minimal context about the scope (folders and document references) but does not disclose behavioral details such as whether the operation is recursive by default, whether it requires specific permissions, or how the output is structured. With readOnlyHint covering the safety profile, the added value from the description is limited but acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no unnecessary filler. It clearly states the core purpose and is front-loaded with the action word 'Read'. While it could be expanded for completeness, the conciseness itself is appropriate and matches the structure of a tool description that is meant to be brief.
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?
With 7 parameters, low schema coverage, and no output schema, the description is under-specified. It explains the tool's high-level purpose but doesn't clarify the meaning of 'structure', how parameters interact, or what the return value looks like. The agent would have to guess key details for correct invocation, making this incomplete relative to the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29%, with only userId and clientId having descriptions. The tool's description provides zero information about any of the 7 parameters (path, types, recursive, recursiveDepth, includeEntityData). Since the schema coverage is low, the description must compensate but entirely fails to do so, leaving the agent without guidance on how to use these parameters.
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?
The description clearly states the action ('Read') and the target resource ('folders and document references' in a Foundry world). This distinguishes it from sibling tools like foundry_get_folder (which retrieves a specific folder) and foundry_get_entity (which retrieves a specific entity). However, the term 'document references' is somewhat ambiguous and could be clearer about the output structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided for when to use this tool versus alternatives. The description does not mention prerequisites, typical use cases, or exclusions. Given the large set of sibling tools with overlapping domains (folders, entities, search, files), the absence of usage guidance is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotation readOnlyHint=false indicating mutation, the description adds no detail about side effects, token identification, animation behavior, or required scene context. Since annotations provide minimal coverage, the description carries the burden and fails to disclose these.
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?
A single clear sentence with no filler; it is appropriately compact and front-loaded. Every word earns its place.
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?
For a tool with 9 parameters, no output schema, and minimal annotations, this one-line description is grossly incomplete—it omits token identification, scene targeting, animation options, and expected return behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 22%, with only userId and clientId briefly described. The description does not explain x/y coordinates meaning, the difference between name and uuid, animate, waypoints, or sceneId, leaving most parameters ambiguous.
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?
The description uses the specific verb 'Move' and resource 'token' with destination 'canvas coordinates', clearly stating the action. However, it doesn't differentiate from sibling tools like update_canvas_document that could also move tokens.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this versus alternatives such as update_canvas_document or select_tokens, nor any preconditions like scene/selection requirements. The description provides no usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=false indicates a write operation, but the description adds no behavioral detail about whether effects are appended or overwritten, required permissions, failure modes, or the role of the required uuid. For a mutation tool, this is insufficient.
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?
A single sentence of nine words, immediately conveying the operation with zero waste. Perfectly front-loaded.
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?
For a 5-parameter write tool with no output schema and minimal annotations, the one-liner is inadequate. It does not explain how to construct effectData, how statusId maps to standard effects, or what a successful response looks like.
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 schema already describes userId, clientId, and effectData (60% coverage). The description hints at statusId vs effectData for status vs custom effects, adding some meaning, but uuid and statusId remain undocumented in both description and schema, so it only partially compensates.
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?
The description clearly states the action (add) and the resource (status or custom active effect), distinguishing it from sibling tools like foundry_remove_effect and foundry_get_effects. It is specific but omits the target entity (uuid) context, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor any prerequisites or exclusions. The description does not clarify when to use statusId vs effectData or how this differs from other effect-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=false, the annotation already signals a write operation. The description merely restates this fact with 'Create' and adds no further behavioral context, such as side effects, required permissions, or what happens to the current scene.
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 a single, front-loaded sentence that conveys the core purpose with zero superfluous words. It is appropriately concise for a simple operation.
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?
Given the tool requires a complex nested data object and has no output schema, this one-line description is insufficient. It does not explain what a scene requires, how the data object should be structured, or what the expected result is, leaving the agent without enough context to invoke the tool correctly.
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?
Schema description coverage is 100% for all three parameters, so the baseline is 3. However, the description offers no additional meaning beyond the schema; the 'data' parameter is vaguely described as 'JSON object accepted by Foundry' with no enrichment from the 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?
The description 'Create a new scene' clearly identifies the action (create) and the target resource (scene). It distinguishes from sibling tools like update_scene or delete_scene via the verb, though it lacks any additional detail about what makes this scene creation different from other scene operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The description does not mention prerequisites, typical use cases, or exclusions, such as when update_scene might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations include readOnlyHint: true, indicating safety. However, the description adds no additional behavioral context: it does not explain what happens when no roll exists, whether the result is scoped to a user, or whether it uses the default client. It merely restates the tool's name.
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 a single, clear sentence with no wasted words. It front-loads the purpose and is appropriately sized for a simple getter operation.
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?
The tool has no output schema, so the description should clarify what is returned and edge cases. It does not mention the return format, potential null result, or how the optional userId/clientId parameters affect the outcome. The description is too minimal for a tool that could have ambiguous behavior.
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 provides descriptions for both parameters (userId and clientId), achieving 100% schema coverage. The description does not add any parameter-specific meaning, but the baseline of 3 is appropriate given the schema already documents them.
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?
Description states a specific verb and resource: 'Get the latest roll.' It clearly indicates a read operation targeting a singular roll. It does not explicitly distinguish from the sibling foundry_list_rolls, but 'latest' implies a specific item, providing some differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like foundry_list_rolls or foundry_roll. There is no mention of exclusions, prerequisites, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers safety, and the description's 'recent' adds temporal ordering. However, it doesn't disclose behaviors like pagination, default limits, or response format. The 'Get' action is consistent with the annotation, and no contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single five-word sentence with no wasted words. It lacks detail, but for what it conveys, it is well-structured and front-loaded.
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?
With no output schema and a terse description, the agent gets no information about return shape, what constitutes a 'roll', or how this differs from related tools. The absence of usage and behavioral context leaves significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description offers no parameter explanations. Schema coverage is 67% (userId and clientId have descriptions), but 'limit' lacks any description and the tool description does not compensate. Parameter names are intuitive but not sufficiently clarified.
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?
The description 'Get recent rolls' clearly specifies the action (get) and resource (rolls), with 'recent' indicating plural temporal retrieval. It does not explicitly differentiate from sibling tools like foundry_get_last_roll or foundry_roll, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as foundry_get_last_roll or foundry_roll. No context is given for typical usage scenarios, exclusions, or requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, which is consistent with 'Advance'. However, the description adds no extra behavioral details beyond that, such as side effects, reversibility, permissions needed, or what happens if no encounter is active.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The one-sentence description is concise and front-loaded with the action verb. It wastes no words, though its brevity sacrifices contextual explanation. The structure is fine but could have been slightly expanded without losing clarity.
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?
Given no output schema and only readOnlyHint=false as an annotation, the description is too sparse for an agent to understand execution context. It omits prerequisites, observable effects, or edge cases like advancing past the last turn. This leaves meaningful gaps for a tool that mutates game state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers userId and clientId but leaves the encounter parameter undocumented (67% coverage). The description does not clarify what 'encounter' refers to, whether it is optional, or how to obtain a valid ID, failing to compensate for the gap.
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 uses a clear verb 'Advance' and identifies the resource as 'the next encounter turn'. It distinguishes itself from sibling tools like previous_turn and next_round by specifying turn direction and unit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It implicitly suggests use during an encounter but lacks any statement of prerequisites, exclusions, or context such as requiring an active encounter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already communicates that this is a safe read operation, so the description does not need to repeat that. It does add the scope of searching 'world entities and compendiums,' which is beyond the annotation, but it offers no additional behavioral details like result limits, pagination, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is appropriately brief for a simple search tool, though it could have been slightly more detailed without becoming verbose.
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?
Given the tool has 8 parameters, no output schema, and no usage context, the description is inadequate. It does not explain what results look like, how to paginate or limit results, or how search differs from direct entity retrieval, leaving significant gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, and the tool description does not compensate for the six undocumented parameters. It only implies that a 'query' or 'filter' parameter is involved, but it does not explain their syntax, purpose, or how they interact, leaving most parameters semantically under-specified.
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?
The description clearly states the verb 'search' and the resource 'world entities and compendiums,' which distinguishes it from sibling tools like get_entity or get_structure. However, it lacks specificity about what constitutes 'world entities' and whether it also searches folders or other resources, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_entity, get_structure, or list_files. It does not mention any exclusions, prerequisites, or typical use cases, so the agent is left without context for selecting this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (destructiveHint: true, readOnlyHint: false) already communicate the destructive nature. The description adds no further behavioral context, such as permanence, permissions, or impact on related scene data. It is consistent with annotations but not informative beyond them.
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 a single short sentence with no wasted words, fully front-loaded. It earns its place.
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?
The tool is a destructive operation with no output schema and minimal description. It does not explain prerequisites, the effect on the scene, or how to identify the document beyond the schema. With five parameters and a complex domain (canvas documents), the description is insufficient for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any parameters. While the schema covers 60% of parameters with descriptions (userId, clientId, documentType), sceneId and documentId are not described. The description adds no meaning beyond the schema, and the missing context for sceneId (e.g., its role in locating the document) is not compensated.
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?
The description uses a specific verb ('Delete') and identifies the resource ('canvas embedded document'), clearly distinguishing it from sibling delete tools for entities, folders, scenes, and chat messages. However, it does not elaborate on what constitutes a canvas embedded document, leaving some ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like update_canvas_document or delete_entity. The description is purely definitional and offers no context, exclusions, or recommended scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds only 'from a scene' as a scope constraint. It does not disclose whether sceneId is optional, what happens if omitted, return format, or pagination behavior. This is minimal behavioral context beyond the annotation.
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 a single, concise sentence with no filler. It is front-loaded and every word contributes to the core purpose, making it appropriately sized for a simple retrieval tool.
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 having 5 parameters and no output schema, the description is too sparse. It does not explain what canvas embedded documents are, how sceneId is resolved, or how documentType filters results. Given the many sibling tools, the description lacks operational context necessary for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 60% of parameters (userId, clientId, documentType), but sceneId and documentId are undocumented. The description merely hints at 'a scene' without explaining parameter usage or filtering semantics, failing to compensate for the undocumented parameters.
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 'Get canvas embedded documents from a scene' clearly states the specific action (get) and resource (canvas embedded documents), with a scope ('from a scene'). It distinguishes this tool from sibling tools like foundry_create_canvas_documents and foundry_delete_canvas_document by focusing on retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., get_entity, create_canvas_documents) or how to specify a scene. There are no exclusions, prerequisites, or mentions of related tools, leaving the agent to infer usage from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation indicates readOnlyHint=false, so the tool is known to mutate state, but the description adds no further behavioral context. It does not disclose side effects, requirements (e.g., an active encounter), or what happens if no encounter is active.
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 a single, concise sentence (six words) that front-loads the action and resource. There is no redundancy or extraneous information, making it highly efficient.
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?
For a mutation tool with no output schema, the description is too minimal. It does not mention preconditions, return behavior, or side effects. Given the complexity of encounter management, the description leaves significant gaps that an agent would need clarified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, but the description adds no parameter information. The 'encounter' parameter is undocumented, and the description does not clarify which parameters matter or how they affect the action. The description provides no value beyond the schema.
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 uses a specific verb ('Advance') and resource ('next encounter round'), clearly distinguishing it from siblings like 'next_turn' and 'previous_round'. It unambiguously states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'foundry_next_turn' or 'foundry_previous_round'. It does not mention prerequisites like an active encounter, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=false annotation already indicates this is a mutating operation. The description merely restates the action ('Return to previous encounter round') without disclosing side effects, prerequisites, or potential failure modes. No additional behavioral context is provided beyond the annotation.
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 a single short sentence that directly conveys the tool's purpose with no filler or redundant information.
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?
With no output schema, only a readOnlyHint=false annotation, and no mention of preconditions or side effects, the description is insufficient for an agent to fully understand the operational context. The agent is left guessing about required encounter state and return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the three parameters. Schema coverage is 67%, but the 'encounter' parameter lacks a description in the schema, and the tool description does not compensate by clarifying what 'encounter' refers to or how the parameters influence the operation.
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 uses a specific verb ('Return to') and clear resource ('previous encounter round'), making the tool's purpose unambiguous. It also distinguishes itself from the sibling tool foundry_next_round by specifying 'previous' instead of 'next'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage during an active encounter but provides no explicit guidance on when to use this tool versus alternatives like foundry_previous_turn or foundry_next_round. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the annotations already provide (destructiveHint=true). It does not mention whether deletion is permanent, cascades to related documents, requires specific permissions, or returns a confirmation.
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 a single, clear sentence that immediately states the action and supported identifier types. Every word contributes meaning, with no filler or repetition.
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 being a destructive operation, the description lacks essential context: it does not state that at least one of name/sceneId is required, what happens if both are given, or what the tool returns after deletion. Given the 4-parameter schema with no required fields and no output schema, this is insufficient for an agent to invoke the tool correctly.
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 description clarifies that 'name' and 'sceneId' are alternative identifiers for the scene, adding some meaning to those parameters. However, schema coverage is 50% (only userId and clientId have descriptions), and the description does not compensate by explaining whether both identifiers can be used together or which one is preferred.
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 uses a specific verb ('Delete') and resource ('scene'), and clearly states the identification methods ('by ID or name'). This distinguishes it from sibling tools like foundry_update_scene or foundry_delete_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, nor does it mention that a scene identifier must be provided (name or sceneId) despite no required parameters in the schema. It does not clarify whether name or sceneId takes precedence if both are supplied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=false already alerts to mutation, but the description adds no behavioral context beyond the word 'Add'. It does not disclose side effects such as whether tokens are duplicated, how rollInitiative behaves, or what happens if the encounter does not exist. With no extra behavioral information, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to the core meaning, making it highly concise and readable.
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?
This is a mutation tool with 6 parameters, no output schema, and minimal annotation. The description does not cover important context such as return values, error conditions, or how the encounter is identified. Given the tool's complexity, the description is too thin to be considered complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only userId and clientId have descriptions). The description adds meaning for 'selected' and 'named' (mapping to the selected boolean and uuids array), but it does not explain the 'encounter' or 'rollInitiative' parameters. It partially compensates but leaves significant gaps in 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 uses the specific verb 'Add' with a clear resource ('selected or named tokens') and target ('an encounter'), which clearly distinguishes it from sibling tools like remove_from_encounter. It states exactly what the tool does without ambiguity.
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 description implies usage: when you need to add tokens to an encounter. However, it does not provide explicit guidance on when to prefer this over alternatives, nor does it mention any prerequisites or exclusions. It is adequate but lacks explicit directional cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the agent knows the operation is safe. The description adds no further behavioral context—it doesn't mention error handling, authentication requirements, response format, or side effects. It merely restates the purpose without disclosing any traits beyond the annotation.
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 a single concise sentence, front-loaded with the key action, and contains no waste or redundant details. It is optimally sized for the information it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and no output schema, but the schema descriptions are comprehensive and the read-only annotation provides safety context. The description lacks discussion of edge cases, defaults, or how to choose among the optional parameters, but given the schema coverage, it is minimally adequate. More context (e.g., file not found behavior or source selection) would improve completeness.
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 covers all 5 parameters with descriptions (100% coverage), so the baseline is 3. The description adds no additional meaning to the parameters; it relies entirely on the schema. Since the schema is thorough, this is adequate but not improved by the description.
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 uses a specific verb and resource ('Download a file from a Foundry file source'), clearly distinguishing it from sibling tools like foundry_upload_file or foundry_list_files. It is unambiguous and immediately tells the agent 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention that this should be used for retrieving file contents as opposed to foundry_list_files for metadata, nor any preconditions or context. The description provides no exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the UUID-based retrieval scope but doesn't disclose pagination, return format, or behavior with invalid UUIDs. It's consistent with annotations, no contradiction.
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?
A single sentence, only 10 words, immediately front-loads the tool's purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with readOnlyHint and no output schema, the description covers the core purpose. However, with 5 optional parameters and no output schema, additional details about return values or parameter relationships would be helpful. It's minimally viable but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, with uuid, actor, and selected lacking descriptions. The description adds minimal context by indicating uuid is the document identifier, but it doesn't explain the boolean parameters or permission-related usage beyond what the schema already says for userId/clientId. The description should compensate more given the low coverage.
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?
The description clearly uses the verb 'Get' with resource 'one Foundry document' and method 'by UUID', giving an example 'Actor.abc123'. It distinguishes from siblings like foundry_get_scenes or foundry_search, though it doesn't explicitly define what 'entity' includes.
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 description implies using this tool when you have a specific UUID and need a single document, but it doesn't explicitly state when not to use it or mention alternatives like foundry_search for broader queries. Context signals list many sibling tools, but no guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation covers the safety profile, but the description adds no additional behavioral context beyond the tool's basic purpose. It doesn't disclose return format, whether an empty selection is possible, or how permissions affect results.
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 a single concise sentence that immediately conveys the tool's purpose with no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with well-documented optional params, the description is minimal but adequate. However, without an output schema, it doesn't specify what the return value looks like or how to interpret selection, leaving some ambiguity for the agent.
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 has 100% coverage with clear descriptions for both optional parameters (userId, clientId). The description adds no parameter information, so the baseline of 3 applies.
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 uses the specific verb 'Get' and resource 'tokens selected in the Foundry client,' clearly distinguishing it from siblings like foundry_select_tokens, which implies setting selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives is provided. The description only states the action, leaving the agent to infer usage context from the name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a safe read operation, and the description adds that the tool lists status effects 'supported by the game system,' which sets expectations about the scope of results. However, it does not disclose return format, pagination, or authentication requirements beyond what annotations provide.
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 a single, clear, front-loaded sentence with no unnecessary words. It directly states the action and object, making it highly concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description is minimally viable, but it lacks details about the return structure (no output schema) and does not disambiguate from related tools like foundry_get_effects. The context is sufficient for basic invocation but leaves ambiguities about the nature of 'status effects' and how they differ from other effect lists.
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 covers both parameters with clear descriptions, including defaults and purpose (e.g., userId for permission-scoped access, clientId defaulting to FOUNDRY_CLIENT_ID). The tool description adds no additional parameter information, so it relies entirely on the schema, which is adequate.
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?
The description clearly states the tool lists status effects, with a specific verb and resource. However, it does not explicitly distinguish itself from sibling tools like foundry_get_effects, which might overlap in purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as foundry_get_effects or foundry_add_effect. Usage is only implied by the tool's name and one-line description, with no exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation readOnlyHint=false already indicates mutation. The description adds the 'player-facing' nuance, which is useful context, but it does not disclose permissions, side effects on the previous scene, or the result of the operation. Has modest added value beyond annotations.
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 a single six-word sentence, highly concise and front-loaded. Every word contributes 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?
The tool has no output schema and zero required parameters, so the description must compensate. It fails to explain how to specify the target scene, what happens on success or failure, or whether the operation is restricted to GMs. Too sparse for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, with name and sceneId lacking descriptions. The description does not add any meaning to these parameters, leaving ambiguity about which identifiers are valid and how the parameters relate. With zero required parameters, this is a notable gap.
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 uses a specific verb ('Switch') with a clear resource ('player-facing active scene'), which effectively distinguishes it from sibling tools like foundry_update_scene or foundry_get_scenes. It conveys the essential action concisely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention exclusions or related tools. It is a bare statement of the operation without contextual cues for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=false already signals a write operation, so the description adds no new transparency about update semantics, data loss risk, or required permissions. It does not explain whether the update replaces or patches the documents array.
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 a single concise sentence (nine words) that is front-loaded and immediately understandable. Every word earns its place.
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?
Given the tool's mutation nature and lack of output schema, the description omits critical context such as whether updates require document _ids, whether it replaces or merges, and any side effects. It is minimally viable but leaves major gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 60%, but the description does not explain the structure or application of the 'documents' array or clarify the 'documentType' values beyond their names. It fails to compensate for the undocumented parameters.
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 uses the specific verb 'Update' and identifies the exact resource ('Items or ActiveEffects embedded in one actor'). It clearly distinguishes from sibling create/delete tools and other entity update tools.
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 description implies usage context (updating embedded documents on a single actor) but does not explicitly state when to use it over the create/delete sibling tools or mention any exclusions. Usage is clear from context but not formally separated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds little beyond the annotation readOnlyHint: false, which already signals a write operation. It does not disclose side effects such as overwrite behavior, permission requirements, or whether the operation is idempotent. For a write tool, this is a significant gap in transparency.
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 a single, focused sentence that is front-loaded with the action and resource. It contains no redundant words or filler, making it highly efficient.
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?
The tool has 8 parameters, some lacking descriptions, and no output schema. The description only states the core action, making it insufficient for an agent to fully understand success/failure behavior, return values, or edge cases like overwrite. For a tool with this complexity, the description is notably incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 63%, and the description adds no new information about parameters. It repeats the base64/data URL detail found in the fileData schema description, but fails to explain filename, mimeType, overwrite, or path. The description does not compensate for the missing parameter documentation, offering minimal added value.
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 states the tool's function: uploading a base64-encoded file or data URL to a Foundry file source. It uses a specific verb (Upload) and resource (file source), and distinguishes from sibling tools like foundry_download_file and foundry_list_files, making the tool's purpose unambiguous.
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 description implies when to use the tool (whenever you need to upload a file to Foundry), but provides no explicit guidance on when not to use it or how it compares to alternatives like creating a folder or using data URLs vs. base64. There is no mention of alternatives or exclusion criteria, so it falls short of clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, and the description's verb 'Delete' is consistent. However, the description adds no additional behavioral context such as irreversibility, impact on linked data, or permission requirements beyond what annotations imply.
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 a single concise sentence that directly states the action and target, with no unnecessary words. It is front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal but covers the basic purpose; however, for a destructive tool with multiple parameters, it lacks context about permanence, error conditions, or usage scenarios. The presence of annotations and schema partially compensates, but the description alone is insufficient for a fully informed invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-level detail beyond the schema; it repeats the documentType enum values and actor scope but does not explain documentIds or how parameters interact. With 60% schema coverage leaving documentIds undocumented, the description does not compensate for that gap.
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 uses a specific verb ('Delete') and clearly identifies the resource ('Items or ActiveEffects embedded in one actor'), which distinguishes it from sibling tools like delete_entity or delete_scene. It accurately summarizes the operation scope without being tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose this tool over alternatives such as delete_entity or update_actor_embedded_documents. It states what the tool does but does not mention any use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the destructive nature is covered. The description adds that selection can be based on UUID or current selection, which is useful targeting context. However, it does not disclose consequences like irreversibility, cascading deletes, or permission requirements, so it adds limited value beyond annotations.
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?
A single, direct sentence with no filler. The verb, resource, and targeting method are front-loaded, making it easy to scan.
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?
With zero required parameters, the description does not explain how the tool determines its target if neither uuid nor selected is provided. It also omits return values, error behavior, and any interaction with the Foundry client context, leaving a simple but ambiguous operation under-specified.
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?
Schema coverage is 50% (uuid and selected lack descriptions). The description partially compensates by explaining the two targeting modes, but it does not clarify the relationship between uuid and selected (e.g., precedence if both are set) or expand on userId/clientId, which already have schema descriptions.
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 states the action ('Delete'), the resource ('Foundry entity'), and the two targeting modes ('by UUID or the current selection'). This distinguishes it from sibling tools like foundry_get_entity, foundry_update_entity, and specific delete tools for folders/scenes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternative delete tools (e.g., foundry_delete_folder, foundry_delete_scene) or when to prefer UUID over selection. There are also no prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates the operation is safe, but the description adds no additional behavioral context such as measurement units, Euclidean vs. grid distance, line-of-sight considerations, or the structure of the returned result. Since there is no output schema, the agent is left unaware of what the tool actually returns. The phrase 'points or tokens' hints at input modes but does not elaborate on behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the core purpose. It is concise and to the point, with no wasted words. However, given the tool's complexity (11 parameters, no output schema), a slightly longer description that included essential usage hints would arguably be more appropriate, so it earns a 4 rather than a 5.
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?
The description is not complete enough for a tool with 11 parameters and no output schema. It lacks critical information about units, measurement type, how to specify points vs. tokens, the need for scene selection, and what is returned. The high parameter count and absence of parameter descriptions in the schema place a heavy burden on the description, which it fails to meet.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is very low at 18%, with only userId and clientId having descriptions. The description does not explain the 11 parameters, such as how originX/Y vs originName/UUID relate to 'points or tokens,' whether sceneId is required, or how coordinates should be formatted. The mention of 'points or tokens' provides a minimal hint but falls far short of compensating for the lack of schema descriptions.
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 states the tool's function with a specific verb and resource: 'Measure distance between two points or tokens.' This is immediately understandable and distinguishes it from sibling tools, which are primarily CRUD operations, canvas manipulation, and chat utilities. The wording is unambiguous and leaves no doubt 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that the tool is for measuring distance, and there are no closely related sibling tools that perform measurement. However, it does not explicitly state when to use this tool over alternatives or provide any exclusions, which slightly prevents a perfect score. The intended use case is implicitly obvious from the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=false already communicates that this is a mutating operation, and the description aligns with that. However, it does not disclose additional behavioral nuances, such as how it interacts with rounds or what happens at encounter boundaries. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. It efficiently communicates the action 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?
For a state-changing tool with three parameters and no output schema, the description is too sparse. It omits whether an active encounter is required, how the encounter parameter is used, and the behavior at start/end of a turn or round. This leaves significant gaps for an agent selecting or invoking the tool.
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?
Schema description coverage is 67%, with userId and clientId documented but 'encounter' left unexplained. The description adds no parameter semantics, leaving the critical 'encounter' parameter ambiguous. Baseline is acceptable given moderate coverage.
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 uses a specific verb 'return' and identifies a clear resource ('previous encounter turn'), distinguishing it from siblings like foundry_next_turn and foundry_previous_round. It unambiguously states the action performed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites (e.g., whether an encounter must be active) or contrast with next_turn/previous_round. It simply states the function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the destructiveHint annotation by stating 'Remove'. It adds the qualifier 'active effect' and the two selection modes, but does not disclose irreversibility, required permissions, or behavior when both ID and status are provided. Annotation contradiction is absent.
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 a single sentence that directly states the action and options, with no wasted words.
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?
Given five parameters and no output schema, the description is minimal. It omits the role of the required uuid, possible parameter combinations, and return/error behavior, leaving significant gaps for the agent.
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 phrase 'by ID or status' gives semantic meaning to effectId and statusId, which lack schema descriptions. However, the required uuid parameter is not explained, and user/client parameters are only described in the schema. At 40% schema coverage, the description only partially compensates.
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 uses a specific verb ('Remove') and resource ('active effect') and specifies two selection modes ('by ID or status'), clearly distinguishing it from sibling tools like foundry_add_effect or foundry_get_effects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention prerequisites, exclusions, or when to prefer effectId over statusId.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes the safety profile. The description adds the scope of listing both files and directories but does not disclose behavior such as default recursion, path handling, or whether source 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?
The description is a single, focused sentence that front-loads the verb and object with no extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool description is minimal but covers the core purpose. With no output schema and a read-only annotation, the agent lacks information about return structure or how source/path/recursive affect results, yet this is a simple list operation.
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 schema already covers 80% of parameters with descriptions, and the tool description adds no additional parameter semantics. The recursive parameter has no schema description, but the name is self-explanatory; the description doesn't clarify its interaction with path.
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 uses a specific verb ('List') and resource ('files and directories') within a Foundry file source. It clearly conveys a read-only listing operation, distinguishing it from file transfer tools like download/upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to choose this tool over siblings (e.g., foundry_get_folder or foundry_download_file). It neither states prerequisites nor excludes alternative use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, so the destructive nature is known. The description does not add any extra behavioral context (e.g., permanence, side effects) but is consistent with the annotation and does not contradict it.
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 a single, direct sentence: 'Delete one chat message.' It is concise, front-loaded, and free of unnecessary words or repetition.
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?
For a simple delete operation, the description combined with the schema and annotations provides sufficient context. The agent knows it is destructive and requires a messageId. The lack of an output schema and the simplicity of the tool mean additional detail is not necessary.
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?
Schema coverage is 67% (2 of 3 parameters have descriptions), so the baseline is 3. The tool description adds no parameter-specific information, but the required messageId is implied by the tool name and the userId/clientId are already documented in the schema.
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 states the verb 'delete' and the resource 'chat message', which is specific and distinguishes it from sibling tools like foundry_send_chat_message or foundry_clear_chat. It unambiguously indicates the action of removing a single chat message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as foundry_clear_chat for bulk deletion. It simply states the action without any context about appropriate use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the safety profile, so the bar is lower. The description adds the behavioral detail that the result includes both the folder and its contents, which is useful. However, it fails to disclose what 'contents' encompasses (files, subfolders, documents?), how the result is structured (nested vs flat), or any permission-related behavior. The userId parameter hints at permission scoping but is not mentioned in the description.
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 a single, front-loaded sentence with no redundant or filler content. Every word is meaningful and efficiently communicates the core action and target resource.
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 readOnlyHint annotation, the description is insufficient for an agent to fully utilize the tool. There is no output schema, and the description does not specify the return format, the exact composition of 'contents', behavior for multiple folders with the same name, or error conditions. The tool is not trivial enough to rely on the sparse description alone, and the lack of return structure guidance could lead to misinterpretation.
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 description coverage is 67% with userId and clientId already described. The description adds critical meaning to the primary parameter 'name' by specifying that it is a folder name, which the schema alone (a string with minLength 1) does not convey. This compensates for the uncovered 'name' parameter and makes the parameter semantics clear enough for invocation.
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 'Get a folder and its contents by name' uses a specific verb ('Get') and resource ('folder'), and explicitly indicates the return scope ('contents') and lookup method ('by name'). This clearly distinguishes it from sibling tools like foundry_get_structure, foundry_get_entity, and foundry_get_scenes, which target different resource types or broader scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose this tool over alternatives. It does not reference sibling tools such as foundry_get_structure (for full world structure) or foundry_get_entity (for individual entities), nor does it mention any exclusions or prerequisites. The only implied context is that a folder name is needed, but no usage scenario or alternative selection logic is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint: true annotation already conveys the safe read-only nature of the tool. The description adds only 'optional pagination and filters,' which is more about parameters than behavioral traits. It does not disclose scope, ordering, or handling of edge cases, so transparency is adequate but not enriched.
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 a single concise sentence with no redundant words. It is front-loaded with the core action ('Get chat messages') and adds relevant qualifiers ('optional pagination and filters') without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, no output schema, and a sparse description. While the purpose is clear, the description omits details about which filters are available and what the response structure looks like. For a listing tool, this leaves some gaps for the agent, but the overall simplicity keeps it from being severely incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at only 33%, the description should compensate by explaining the un-covered parameters. It mentions 'pagination and filters' generically but does not name which parameters correspond to each role (e.g., limit/offset vs. speaker/chatType). This adds minimal meaning beyond the schema's property names and required flags.
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 uses a specific verb ('Get') and resource ('chat messages'), clearly distinguishing it from sibling tools like foundry_send_chat_message, foundry_delete_chat_message, and foundry_clear_chat. Mentioning 'optional pagination and filters' further clarifies the scope of the operation.
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 description implies usage for retrieving chat messages and notes optional pagination/filters, but it does not explicitly state when to use this tool versus alternatives like send/delete/clear chat. There are no exclusion criteria or comparative guidance, making the usage guidance minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes that this is a safe read operation, so the description needs only to add beyond that. It adds the qualifier 'active', which is a behavioral filter beyond mere listing. However, it does not disclose any other behavioral details such as whether the list is scoped to the current world, whether encounters are sorted, or what constitutes 'active' versus inactive. This is minimal but non-contradictory.
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 a single, front-loaded sentence with zero filler. It gets straight to the verb and resource, and the word 'active' is the only modifier. This is as concise as possible while still conveying the essential action.
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?
The tool is a simple read-only list with fully documented parameters and a clear annotation. The description covers the core action and the active filter. It lacks a bit of context about what 'active' means in the Foundry encounter lifecycle and doesn't mention permissions, but given the low complexity, it is nearly complete. The absence of an output schema means a description of return fields could be helpful, but it is not strictly necessary for a list operation.
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 schema covers 100% of the parameter descriptions, so the baseline is 3. The description 'List active encounters' does not add any extra meaning to the two optional parameters (userId and clientId) beyond what the schema already states. The params are straightforward optional auth/scope overrides, and the description provides no additional usage hints.
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 'List active encounters' uses a specific verb ('List') and a specific resource ('active encounters'), clearly distinguishing it from sibling encounter mutation tools like start_encounter and end_encounter. It also clarifies that only active (in-progress) encounters are returned, not all historical ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is the correct choice for checking ongoing encounters before starting or modifying one, nor does it exclude cases where a broader or narrower view might be needed. The single sentence is purely a statement of function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, indicating a write operation, but the description adds no behavioral context beyond that. It does not disclose whether data is merged or replaced, what permissions are required, what happens if both uuid and selected are provided, or the success/failure response. The description's only extra is the targeting modes, which do not illuminate the update behavior itself.
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 a single, efficient sentence that front-loads the core action and targeting. Every word earns its place; there is no redundancy or filler.
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?
For a tool with 6 parameters, no output schema, and a general 'entity' concept, the description is underspecified. It lacks essential context such as what an 'entity' is in this Foundry MCP context, whether the update is partial or full replacement, what response to expect, and any constraints (e.g., cannot use both uuid and selected). The presence of many sibling tools (create, delete, get) makes the lack of boundary-clarifying context more impactful.
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?
Schema coverage is 50% (data, userId, clientId have descriptions; uuid, actor, selected do not). The description adds context that uuid and selected are alternative ways to identify the entity, which helps interpret those parameters. However, it does not compensate for the vague 'data' parameter (just 'JSON object accepted by Foundry') or clarify the role of actor or the interaction between parameters.
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 states the action ('Update a Foundry entity') and specifies the targeting mechanism ('by UUID or the current selection'). This distinguishes it from sibling tools like foundry_create_entity and foundry_delete_entity, so purpose is 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?
The description implies when to use this tool: when you need to modify an existing entity, identified either by uuid or through the current selection in Foundry. It does not explicitly name alternatives or exclusions, but the verb 'update' and targeting modes provide clear contextual usage for an action-oriented tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, and the description adds that the action is permanent and applies to all messages, which is helpful context beyond the raw annotations. However, it does not address whether the operation is undoable or if special permissions are 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?
A single, front-loaded sentence that states the core behavior with no filler or redundant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive tool with two optional params and clear annotations, the description is adequate but lacks any detail about how the parameters alter behavior or what the tool returns after clearing. The absence of an output schema and minimal context about side effects leaves some gaps.
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 covers both parameters with descriptions (100% coverage), so the baseline is 3. The description does not clarify how optional userId or clientId affect the 'all messages' scope, leaving a minor semantic gap.
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 states the action ('clear'), the resource ('chat messages'), the scope ('all'), and the consequence ('permanently'). This unambiguously distinguishes it from sibling tools like delete_chat_message (single message) or list_chat_messages (read-only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as delete_chat_message. It does not mention prerequisites, permissions, or situations where a bulk clear is appropriate, leaving the agent to infer from the name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the annotation readOnlyHint=false (it's a create/write operation). However, it provides no additional behavioral context such as permissions required, side effects, idempotency, or return value. The simple 'create' action is clear, but lacks depth beyond what annotations already signal.
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 a single, focused sentence that immediately communicates the core purpose. It is efficiently written with no filler or repetition, fitting the tool's straightforward nature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with no output schema, the description is minimal. It doesn't explain what the return value will be, any preconditions, or how the created documents manifest. However, the operation is conceptually simple, and the schema covers required parameters, so this is a borderline pass but with clear gaps.
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?
Schema coverage is 80%, with most parameters having descriptions. The description adds no parameter-level detail beyond stating 'one or more', which is already reflected in the 'data' property's description. Since the schema handles the semantics, the description doesn't add significant value, but it doesn't need to.
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 states the action ('Create') and the resource ('canvas embedded documents'), which distinguishes it from the sibling tool 'foundry_create_actor_embedded_documents'. The phrase 'one or more' also communicates the tool's multi-create capability, making the purpose unambiguous.
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 description implies usage for creating canvas documents, and the name differentiates it from actor-embedded document creation. However, there is no explicit guidance on when to prefer this tool over alternatives, nor any mention of prerequisites or exclusion criteria. Usage context is only implied by the resource type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=false annotation already signals a write operation. The description adds extra context about item creation using an upsert, revealing a non-obvious behavioral trait beyond the annotation. However, the upsert nuance is not fully elaborated, so it doesn't reach the highest level of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with the key action front-loaded. The second sentence adds a useful behavioral nuance but is slightly cryptic. Overall, it is appropriately concise without being under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is present, and the description does not mention return values or prerequisites. The upsert behavior is mentioned but not fully explained, and the open-ended document schema is a significant gap for a create operation. The tool has moderate complexity, so more guidance would improve completeness.
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 schema provides descriptions for 60% of parameters (actorUuid, userId, clientId) and the documentType enum explains itself. The tool description clarifies that documents are for Items or ActiveEffects, but it does not compensate for the vague 'JSON object accepted by Foundry' description of the documents array, nor does it provide examples or structure.
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 uses a specific verb 'Add' and names the resource ('Items or ActiveEffects') and target ('one actor'), clearly distinguishing this from the update and delete sibling tools. It is unambiguous 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through 'Add' and the tool name, but does not explicitly state when to use this versus update/delete or provide alternative guidance. The phrase 'uses the relay's supported Actor items upsert' hints at behavior but not at selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint=true annotation is consistent with the 'list' operation, and the description adds scope ('connected to the relay') and output details (status and version). However, it does not disclose potential nuances like whether the list is live, if connections require authentication, or behavior on empty results. This adds some value but not rich behavioral context.
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 a single concise sentence, front-loaded with the action verb 'List' and includes all necessary details without redundancy. It earns its place with 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?
For a tool with no parameters, a readOnlyHint annotation, and no output schema, the description is quite complete. It states the scope (connected to relay) and the return contents (status, version). It could arguably mention that it is a snapshot or only currently active connections, but overall it is sufficient for the tool's simplicity.
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?
There are zero parameters, so the baseline is 4 per the rubric. The description adds meaning by indicating what the output covers (worlds, connection status, Foundry version), which helps set expectations even without parameters to document.
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 uses a specific verb 'List' with a clear resource 'Foundry VTT worlds connected to the relay' and specifies output contents (connection status, Foundry version). This distinguishes it from sibling tools like foundry_list_users and foundry_get_current_client by focusing on connected worlds/clients.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives. It does not mention use cases, exclusions, or when to prefer foundry_list_users or foundry_get_current_client. For a simple listing tool, this is a minor gap but still lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint: false annotation, the description discloses important behavioral traits: required permissions and the guarantee that 'The tool never accepts, returns, or logs a password.' This is significant security-relevant information that an agent needs to know. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of three short sentences. The first sentence state the purpose, the second provides permissions, and the third discloses the password handling guarantee. 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has six parameters, no output schema, and sparse annotations, the description is incomplete. It lacks parameter semantics, return value expectations, and any explanation of what the created user represents or how it will behave. The security-related context is helpful, but significant operational details are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17% (only clientId has a description). The description text does not explain any parameters such as role, color, active, or avatar, leaving the agent to guess their meaning and constraints. With low schema coverage, the description should compensate but provides zero parameter information.
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 states the tool's purpose with a specific verb and resource: 'Create a Foundry service or bot user.' It distinguishes from sibling tools like foundry_create_entity by explicitly targeting users versus generic entities. The scope (service/bot user) is specific enough to avoid confusion.
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?
The description provides clear context by stating the required permissions: 'Requires relay scope user:write and GM access.' This implies when the tool is appropriate (when those permissions are held) and gives practical usage context. It does not explicitly mention alternatives or exclusions, but there are no clear sibling alternatives for user creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation, so the description's 'Get' aligns with it. However, the description adds no further behavioral context such as whether inherited effects are included, what happens if no effects exist, or whether permissions affect the result beyond the schema's userId hint.
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?
A single, short sentence that is immediately informative and free of any redundant or extraneous text.
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?
For a simple read-only getter with readOnlyHint and clear param semantics, the description is complete enough to guide invocation. It could note the return type, but the tool name and description already convey the core purpose adequately given the sibling context.
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 descriptions cover userId and clientId, but uuid lacks a description. The tool description clarifies that the uuid refers to an actor or token, providing necessary meaning for the required parameter. This compensates for the 67% schema coverage.
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 uses the specific verb 'Get' and identifies the resource ('active effects') and its target ('an actor or token'), clearly distinguishing it from mutation tools like foundry_add_effect/foundry_remove_effect and from foundry_list_status_effects which likely returns all status effects globally.
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 description implies usage for retrieving active effects on a specific actor or token but provides no explicit guidance on when to prefer this over alternatives like foundry_get_entity or foundry_list_status_effects. 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=false annotation, the description discloses the permission restrictions and the non-obvious verification behavior. It reveals that the relay enforces a strict identity check and that scoped keys are not allowed to impersonate others. This adds meaningful context 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, action-first, and contains no filler. It delivers the core purpose and critical constraints in a tight, scannable format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action and permission model, but without an output schema or detailed parameter semantics, an agent may struggle with constructing valid requests (e.g., whisper chatType usage). It is adequate but leaves gaps around parameter behavior and error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no additional parameter guidance. While the schema includes descriptions for userId, whisper, chatType, and clientId, it leaves alias, content, and speaker undocumented. The description does not compensate for these gaps, leaving ambiguity for parameters like speaker and alias.
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 uses a specific verb+resource construction: 'Create a chat message as a Foundry user'. It also adds a verification step ('verify the returned ChatMessage.author.id'), which clarifies the intended outcome. This distinguishes it from the sibling tool foundry_send_chat_message by emphasizing user impersonation and scoping.
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?
It clearly states when the tool can be used: 'The relay permits this only for the API key's scoped user, or for a GM key'. It also warns that 'scoped keys cannot be overridden', which is a key usage constraint. It does not explicitly name alternative tools, but the context implies when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description doesn't need to repeat that. It adds valuable context by noting that deleteAll also deletes folder contents, which is a key behavioral nuance not present in the schema or annotations. No contradictions.
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 short sentences, front-loaded with the primary action. No filler words. Every word adds value.
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?
For a destructive tool with a simple schema and no output schema, the description covers the essential behavior. It could mention that deletion is permanent or requires permissions, but the annotations already signal destructiveness. The deleteAll nuance is included, making it complete for its complexity.
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 description coverage is 50%, with userId and clientId described. The description adds meaning for deleteAll, which is otherwise undocumented in the schema. folderId's purpose is obvious from context, and deleteAll's effect is explained. This compensates for the missing schema descriptions.
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 states the tool deletes a Foundry folder and specifies the deleteAll parameter behavior. It distinguishes itself from sibling delete tools (e.g., delete_entity, delete_scene) by explicitly targeting folders.
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 description implies usage (to delete folders) but does not explicitly state when to use this tool over alternatives or any exclusions. It lacks guidance like 'use for folders only' or comparison with delete_entity, so the context is clear but not fully elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, which already discloses the read-only nature. The description adds context about the 'currently resolved' state and the relationship between scoped keys and clientId, which goes beyond the annotation without contradicting it.
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, both of which earn their place: the first states the primary action, and the second provides a key nuance about scoped keys. There is no filler or redundancy.
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?
Given the tool's simplicity (0 params, readOnly annotation), the description is fairly complete. It conveys the core purpose and a relevant edge case. It could be more explicit about the exact return value, but the mention of clientId implies the output sufficiently.
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?
The tool has no parameters, so the schema is fully covered. The description does not need to add parameter details, and the note about scoped keys gives contextual meaning that is helpful for understanding the tool's behavior.
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 states the action ('Get') and the resource ('the relay's currently resolved Foundry world'). It also adds the distinguishing detail about scoped keys and clientId, which helps differentiate this tool from siblings like foundry_list_clients.
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?
The phrase 'With a scoped key' gives a specific scenario for using the tool, and it explains the benefit (identifying clientId without FOUNDRY_CLIENT_ID). However, it does not explicitly name alternatives or state when not to use the tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, and the description adds value by noting that GM access and user:read scope are required, plus clientId auto-resolution for scoped keys. This goes beyond the annotation to inform the agent about authorization and parameter behavior.
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 sentences with no wasted words; action, output fields, and requirements are front-loaded in a clear structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one optional parameter, the description covers purpose, output fields, permission requirements, and parameter behavior. No output schema exists, but the return fields are enumerated, making it complete for an agent to use correctly.
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?
The input schema already covers clientId fully, and the description adds the auto-resolution behavior for scoped keys. With 100% schema coverage, this extra context elevates the score above the baseline of 3.
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 explicitly states it lists Foundry users with specified output fields (id, name, role, isGM, active, avatar), clearly distinguishing it from sibling tools like foundry_list_clients which list clients, not users.
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?
The description gives clear context: it lists users and specifies required permissions (relay scope user:read and GM access). It doesn't explicitly name alternative tools, but the resource is unambiguous and prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![foundry-rest-api-mcp MCP server](https://glama.ai/mcp/servers/zagushka/foundry-rest-api-mcp/badges/card.svg)](https://glama.ai/mcp/servers/zagushka/foundry-rest-api-mcp)

Score Badge

Copy to your README.md:

[![foundry-rest-api-mcp MCP server](https://glama.ai/mcp/servers/zagushka/foundry-rest-api-mcp/badges/score.svg)](https://glama.ai/mcp/servers/zagushka/foundry-rest-api-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/zagushka/foundry-rest-api-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server