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

Annotations already mark destructiveHint=true and idempotentHint=true, and the description adds meaningful detail beyond that: it lists exactly which fields are overwritten, states that mechanics remain untouched, and explains that items without a resolvable source are listed and left alone. This is strong behavioral disclosure for a mutating tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-ordered: it starts with the problem, states what the tool changes, explicitly lists what it never changes, addresses unresolvable sources, and ends with the key safety instruction. Every sentence contributes useful information.

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

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

For a mutating tool with five parameters and no output schema, the description provides the essential mental model: stale copy problem, exact mutation scope, safety boundary, and dryRun workflow. The parameter schema covers the remaining details, so nothing important is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters. The description reinforces the dryRun-first behavior and the default fields but does not add substantive parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: refresh actor items from their source. It clarifies exactly what is pulled (name, image, description) and explicitly excludes mechanics such as levels, uses, and quantity, making it distinct from generic update tools like update-document or manage-actors.

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

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

Provides clear context for when this is appropriate: after a compendium has been translated or corrected and actors still contain stale copies. It gives an explicit safety instruction to run dryRun first, though it does not name alternative tools or state when not to use it.

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

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

The description adds useful behavioral context beyond annotations, such as how the ring behaves when enabled and how ringColor defaults to disposition-based coloring. However, despite destructiveHint=true, it does not explain the overwriting or potentially destructive consequences of changing the prototype token image.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no filler, front-loading the main purpose and then adding only relevant optional behaviors. Each clause adds actionable information without repetition of schema details.

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

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

For a 7-parameter mutation tool with no output schema, the description covers the target resource, identifier resolution, optional fields, and ring semantics. It is slightly incomplete regarding what happens on failure or whether existing placed tokens are affected, but these are minor gaps given the schema covers every parameter.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value by explaining behavior not fully explicit in the schema, such as ring color defaulting by disposition, ringScale being usually unnecessary, and the actor being found by id or exact name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action on a specific resource: 'Set an actor's prototype token image' and lists the optional modifications. The word 'prototype' and 'actor' clearly distinguish this from sibling token tools like update-token, which operate on placed scene tokens.

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

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

The description implies when to use it: when an actor's prototype token image needs to be set, optionally with portrait, token name, or ring changes. It does not explicitly contrast with alternatives such as update-token or manage-actors, nor does it state when not to use this tool.

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

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

Annotations already indicate idempotentHint=true, but the description adds concrete behavioral details: an unknown id stops the entire operation and tokens already in the encounter are not added twice. This goes beyond the structured annotations and helps an agent predict failure and duplicate handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences deliver the core action, token source, failure behavior, and duplicate prevention without wasted words. The most important information is front-loaded in the first sentence.

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

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

The description covers the key operational constraints: token source, unknown-id atomicity, and duplicate handling. With a 100%-covered schema and idempotentHint annotation, the remaining details are adequately supported, though it stops short of describing the exact success output or post-add state.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description reinforces the role of sceneIdentifier and the source of tokens, but it does not add meaning beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Add') and resource ('tokens to a combat encounter as combatants'), making the tool's function immediately clear. It also implicitly differentiates from siblings like remove-combatants and update-combatant by focusing exclusively on addition.

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

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

The description explains the token source (encounter scene, sceneIdentifier, or active scene), which provides useful context for when the tool can be used. However, it does not explicitly state when to prefer this tool over alternatives or mention exclusions, so usage guidance is implied rather than direct.

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

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

Annotations only mark this as non-read-only, non-idempotent, and non-destructive, so the description carries the burden of explaining side effects. It does so well: the operation writes world time, triggers effects/calendars/modules, requires the write switch, and reads back the new time. This adds meaningful behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences front-load the core operation and immediately clarify the negative-number case, followed by useful magnitude examples and the permission requirement. No filler or repetition of schema content.

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

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

For a simple two-parameter mutation tool with no output schema, the description covers the operation, direction, scale, system reaction, permission requirement, and read-back behavior. It could mention the ten-year limit, but that is already in the schema, so the description is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by giving concrete duration equivalents ('3600 is an hour and 86400 a day') and reiterating the direction semantics for negative numbers, which helps an agent reason about valid values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: 'Move the world time forward' by seconds through Foundry. It distinguishes itself from read-only time tools (e.g., get-world-time) by emphasizing that effects, calendars, and modules react, and it clarifies that negative numbers move time backward.

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

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

The description gives clear context for when to use this tool: when the GM wants the world clock to advance in-game so systems react as at the table. It does not explicitly name alternative tools or state when not to use it, but the context is strong enough to guide selection.

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

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

The description adds substantial behavior beyond the annotations: exact match semantics and no partial-name matching, GM exclusion, bulk confirmation requirement, and read-back reporting of each pair including unchanged ones. This goes well beyond the idempotentHint/readOnlyHint/destructiveHint annotations and paints a clear operational picture.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences front-load the purpose and example, then state constraints and reporting behavior. Every sentence carries necessary information with no filler or repetition, making it easy to parse quickly.

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

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

For a permission-assignment tool with no output schema, the description covers all critical aspects: valid input patterns, edge cases (exact match, GM exclusion), bulk handling, and the fact that results are reported back including unchanged pairs. An agent can confidently invoke it without missing key constraints.

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

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

With 100% schema coverage the baseline is 3, but the description adds meaningful semantic layers: it explains matching rules, the 'all friendly NPCs' and 'party' special values are contextualized with examples, and it clarifies that the operation is non-destructive and idempotent in effect. This is more than the schema alone provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Give players a permission level on actors', a specific verb and resource, and reinforces it with concrete examples (John as owner of Aragorn, party observer access to friendly NPCs). This clearly distinguishes it from sibling tools like list-actor-ownership and remove-actor-ownership, even without naming them.

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

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

The description provides clear context and invocation rules: exact matching (id or name, case-insensitive, never partial), Gamemasters are never changed, and confirmBulkOperation is required when affecting multiple actors/players. It lacks explicit alternatives or when-not-to-use guidance, but the context is strong enough for correct selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description goes beyond annotations by disclosing the 500-entry cap and the relative-path convention, which are operational details an agent needs to avoid surprises. It does not contradict any annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences, each contributing a distinct fact: scope, path format, and result cap. The verb and resource are front-loaded, and there is no filler or redundancy.

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

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

For a simple read-only list tool with no required parameters and a well-annotated safety profile, the description covers purpose, path semantics, source values, and the entry limit. There is no output schema, but 'List folders and files' adequately conveys the return. Minor omissions like sorting or error behavior are acceptable for this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful value with the illustrative relative path example 'worlds/<world>/maps' and clarifies the default source, giving practical semantics beyond the schema's terse parameter entries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List'), names the resource (Foundry's data storage and public files), and scopes to 'one folder'. It clearly distinguishes from sibling file tools like create-directory, upload-file, and copy-file by focusing on read-only listing and explicitly naming the two source options.

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

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

The description implies usage through its functional definition and gives context like relative paths and the 500-entry limit, but it never explicitly states when to use this tool versus alternatives. There is no exclusionary guidance or 'use X instead' routing, so an agent must infer applicability.

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

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

Annotations already cover read-only/idempotent/destructive hints, and the description adds useful behavioral context: moves follow Foundry's own defeated-combatant handling and the response reports round/turn before and after. This elaborates on side effects without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences carry purpose, behavior, and output expectations without repetition. The action list is front-loaded, and every sentence earns its place.

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

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

Despite no output schema, the description covers prerequisites (running encounter), behavior, and return info (round/turn before and after). It leaves tokenId vs combatantId and combatId defaulting to the schema, which is appropriate; minor error/validation behavior is not described.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates that set-turn targets a combatant, but the tokenId/combatantId semantics and combatId default are already fully described in the input schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description names a clear verb and resource: 'Move a running combat encounter', then exhaustively lists the five supported moves. This differentiates it from combat-query tools like list-combats/get-combat and from start/end-combat siblings.

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

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

It implies the tool applies to running encounters and that movement follows Foundry's own rules, but it never explicitly says when to choose it over sibling combat tools or when not to use it. No alternative tools or exclusions are named.

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

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

Annotations already mark it readOnly, idempotent, and non-destructive. The description adds valuable behavioral detail beyond that: open doors do not block, and it explains the fallback between Foundry's live canvas test and stored walls. This is exactly the kind of context a caller needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, tightly written, with the core action and result front-loaded. Every clause adds information: the purpose, the use cases, the wall list, the door exception, and the fallback behavior. No fluff.

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

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

For a read-only check with fully documented parameters despite no output schema, the description covers the key behavioral nuances: open doors, the canvas vs stored-wall fallback, and that a list of blocking walls is returned. It stops short of specifying the exact return shape, but this is a minor gap given the simple check semantics.

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

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

Schema description coverage is 100%, so the input schema already documents all four parameters including tokenId vs x/y and the type enum. The description reinforces the 'tokens or points' concept but does not add meaningful parameter-level detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Test whether walls block') and a precise resource ('the straight line between two tokens or points'), then enumerates the use cases (movement, sight, light, sound) and the additional output ('list the walls on it'). This clearly distinguishes it from related tools like find-path or measure-distance.

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

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

The description names the intended use cases ('for movement, sight, light or sound'), providing clear context for when to use it. However, it does not explicitly contrast this with sibling tools such as find-path or measure-distance, nor does it state when not to use it.

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

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

Annotations already mark this as non-read-only live playback control, but the description adds valuable behavior beyond them: it explicitly calls out error conditions (empty playlist or disabled mode), the one-time browser click requirement for audio, and the required permission. This goes well beyond what annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tightly packed sentences cover action, lookup semantics, error behavior, browser restrictions, and permissions without a single wasted word. The most important usage facts are front-loaded before the edge-case details.

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

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

For a three-parameter tool with no output schema, this description is unusually complete: it explains the synchronous playback effect, identifier resolution, failure cases, browser autoplay limitation, and authorization requirement. An agent has enough context to call it correctly without additional investigation.

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

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

Even though the schema has full descriptions for all three parameters, the tool description enriches them significantly: it explains exact name matching with case insensitivity when unique, forbids partial-name matches, and clarifies that 'sound' is required for track-specific commands. This materially improves parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource scope: 'Play or stop a playlist or one of its tracks, or switch its mode'. It also clarifies the mechanism ('through Foundry's own playback') and clearly distinguishes this from management or scene-music siblings by focusing on live, synced playback control.

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

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

The description gives clear context for when to use the tool: whenever you want Foundry's playback controls to affect all connected browsers. It does not explicitly name alternatives or exclusion cases, but the synced-playback framing and command semantics make the intended usage clear without being misleading.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds important context: the original file is preserved; actually, it says 'The original stays: Foundry cannot delete files.' It also clarifies the write switch requirement and the dryRun behavior (needs no write permission, implying the actual copy does). However, it does not explicitly state that the operation is destructive (overwrites) or that it is idempotent, but the annotations cover those.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured. It front-loads the core action and constraints, then provides a practical moving workflow, all in a few sentences with no wasted words. It efficiently packs essential information.

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

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

Given that there is no output schema, the description does not explain return values, but that is acceptable for a copy operation. It covers key prerequisites (existing folder, write switch), constraints (size limit, no deletion), and the moving workflow. It does not mention the overwrite behavior in detail, but the schema covers that. Overall, it is fairly complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description does not add significant detail beyond the schema, but it clarifies the 'to' folder must exist and the 'name' default. The description reinforces the dryRun purpose but adds little new meaning, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('Copy'), a resource ('a file inside Foundry's data storage'), and a destination ('existing folder'), with an explicit size limit. It distinguishes itself from file-moving alternatives by noting it cannot delete files, but does not directly name a sibling tool for copying (though file movement tools are implied).

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

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

The description provides explicit direction on when to use this tool versus moving files: it states the tool cannot delete files and outlines a multi-step procedure (find-file-references, copy-file, world-rewrite-paths, find-missing-files) for moving. It also mentions the write switch requirement, but does not explicitly say when NOT to use it (e.g., if only moving is needed).

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

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

Annotations only indicate readOnlyHint=false, destructiveHint=false, offering no safety or behavioral detail. The description compensates fully by disclosing limits (10 copies, maxActorsPerRequest), the link behavior (keeps a link, never its id), image handling (remote token image dropped), preflight checks (everything that could refuse is checked), and response content (lists actors, tokens, and problems). This is rich, non-obvious behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficient and front-loaded, starting with the core action before moving to prerequisites, constraints, and behaviors. It contains no tautology or filler; every sentence adds a distinct piece of information. It is slightly longer than strictly necessary, but the density justifies the length, 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.

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

The tool has 6 parameters, nested objects, and no output schema, making it relatively complex. The description covers the preflight checks, limits, and a summary of the response format ('lists every actor with its real name, the placed tokens and every problem'). It doesn't detail the exact response structure, but given no output schema, this is a reasonable level of completeness. It could mention possible error types more explicitly, but the overall context is well covered.

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

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

Schema description coverage is 100%, so every parameter already has a clear description in the schema. The description adds minimal extra parameter-specific meaning; it reiterates the limit and mentions the folder, but the schema already covers quantity semantics and placement options. Consequently, the description meets the baseline of 3 for high schema coverage without adding substantial new parameter insight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Copy'), a precise resource ('one actor entry of a compendium'), and the target ('into the world, into the folder Foundry MCP Creatures'). It also mentions optional token placement, which clearly distinguishes it from sibling tools like dnd5e-add-features-from-compendium that copy features, not actors. This leaves no ambiguity about the tool's purpose.

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

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

The description explicitly instructs users to find packId and itemId with search-compendium first, which is a clear prerequisite. It also defines limits (at most 10 copies, maxActorsPerRequest) and explains when placement occurs (optionally with addToScene). It doesn't explicitly name alternative tools to exclude, but the clear scope and prerequisite offer solid usage guidance.

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

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

The description goes well beyond the sparse annotations by disclosing many behavioral traits: status toggles cycle through four states and persist, figures/current part/lock markers react to saved status, parts lock until predecessors are completed/skipped, journal is GM-only, folder is auto-created if missing, and text follows the GM's client language. These details add substantial context beyond readOnlyHint and destructiveHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is information-dense and front-loaded with the core purpose. Each of its five sentences contributes distinct value: contents, toggle behavior, locking rules, folder/visibility, and localization. There is no filler or repetition of schema details.

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

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

Given the tool's complexity and the absence of an output schema, the description is largely complete: it explains the journal's contents, dynamic status behavior, locking, permissions, folder creation, and localization. A minor gap is that it never states what the function returns (e.g., journal ID), but for calling and creating the dashboard, the essential context is present.

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

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

The input schema has 100% description coverage for all six parameters, so the baseline is 3. The tool description adds narrative context about how the journal uses campaign data (e.g., location, quest giver, parts), but it does not add parameter-specific meaning or constraints beyond what the schema already states. It does not need to repeat the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Create a journal that gives an overview of a campaign.' It then enumerates the journal's contents (progress, current part, location, quest giver, per-part levels/description/status toggles), which clearly distinguishes it from sibling tools like create-quest-journal. The resource and behavior are unambiguous.

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

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

The description makes the tool's context clear: it is for creating a campaign-wide overview journal with status tracking, lock progression, and GM-only visibility. It does not explicitly name alternatives or state when not to use it, but the campaign focus and journal structure implicitly separate it from quest journal and combat tools.

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

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

The description attributes a key non-schema detail: 'One bad entry creates nothing' (atomicity), which prevents partial writes. It also adds a permission gate and the 200-element batch limit. Annotations only carry false hints, so this add value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The text is dense but organized as a list separated by semicolons, with the most useful batch/permission facts at the end. All content is functional and none is redundant with the schema.

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

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

For a complex multi-type batch-creation tool, this is enough: per-type structures, atomicity, permission requirement, and size cap. Lack of output details is minor because no output schema exists and the rule is not to duplicate output definitions; still missing are return-value or confirmation semantics.

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

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

The description substantially enriches the schema. For each elementType it gives precise field layouts (e.g., Wall: c [x0,y0,x1,y1], door state options, light/sound fields, tile texture src, drawing shape). This goes far beyond the schema's generic 'Foundry fields' placeholder.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: create canvas elements, up to 200, on a scene, and lists the six element types. It clearly stands apart from sibling update-canvas-elements, delete-canvas-elements, and list-canvas-elements.

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

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

It gives batch size, one-type-per-call, and permission prerequisites ('Needs the level change for scenes'), plus an atomic failure mode. It does not explicitly spell out 'use update for existing elements' but the naming makes it obvious.

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

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

Annotations already indicate non-read-only, non-idempotent, and non-destructive behavior, so the description's burden is lower. It adds useful behavioral details: cards preserve order when read back, and empty hand or pile is permitted. This goes beyond the schema's property descriptions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no wasted words. The core purpose is front-loaded, and the ordering guarantee is placed at the end without excess detail. Every sentence earns its place.

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

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

For a creation tool with fully documented parameters and clear annotations, the description covers the essential behavioral nuance (ordering, empty stacks). It does not describe return values, but without an output schema that is not a significant gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context about card structure and ordering, but it does not add meaning for name, type, folderPath, backImg, or description beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('Create a card deck') and resource, and immediately clarifies that it can also produce an empty hand or pile. This distinguishes it from sibling stack tools like get-card-stack or delete-card-stack without requiring the agent to inspect each schema.

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

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

The phrase 'or an empty hand or pile to deal into' explains when this tool is appropriate for creating non-deck stack types. It does not explicitly name alternative tools for reading, shuffling, or deleting stacks, but the context signals are clear enough for an agent to select this tool.

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

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

Annotations declare readOnlyHint=false and idempotentHint false, so the mutation nature is already implicit in the annotations; the description adds valuable behavioral context. It explicitly states the encounter is not started automatically and that tokens are specified by id only, which goes beyond the schema and annotations. It doesn't mention permissions or failure cases, but the added context is meaningful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler. The main action and default behavior are front-loaded, followed by the key exclusion, and the token-specific constraint. Every sentence earns its place.

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

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

Given no output schema exists, the description covers the essential operational behavior well: creation, default scene, optional token list, and the start-combat separation. It doesn't hint at return value details, which the agent may need to later reference the created encounter, but the core invocation context is sufficiently complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description repeats the scene default and token id idea, but these are already in the sceneIdentifier and tokenIds schema descriptions. It adds no new parameter-level semantics beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: creates a combat encounter on a scene. It also clarifies scope with details like the active-scene default and optional token combatants, and distinguishes itself from start-combat in the next sentence. The description clearly separates creating an encounter from starting the encounter.

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

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

Explicitly states the main condition of use: creating a combat encounter on a scene, with the active scene as default. It names the key alternative alternative explicitly: "It does not start the encounter; start-combat does." The token handling note also gives practical guidance for how to provide tokens.

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

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

Annotations indicate this is a write operation (readOnlyHint: false). The description adds the crucial permission requirement ('create and change') and specifies that it creates a world compendium, providing useful behavioral context beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise, front-loaded sentences: action+example, parameter guidance, and permission requirement. Every sentence adds value with no redundant phrases.

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

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

For a simple 2-parameter creation tool with no output schema, the description covers the purpose, parameter usage, and a critical prerequisite. No additional information is needed for correct invocation.

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

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

Schema description coverage is 100% with both 'type' and 'label' fully explained. The description adds minimal extra value—only echoing the type choice and providing an example for label that is already in the schema. Baseline 3 is appropriate since the schema carries the semantic load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Create a new world compendium' with a concrete example ('archive a finished chapter'). It also specifies the parameter purpose ('Choose the document type it will hold'), making the tool's function unambiguous and distinct from sister tools like delete-compendium.

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

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

Provides a clear use case ('to archive a finished chapter of a campaign') and a prerequisite permission ('Needs the compendium permission on create and change'). It doesn't explicitly contrast with alternative compendium tools, but the example and action make the intended scenario evident.

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

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

Beyond the annotations, the description discloses meaningful behavior: missing parent folders are created, existing folders are left as-is, and write permission is required. The 'existing folder is left as it is' detail aligns with idempotentHint=true 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tightly written sentences, each carrying necessary information: the core action, parent-folder behavior, location constraints, idempotency, and permission requirement. No filler or redundancy.

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

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

For a simple two-parameter tool with no output schema, the description plus annotations cover purpose, path semantics, permissions, idempotency, and safety. An agent has enough to invoke it correctly without missing critical context.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds value by explaining that the path creates missing parent folders and that dryRun performs no write, though much of the parameter semantics already lives in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Create a folder in Foundry's data storage', with additional scoping such as creating missing parent folders. This clearly distinguishes it from sibling operations like folder-rename and folder-delete.

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

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

It provides clear usage context: creates missing parents, leaves existing folders untouched, and requires the write switch. Location restrictions are explicit ('Never inside modules, systems or another world'), though it does not explicitly name alternative tools for similar file operations.

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

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

Annotations are all false, so the description must carry the behavioral burden. It adds valuable context: the created document is read back from Foundry, certain fields (ids, ownership, _stats, module flags) cannot be set, and permission behavior matches specialized tools. It does not explicitly state that it writes to the world, but that is implied. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence serves a purpose: purpose, data shape, permission/constraints, dryRun advice, tool routing, and exclusions. It is front-loaded with the 'Generic fallback' label and proceeds logically. No wasted words for the amount of information conveyed.

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

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

For a generic creation tool with no output schema, this description is fairly complete: it covers what it does, how to use it, constraints, and what it returns (read back from Foundry). It could add a note on error handling or how to discover valid document types, but the pointer to describe-document-type mitigates that. Overall, an agent can confidently invoke it.

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

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

Schema coverage is 100%, so parameters are documented, but the description adds important semantics: how data should be structured (nested objects, 'as describe-document-type shows'), what parentUuid is for (with examples), and the restriction on fields like ids and _stats. This goes beyond the schema's bare descriptions, making it more actionable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('create one document') on a broad but well-defined resource ('any type in the world, or inside another document with parentUuid'). It clearly positions itself as a generic fallback, explicitly naming specialized siblings it should not replace. This distinguishes it from the many other creation tools like journal-create or create-scene.

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

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

The description provides explicit usage guidance: it says to prefer a list of specialized tools 'where they fit', and clarifies what is not handled here ('Chat messages are sent only with send-chat-message; settings, users and compendiums are not written here'). It also recommends using dryRun first, which is a specific precondition. This gives an agent clear decision criteria.

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

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

The description richly discloses side effects and behaviors beyond the sparse annotations: the hero lands in 'Foundry MCP Actors', has no token in a scene, remains linked to its archetype, duplicate names are refused, and addToWorld false prevents any write. This far exceeds the annotation's minimal safety hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences deliver scope, destination, linking behavior, duplicate handling, and the dry-run flag with no filler. The most important constraints are front-loaded, and every clause earns its place.

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

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

For a tool with a nested customization object and no output schema, the description covers the critical context: source, destination, write behavior, uniqueness rule, and no-token outcome. The only small gap is not specifying the exact return shape, though 'read back' hints at the response.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description adds a useful pointer that archetypePackId is shown by list-dsa5-archetypes and restates the addToWorld behavior, but most parameter-level meaning is already present in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: 'Create one hero as a copy of an archetype', and identifies the source explicitly via 'list-dsa5-archetypes'. It also distinguishes itself from the related read-only sibling by describing the actual creation behavior, making the tool's role unambiguous.

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

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

The '[DSA5 only]' prefix gives a clear system-scoping condition, and the reference to list-dsa5-archetypes as the required source indicates when this tool is appropriate. It does not explicitly name alternatives or exclusion conditions, but the context is strong enough for an agent to select it correctly.

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

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

Annotations only carry all-false hints, providing no safety or side-effect information. The description adds important behavioral context: 'Creating runs nothing' clarifies that creation has no immediate execution side effect, and it warns that script macros can do anything a Gamemaster can once run. These details go beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no filler. The opening sentence 'Create a macro' front-loads the core action, followed by the two macro type explanations and a key behavioral note. Every sentence earns its place.

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

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

For a simple create tool with no output schema, the description covers the essential behavior (creating a macro without running it), differentiates macro types, and implies the risk of script macros. It does not mention return values or prerequisites like permissions, but those are not critical for an agent to invoke the tool correctly. The core usage context is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by defining the 'type' enum values (chat vs. script) with concrete examples like '/roll 1d20' and explaining what each type holds. It does not add detail for name, img, or folderPath, but the schema already covers those adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Create a macro.' It further distinguishes itself from sibling tools by explaining the two macro types and explicitly adding 'Creating runs nothing,' which contrasts with execute-macro. This makes the tool's purpose unambiguous and separates it from related operations like list-macros and execute-macro.

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

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

Usage is implied: to create a macro, use this tool. The description does not explicitly name alternatives like execute-macro or list-macros, nor does it state when not to use it. The explanation of chat vs. script macros offers context but no direct routing to sibling tools, so guidance remains implicit.

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

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

The annotations only carry negative hints (readOnlyHint=false, etc.), so the description carries the full behavioral load. It does well: it discloses GM-only visibility, HTML escaping of given values, that additionalPages are stored as sent, and that the response lists page ids and lengths, not HTML, which is essential because there is no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and every sentence conveys a meaningful behavior, with no padding. It is, however, long and sentence-like; a structured list or clearer breaks would improve scannability, but not at the cost of necessity.

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

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

Despite having no output schema and 10 parameters, the description provides a complete mental model: what the journal contains, how optional params affect it, folder behavior, and the response format. This is enough for an agent to call the tool correctly without hunting for additional guidance.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes well beyond the schema. It explains how parameters are used: values are escaped, the questType drives fixed objectives, folderName governs folder placement, and additionalPages content is stored as sent—all crucial for correct invocation or interpretation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Create'), a specific resource ('a quest journal'), and a distinguishing scope ('visible to Gamemasters only'). It also enumerates the journal's internal content, which differentiates it from generic siblings like journal-create and update-quest-journal.

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

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

The description makes it clear when this tool is appropriate: when you need to create a quest journal with the canonical first page, optional folder handling, and additional pages. It does not explicitly call out alternatives or say when not to use this tool versus update-quest-journal or journal-create, but the context is clear enough.

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

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

Beyond the flat annotations, the description discloses significant runtime behavior: omitted ranges are assigned consecutively, the dice formula is derived from the highest range, overlapping ranges are refused, and gaps or unrollable numbers produce warnings. This gives an agent a reliable model of what will happen on valid and invalid input.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two focused sentences: the first states the core action and input, the second packs the default range assignment, dice derivation, and validation behavior. Nothing is redundant or extraneous, and the key action is front-loaded.

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

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

For a creation tool with five parameters, the description plus a fully covering schema gives an agent the essential behavior needed to call it correctly. It stops short of complete by not stating what the successful response contains, since there is no output schema, and does not mention any permission prerequisite.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning to `formula` and `results.range` by explaining derivation and validation, e.g., a six-entry table becomes 1d6 and overlapping ranges are refused. It does not add semantically to `weight` or `folderPath`, but those are already documented in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with the specific action 'Create' and the specific resource 'a roll table', and narrows the input to 'a list of text results'. This tells an agent exactly what the tool does and distinguishes it from roll-table siblings like draw-roll-table, get-roll-table, and update-roll-table.

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

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

The description implies this tool is for creating new roll tables, but it does not state when to prefer it over update-roll-table, delete-roll-table, or other alternatives. No when-not-to-use guidance or explicit alternative routing is provided.

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

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

Annotations indicate readOnlyHint=false, so the description correctly implies mutation. It adds behavioral context beyond annotations by detailing side effects: templateName copies settings but not map contents or id, folderPath creates missing folders, and journalIdentifier links a journal. However, it doesn't disclose potential side effects like what happens to existing scenes or whether the scene is activated by default (though 'activate' parameter exists). With no output schema, some return behavior is opaque, but the description covers the main behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded: the first sentence states the core purpose, followed by short, specific behavior notes for key parameters. Every sentence adds value, covering revealing details about templateName, folderPath, and journalIdentifier without unnecessary verbosity. It's well-structured for an agent to parse quickly.

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

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

Given the tool's complexity (13 parameters, no output schema, no enums), the description covers many important defaults and behaviors (grid measuring, template copying, folder creation, journal linking). It lacks explicit mention of the return value or confirmation of creation, but the schema and annotations provide basic context. For a complex creation tool, it's nearly complete, with minor gaps around error handling or what happens on invalid paths.

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

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

The input schema has 100% description coverage for all 13 parameters, each with a clear description. The tool description adds extra meaning by explaining how parameters interact: width/height default to measured values, templateName copies settings but not map/id, folderPath creates missing folders, and journalIdentifier links a journal. This goes beyond the schema's individual descriptions, but the schema already provides strong parameter semantics, so this isn't a full compensation need.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states that it creates a scene from an image or video in the data directory, with a clear verb and resource. It also explains key behaviors like grid fitting and template copying, which distinguishes it from other scene-related tools (e.g., update-scene, delete-scene). However, it does not explicitly name any sibling tool for contrast, so it doesn't fully differentiate from siblings.

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

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

The description provides clear context on when to use this tool—creating a new scene from media files. It implies usage for battlemaps or location pictures and explains how parameters like templateName and folderPath work. It does not explicitly state when NOT to use it or name alternative tools (e.g., for updating scenes), but the purpose is clear enough for an agent to select it correctly.

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

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

With all annotations false and no other safety signals, the description carries the burden of behavioral disclosure. It reveals the core behavior—creating a clickable note that opens a journal/page—but does not mention reversibility, uniqueness, overlap with existing notes, or any side effects beyond placement. This is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler. The first sentence states the action and outcome; the second gives a motivating use case. Information is front-loaded and every word earns its place.

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

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

The tool has 8 parameters, no output schema, and empty annotations. The description is brief and does not cover prerequisites (e.g., scene and journal must exist), likely failure modes, or how to remove or modify the note. It is sufficient for a simple creation action but leaves room for more guidance given the complexity.

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

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

Schema description coverage is 100%, so the description does not need to explain parameter syntax. It adds minimal extra meaning beyond the schema—only implying that coordinates are in scene pixels and the note becomes clickable. This matches the baseline for full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Place a note on a scene at pixel coordinates' and describes the interactive behavior ('opens a journal, or one page of it, when clicked'). It clearly differentiates from sibling tools like journal-create or create-canvas-elements by tying the action to scene coordinates and click behavior.

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

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

The description provides a concrete use case ('make the places on a town map clickable'), which gives clear context for when to use the tool. It does not explicitly name alternatives or exclusions, but the example strongly implies the intended scenario.

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

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

Annotations provide no hints (all false), so the description carries the full burden. It discloses a key atomicity behavior (refusal before moving anything when insufficient cards) and a permission requirement (write switch), which is valuable. However, it does not describe whether the source stack is modified, what happens to the cards after dealing, or the return value, leaving some behavioral ambiguity. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each adding distinct value: the core action, the failure mode, and the permission prerequisite. The main purpose is front-loaded, and there is zero redundancy or filler. Highly concise and well-structured.

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

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

For a 5-parameter tool with multiple siblings, the description covers the essential action and one failure condition, but omits details like whether the source stack is depleted, the default behavior (already in schema for 'how' and 'number'), and the return value (no output schema). The schema covers parameters, but the description could be more complete regarding state changes and expected results for an agent deciding to invoke it.

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

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

Schema coverage is 100% with each parameter clearly described (e.g., 'how' enum, 'number' default, 'chatNotification' flag). The description adds no additional per-parameter meaning, which is acceptable given the schema's thoroughness. The baseline of 3 applies as the schema does the heavy lifting and the description does not compensate with extra context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the specific verb 'deal' with a resource ('cards from one stack to each of several hands or piles') and a key constraint ('the same number of cards'), clearly distinguishing it from sibling operations like pass-cards or draw-cards. The added failure condition ('Refused before anything moves when too few cards are left') further clarifies the intended behavior.

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

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

The description provides useful context (dealing evenly to multiple stacks) and a prerequisite (write switch), but it does not explicitly compare to alternative card tools such as draw-cards or pass-cards, nor does it state when to prefer this over them. The context is clear but lacks explicit when-not guidance for a tool surrounded by many card-related siblings.

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

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

Annotations already carry destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is known. The description adds beyond annotations: the pre-validation behavior ('Every id is checked first'), the auth requirement being off by default, and that dryRun reports both what would be deleted and whether it is allowed. This meaningfully expands on the structured data 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences in total, each earning its place: the core action with constraints, the pre-check behavior, and the permission/dry-run caveat. Slightly denser than ideal (the last sentence packs two ideas into one semicolon-joined clause) but still efficient and front-loaded with the most important information.

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

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

For a destructive mutation tool with no output schema, this description covers the essential decision factors: scope limits, permission prerequisites, and the dry-run safety option, while the schema documents all parameters. Minor gaps remain (behavior on partially invalid id lists, all-or-nothing vs partial deletion), but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so every parameter (ids, dryRun, elementType, sceneIdentifier) already has meaningful text in the schema. The description reinforces some of that (one type per call, dryRun usage, id limits) but adds only marginal extra semantics beyond what the schema states; the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Delete up to 200 elements of one type from a scene by id') and adds the key constraints (max 200, single element type). This clearly distinguishes it from siblings like create-canvas-elements, update-canvas-elements, and list-canvas-elements, and the elementType enum confirms tokens are out of scope (handled by delete-tokens).

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

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

The description provides clear usage context: the 200-element and single-type constraint, the prerequisite permission level ('create, change and delete' for scenes, off by default), and the dryRun preview capability. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to decide when to invoke it.

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

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

Annotations already mark destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds the useful behavioral fact that deletion will be refused until card stacks get their own permission level, which is not captured by any annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero filler: the purpose is front-loaded, and the second sentence adds an important caveat without repetitive or extraneous explanation.

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

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

For a one-parameter destructive tool with no output schema, this description covers the action, the identifier, and a key failure mode. It doesn't detail what happens to associated cards after deletion, but the destructiveHint annotation supplies the needed safety framing.

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

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

Schema coverage is 100% and the schema already describes stackId as 'Id of the stack'. The description adds no additional detail about format, constraints, or valid values, so it meets the baseline for full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with 'Delete a card stack by id', a specific verb and resource, and clearly differentiates deletion from sibling reset-card-stack, shuffle-card-stack, and other card-stack operations.

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

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

The first sentence states the usage action and target precisely. The second adds a concrete precondition (deleting is refused until grant stack permission level), but it doesn't explicitly call out alternatives such as reset-card-stack.

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

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

Annotations already supply destructiveHint=true and idempotentHint, and the description adds meaningful behavioral context beyond them: it narrows deletion to messages written by the Gamemaster and flags a permission prerequisite that causes refusal. This helps an agent predict refusal behavior without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences deliver the action, scope, key parameter, and a permission gate with no filler. The most important purpose information is front-loaded, and the permission note earns its place by explaining a likely refusal scenario.

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

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

For a single-required-parameter delete operation with destructive annotations, the description is largely complete: what to delete, by what identifier, under what permission condition. There is no output schema, and it does not mention the response shape or not-found behavior, but those are minor for a simple delete operation.

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

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

Schema description coverage is 100%: messageId is already documented as 'Id of the message.' The description only reiterates the id requirement via 'by id,' adding no meaningful semantics beyond the schema. This matches the baseline for fully covered parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action ('Delete a chat message'), identifies the exact resource ('written by the Gamemaster the bridge runs as'), and explicitly requires an id. This cleanly separates it from siblings like update-chat-message, send-chat-message, and list-chat-messages.

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

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

The deletion context is clear: the tool is used to delete a specific chat message by id. It also gives a usage-relevant condition by stating that the tool is 'Refused until the permission settings have a level for chat messages that allows deleting.' It does not explicitly name alternatives or when not to use it, but the purpose is unambiguous given siblings.

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

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

Annotations already include destructiveHint and idempotentHint, but the description goes further: it discloses irreversibility, the non-default/off-by-default permission, and the exact-label safety guard. These are non-obvious behavioral constraints not captured by annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, front-loaded with the core destructive purpose, and contains no padding. It slightly duplicates the schema's confirmLabel description, but the repetition serves to emphasize a critical safety prerequisite.

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

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

For a destructive tool with no output schema, the description covers all necessary calling context: what is deleted, irreversibility, permission requirements, the label safeguard, and what kinds of compendiums are excluded. An agent has everything needed to invoke it correctly and avoid dangerous mistakes.

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

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

The input schema describes both parameters with 100% coverage, so the baseline is 3. The description adds context about packId referring to a whole world compendium and confirms the label requirement, but mostly reinforces the schema rather than providing new semantic information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Remove a world compendium and everything in it', specifying the verb and the exact resource. It also distinguishes the tool from siblings like delete-compendium-entries by limiting scope to whole world compendiums and excluding module/system packs.

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

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

The description gives clear boundaries: only world compendiums are eligible, and module/system compendiums cannot be removed. It also informs the agent about the permission prerequisite and the required confirmLabel. It does not name a sibling tool like delete-compendium-entries explicitly, which costs a point.

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

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

The description goes well beyond the annotations. It discloses that only explicitly named entries are removed, that names are matched exactly and never as a part, that ambiguous names are reported rather than guessed, that dryRun changes nothing, and that unlockIfNeeded lifts a lock only for the one operation and sets it again. These are behavioral traits not visible in the annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded. The first sentence states the core action and selection modes. The second sentence gives the critical safety instruction (dryRun first). Every sentence adds distinct information: no bulk deletion, exact matching, ambiguity handling, confirmLabel condition, and permission requirement. No filler or repetition.

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

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

For a destructive tool with 6 parameters and no output schema, the description covers the essential context: what gets removed, how selection works, the safety workflow (dryRun), the edge case (all entries require confirmLabel), the permission requirement, and the lock behavior. An agent has enough to invoke this tool correctly and safely.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the relationship between ids and names (exact spelling, ambiguity handling), the purpose of dryRun ('reports exactly what would go'), and the condition for confirmLabel ('selection covers every entry'). It doesn't add much about unlockIfNeeded beyond the schema, but the overall added value justifies a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Remove'), a specific resource ('named entries from a compendium'), and the two selection modes ('by id or by exact name'). It also distinguishes itself from a generic delete by explicitly noting there is 'deliberately no empty this pack', which separates it from sibling tools like delete-compendium and delete-document.

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

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

The description gives explicit usage guidance: 'Always run with dryRun first' and explains what dryRun reports. It also states when confirmLabel is required ('If the selection covers every entry') and what permission is needed ('compendium permission on create, change and delete'). This is clear when-to-use and how-to-use guidance.

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

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

Beyond the annotations (destructiveHint=true), the description adds substantial behavioral context: required permission levels, rules for embedded documents, explicit refusal cases, and dryRun behavior including embedded documents. This is exactly the kind of context annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence carries operational value: identification modes, permissions, refusals, dryRun, and alternatives. It is front-loaded with the core purpose and then lists exclusions, though the dense refusal list could be slightly better structured.

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

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

For a complex destructive tool with 5 parameters and no output schema, the description covers identification, permissions, failure cases, dryRun behavior, and routing to siblings. Nothing essential for an agent to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a small amount of meaning by explaining the uuid-or-documentType+id identification modes, but it does not substantially enrich the parameter semantics beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Generic fallback: delete one document of any type', giving a specific verb, resource, and scope. It clearly distinguishes this tool from the many specialized deletion tools by labeling it a fallback and specifying the two identification methods.

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

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

The description explicitly lists preferred alternatives ('Prefer journal-delete, journal-delete-page, delete-scene, manage-actors, delete-playlist, delete-roll-table and delete-tokens where they fit') and states conditions under which deletion is refused. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. It adds valuable context beyond annotations: the refusal behavior when linked to scenes, the fact that it names those scenes, and the permission requirement. This is meaningful behavioral disclosure that helps the agent anticipate failure modes. Minor gap: it doesn't state whether deletion is permanent or reversible, but the destructiveHint covers the risk profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: what it does, when it refuses, and what permission is required. The most important operational constraints are front-loaded. No fluff or repetition of the title.

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

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

For a single-parameter destructive tool with no output schema, the description covers the essential context: the action, the refusal condition, and the permission prerequisite. It doesn't describe the return value, but with no output schema and a simple delete operation, that's a minor gap. The description is complete enough for an agent to invoke it correctly and anticipate failures.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter (playlistId). The description adds the context that the id is the playlist's id and that deletion is by id, but doesn't add new semantic detail beyond the schema. Baseline 3 is appropriate when the schema fully covers parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Delete'), a resource ('a playlist'), and the identifier used ('by its id'). It also distinguishes itself from sibling tools like list-playlists, manage-playlists, and control-playlist by focusing on deletion. The title and description align, and the behavior is unambiguous.

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

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

The description explicitly states when deletion is refused (while the playlist is linked to a scene) and names the scenes, which is a clear exclusion condition. It also states a prerequisite (playlist permission must be set to full), giving the agent actionable guidance on when to use this tool vs alternatives like manage-playlists or control-playlist.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds the permission requirement, which is useful behavioral context. It does not describe side effects, return value, or error behavior, but the low bar set by the annotations makes this acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exactly two short sentences with no filler. The core operation is front-loaded, and the permission note is the only additional detail, making it efficient and easy to parse.

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

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

For a single-parameter destructive tool with annotations covering safety and idempotency, the description plus schema is nearly sufficient. The permission note adds important operational context. A minor gap is not clarifying that deletion is permanent, but the destructiveHint annotation already signals this.

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

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

The schema description fully documents tableId as 'Id of the table to delete'. The description only re-states this as 'by its id', adding no additional semantic detail beyond what the schema already provides. Baseline 3 is appropriate given 100% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Delete'), a specific resource ('roll table'), and the identifying mechanism ('by its id'). This clearly distinguishes the tool from related roll-table siblings like get-roll-table, update-roll-table, reset-roll-table, or draw-roll-table.

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

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

The description clearly implies when to use the tool: when a roll table needs to be deleted. It also provides a meaningful prerequisite by requiring full roll table permission. However, it does not explicitly mention alternatives or give a when-not-to-use scenario, leaving usage guidance somewhat implicit.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, so the description doesn't need to repeat those. However, it adds crucial behavioral context: the tool permanently deletes and cannot target the active scene, and it states the required permission level. This goes beyond annotations and is valuable for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, three sentences with no fluff. It front-loads the primary action (delete for good) and then provides the critical constraints and permission requirement. Every sentence adds essential information.

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

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

The description is complete for a deletion tool with one parameter. It covers the action, the target, the safety caveat, and permission requirement. It doesn't explain the return value, but since there is no output schema and deletion typically returns a simple success, this is not a major gap. The annotations provide safety hints, so the description is sufficiently complete.

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

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

The schema provides 100% coverage for the single parameter 'sceneId' with a basic description. The tool description adds significant semantic meaning by explaining that the id must be exact and that the active scene is never affected, which clarifies how the parameter is used and its constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (delete), the resource (scene), and critical scoping (by id only, never the active scene). It distinguishes from sibling tools like 'delete-canvas-elements' and 'delete-document' by specifying the resource and the id-based targeting.

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

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

The description provides clear context on when to use (deleting a scene permanently) and includes a critical exclusion (never delete active scene, activate another first). It does not explicitly mention alternatives, but the sibling list includes update-scene and restore-scene, so it implicitly suggests alternatives for non-destructive actions.

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

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

Goes well beyond the annotations by disclosing that actors remain in the actor directory, unlinked tokens lose their own values, the operation is atomic when an id is missing, and the response lists deleted and failed tokens. This adds meaningful behavioral context beyond the destructiveHint and idempotentHint annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four dense sentences, each earning its place: the core action, the side effect on actors, the atomic failure behavior, and the response contents. The most important information is front-loaded in the first sentence.

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

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

With only two parameters and no output schema, the description fully covers what an agent needs: scene targeting, id-only restriction, side effects, failure atomicity, and response contents. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic value by clarifying that tokenIds must be ids only, that sceneIdentifier can target a scene by id or name, and that the active scene is used when omitted. This enriches the parameter meaning beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Remove tokens from the active scene (or the scene in sceneIdentifier), by their ids only.' It clearly distinguishes this from sibling tools like move-token or update-token by emphasizing id-based removal and scene scope.

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

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

Provides clear context for when to use it: when removing tokens from a scene by id, with an optional sceneIdentifier for targeting a non-active scene. It does not explicitly name alternatives, but the scope and conditions are unambiguous enough for an agent to select it correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds useful context beyond annotations by enumerating what the tool returns: fields, subtypes, system fields, containment, permission requirements, generic-access behavior, and specialized tools.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is only two sentences and front-loads the core action ('List... or describe one'). The first sentence is a long, dense enumeration of outputs, but it is information-rich and not padded with unnecessary filler.

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

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

For a read-only introspection tool with no output schema, the description fully enumerates what the agent can expect to learn: fields, subtypes, system fields, containment, permission levels, generic-access behavior, and specialized tools. It also tells the agent when to invoke it, making the call context complete.

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

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

The input schema already provides 100% parameter descriptions for depth, subtype, and documentType. The description adds little new parameter-level meaning beyond restating that document types can be listed or described, so the schema carries the semantic burden and the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as a read-only introspection tool for Foundry document types, using verbs like 'List the document types' and 'describe one' with a detailed resource scope. It distinguishes itself from document-instance tools like list-documents/get-document by focusing on Foundry's data model and type metadata.

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

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

The description provides explicit guidance on when to call the tool: 'Call it before creating or changing a type through generic access for the first time.' It gives clear usage context but does not explicitly state exclusions or name alternative tools for non-type document operations.

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

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

Annotations only declare not-read-only/not-idempotent/not-destructive; the description adds rich behavior far beyond that: duplicate item names are refused case-insensitively, actor lookup is by id/exact name/token id and never partial, ignored parameters are named in the answer, everything written is read back, actors with class items are refused for spellcasting, auras create no lasting effect, and unknown keys are stored with a warning. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but every clause earns its place given 33 parameters and 7 sub-modes. Front-loaded with the scoping sentence and '[D&D 5e only]' tag; the bullets are consistent and scannable (definition + minimum parameters per type); the closing paragraph groups the global rules (refusal, lookup, read-back, ordering) efficiently.

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

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

No output schema exists, but 'Everything written is read back' sets return expectations, and the description covers every mode's inputs, rejection conditions, defaults, and edge cases (2024 paladin/ranger slots at level 1, warlock pact magic, natural weapons). For a tool this complex, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% with per-parameter 'Used by' descriptions, so the baseline is 3. The description adds cross-parameter structure the flat schema cannot express: minimal required sets per featureType, 'The first damage part is the weapon damage', 'rangeFt when ranged', and default-derivation rules (abilityModifier fallback, compendiumPacks default). That pushes it above the schema-only baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Add one thing to an existing dnd5e NPC or character') and then enumerates seven distinct feature types with concrete definitions (passive, save, attack, attack-with-save, aura, spellcasting, spells). The 'one thing' phrasing and per-type breakdown distinguish it from siblings like dnd5e-add-features-from-compendium and dnd5e-create-npc.

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

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

Extensive internal routing guidance: each featureType gets a definition and a minimal required parameter set, plus global rules like 'Run spellcasting before spells' and the actor-lookup constraints. However, there is no explicit when-not-to-use guidance against the near-sibling dnd5e-add-features-from-compendium (bulk addition from compendium), so tool-level alternative routing is left to inference.

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

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

The description discloses substantial behavior beyond the minimal annotations: whole-name case-insensitive matching, first-compendium-wins resolution, duplicate-entry reporting, skipping features the actor already has, preserving entry links rather than ids, and the summary of added/skipped/not-found/failed names. It also warns that 2024 class features cannot be fetched individually, which is valuable operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but not padded; the first sentence front-loads purpose and examples, and every subsequent clause adds a relevant behavioral rule. It is slightly long as a single paragraph, and the final routing sentence is compressed, which keeps it from being perfectly structured.

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

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

For a tool with no output schema and nontrivial source-resolution logic, the description covers the core usage, defaults, limitations, duplicate handling, and result categories. An agent has enough information to decide when to call it and what to expect from the actor and the response.

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

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

The schema already documents all three parameters with 100% coverage, so the description does not need to repeat basic parameter meaning. It adds useful extras such as duplicate-name handling and the 2024 class-feature limitation for compendiumPacks. It adds little for actorIdentifier beyond the schema, so a 4 rather than 5 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: copying class and monster features by English name from item compendiums onto an actor, with concrete examples like 'Pack Tactics', 'Multiattack', and 'Action Surge'. It also scopes the tool to D&D 5e and distinguishes it from dnd5e-add-feature by directing spell and homebrew feature use cases to that sibling.

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

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

It states exactly when to use this tool, including the D&D 5e scope and the feature-copying use case, and explicitly names dnd5e-add-feature with featureType values for spells and homebrew features as the alternative. It also explains what happens when compendiumPacks is omitted, giving the agent clear selection criteria.

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

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

Annotations are all false (not read-only, not idempotent, not destructive), so the description carries the burden of explaining side effects. It does so richly: values are read back with warnings, proficiency bonus and XP are derived by dnd5e rather than stored, duplicate names and illegal CRs are refused, and output lands in a specific folder. This tells the agent what to expect after invocation beyond the annotation flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The single paragraph is dense but every sentence earns its place: scope, field inventory, folder, validation rules, derivation behavior, read-back/warnings, and the pointer to dnd5e-add-feature. It is slightly long for one paragraph and could be bulleted, but there is no wasted text.

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

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

For a 34-parameter tool with no output schema, the description covers folder placement, validation refusals, derived values, warning behavior, and the next tool to chain, which is substantial. It does not describe the exact return shape or all edge cases, but the schema's rich properties fill most remaining gaps.

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

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

Schema description coverage is 100%, so the baseline is 3; the tool description itself adds no per-parameter meaning beyond the schema's rich descriptions (CR format rules, 'swarm' handling, unknown-key warnings, etc.). The schema parameters are well documented such that no compensation from the main description is required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Create one NPC with a complete stat block and no items' and enumerates the included fields (type, size, CR, abilities, etc.). It also distinguishes from the sibling dnd5e-add-feature, which is the later step for attacks/features/spells, and scopes to D&D 5e. The target folder is named, removing ambiguity about where the actor lands.

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

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

Scopes to '[D&D 5e only]' and describes the creation flow, including that attacks/features/spells should be added afterwards with dnd5e-add-feature, which is an explicit alternative for continuing after this tool. It does not discuss competing creation tools like create-actor-from-compendium or manage-actors, so exclusions are only partial.

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

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

The description adds meaningful behavioral context beyond the annotations: it refuses before any cards move when too few remain, performs a post-move lookup, and requires the write switch. Since the annotations only provide false hints, these disclosures carry important safety and operational information.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded: action first, then failure behavior, verification step, and permission requirement. The sentence 'Every card is looked up afterwards' is somewhat vague, but the overall size and structure are appropriate with no wasted words.

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

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

The description covers the core operation, a critical failure condition, and an auth prerequisite, which supports invocation. However, with no output schema, it does not clarify what the caller should expect afterward, and it does not position this tool among the similar card-related siblings.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description adds a little context around from/to being stacks and connects the refusal behavior to card count, but it does not substantially extend or clarify any specific parameter beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Draw cards') and resource ('from one stack ... into another'), with concrete typical examples: a deck into a hand or pile. It does not explicitly differentiate from sibling tools like deal-cards or pass-cards, so it stops short of full sibling-level clarity.

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

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

There is no guidance on when to use this tool versus alternatives such as deal-cards, pass-cards, or other card-stack operations. The 'usually a deck' and 'usually a hand or pile' phrasing implies a typical case but does not state exclusions, alternatives, or when another sibling would be more appropriate.

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

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

The description discloses the key side effects: draw mode marks entries on tables without replacement so they do not come again, while roll mode never marks anything. It also states that nothing goes to chat unless chat is set. This goes well beyond the generic annotations (readOnlyHint false, idempotentHint false) and tells an agent exactly how state may change.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, with the purpose front-loaded first and mode/chat behavior following directly. There is no filler or repeated information beyond necessary clarification.

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

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

The definition covers purpose, mode behavior, chat behavior, and side effects, and the schema fully documents all parameters. It lacks only a description of the return-value shape and edge cases like an exhausted table, which is minor given the tool's low complexity and the absence of an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates mode behavior and the chat default that the schema already documents, adding no genuinely new parameter-level meaning beyond what an agent would already see in the input schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Roll on a roll table and return the entries.' It clearly distinguishes this from sibling tools like get-roll-table or reset-roll-table by focusing on drawing and returning results, while the mode detail adds operational scope.

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

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

The description gives clear context for choosing mode 'draw' vs 'roll' and explains when chat output occurs. However, it never names alternatives such as get-roll-table, reset-roll-table, or roll-dice, nor states when not to use this tool, so sibling differentiation is left to inference.

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

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

The description explains the effect on combat state (round 0, not active) and that combatants and initiatives are preserved, which goes beyond the destructiveHint annotation. It also discloses that deletion requires permission, adding context to the destructive nature. The idempotentHint and readOnlyHint are not contradicted; in fact, the explanation of 'keeps its combatants and initiatives' supports the non-destructive stop behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of only two sentences, with the core action front-loaded in the first sentence ('End a combat encounter: it stops...') and the alternative and caveat in the second. No unnecessary words or repetition of annotation data.

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

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

For a 3-parameter tool with full schema coverage and clear annotations, the description covers the primary behavior, the delete alternative, the permission requirement, and the fallback to the active encounter. An agent has all necessary information to invoke the tool correctly, even without an output schema.

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

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

Although the schema already documents each parameter, the description adds extra meaning beyond the schema descriptions: it explains that without combatId the active encounter is used, and that deleteEncounter changes the operation from stopping to deleting, plus the permission caveat. This adds value over the raw schema, which was already 100% covered.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool ends a combat encounter, specifying the resulting state (round 0, not active) and that it retains combatants and initiatives. It explicitly distinguishes between stopping and deleting via the deleteEncounter parameter, which is a key differentiator from sibling tools like start-combat or delete-encounter.

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

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

The description explicitly contrasts the default behavior (stop) with the deleteEncounter alternative, and even references Foundry's own End Combat to clarify semantics. It also notes that deletion is refused without a proper permission level, so an agent knows deletion may require permissions. It doesn't explicitly say 'use this to end an active combat' but that is clearly implied.

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

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

Annotations already include destructiveHint=true and openWorldHint=true, so the destructive nature is disclosed. The description adds important context: script macros can do anything a Gamemaster can, including deleting documents, and cannot be undone. It also explains the off-by-default execution setting and difference between chat and script macros, which goes 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: three sentences with no fluff. It front-loads the core purpose, then the critical caveat about script macros, and ends with the distinction for chat macros. Every sentence earns its place, providing essential information without redundancy.

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

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

For a macro execution tool with complex security implications, the description covers the essential operational context: the required world setting, the risk of script macros, and the behavior of chat macros. There is no output schema, but the description mentions 'report its result or error' which suffices. Given the complexity, the description is complete enough 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.

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

The schema description coverage is 100%, meaning all parameters are described in the schema (e.g., args, alias, macroId). The description itself doesn't add extra parameter details beyond what the schema provides, but it does mention 'read its command' and 'speaker' nuances that align with parameters. Since schema coverage is high, the baseline is 3, and no description compensation is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool executes a macro in the Gamemaster's browser and reports the result or error. It specifies the resource (macro) and the action (run/execute), distinguishing it from sibling tools like list-macros (which lists macros) and create-macro (which creates macros).

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

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

The description provides explicit usage guidance: it mentions the world setting requirement ('macroExecution' must be 'chat' or 'all') and instructs to read macro commands with list-macros before executing script macros. It also distinguishes between chat macros (post to chat) and script macros (can do anything), implicitly guiding when to use this versus other tools.

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

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

Beyond the annotations, the description discloses that duplicate ids are overwritten, locked compendiums are refused unless unlockIfNeeded is set, and the lock is restored afterwards. It also describes the output summary (new, overwritten, skipped, lost), giving an agent a clear picture of side effects and results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences with no wasted words. Purpose is front-loaded, and each subsequent sentence adds a distinct behavioral detail (selection, overwrite, lock handling, result listing).

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

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

Given no output schema, the description enumerates the answer categories and covers edge cases like duplicates and locks. For a moderately complex write operation, all essential behavior an agent needs to call and interpret results is documented.

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

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

The input schema already describes every parameter fully (100% coverage). The description adds value by explaining the interplay between names, folderName, and omission (fallback to all documents of the type), as well as case-insensitive name matching. This is helpful but not extensive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool copies documents from the world into a compendium for archiving finished material. The specific verb and resource are unmistakable, and the direction distinguishes it from the sibling import-from-compendium.

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

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

It provides clear context for when to use the tool (archiving finished material) and explains the selection modes (by name/id, folder, or everything). However, it does not explicitly name alternatives or state when not to use it, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the safety profile. The description adds valuable behavioral context: the exact path matching rule (folder matches files under it, never a longer name), the scan scope (every field of every world document), and the compendium exclusion. It does not describe output format or edge cases, but this is not required given the strong annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler: action, path rule, usage context, and limitation each earn their place. The core function is front-loaded and the supporting rules are presented in a logical order.

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

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

For a read-only search tool with a simple parameter set and strong annotations, this description is complete: it states what is scanned, how path matching works, when to use it, and a key exclusion. The only minor omission is output format details, but no output schema exists and the tool's purpose makes the return type obvious.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description goes beyond the schema by explaining the semantic behavior of the path parameter ('a folder matches the files under it, never a longer name'), which is essential for correctly interpreting what results will be returned. The maxResults and collections parameters are sufficiently documented in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise verb-and-resource pair: 'Find every field of every world document that points to a file or folder path.' It also clarifies the exact matching rule and scope ('Compendiums are not scanned'), which makes it clearly distinguishable from file-related siblings like find-missing-files or world-rewrite-paths even without naming them. The title and description agree and add specificity.

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

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

The description gives an explicit usage scenario: 'Use it before moving or replacing files.' It also exposes a limitation ('Compendiums are not scanned') that tells the agent when this tool is insufficient. It does not explicitly name alternative tools or give detailed when-not-to-use guidance, so it stops just short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds meaningful behavioral nuance beyond those flags: wildcard paths are counted but not checked, compendiums are not scanned, and the search spans both data storage and Foundry's own files. This gives an agent expectations about coverage and false positives without contradicting the read-only safety hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with no fluff. The first sentence front-loads the action, scope, and locations; the second packs the essential caveats. Every clause adds information.

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

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

The description is complete for a read-only analysis tool: it states what is searched, where, and the important coverage limits. With no output schema, it leaves the exact result shape implicit, but the maxResults/maxDirectories parameters and the verb 'find' make the return intent clear.

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

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

Schema description coverage is 100% and every parameter already has a clear description in the schema, so the baseline is 3. The tool description adds no parameter-level meaning beyond the schema; it neither clarifies formats nor reveals relationships between parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Find files that world documents point to but do not exist.' It further narrows scope by enumerating file types, lookup locations, and explicit exclusions, making it distinguishable from sibling file tools like find-file-references and browse-files without needing to open the schema.

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

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

The description gives clear context on what the tool covers (images, sounds, videos, text, fonts in fields and markup, data storage and Foundry files) and states two limitations: 'Wildcard paths are counted but not checked. Compendiums are not scanned.' It does not explicitly name sibling alternatives or state a direct when-to-use/when-not-to-use rule, so it falls just 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it computes a path and its length, does not move anything, and works without a drawn canvas. It could mention whether the path is returned as a list of points or cells, but the description adds meaningful behavior beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the core function, the non-mutation clarification, and the no-canvas prerequisite. The most important scoping information is front-loaded. No wasted words.

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

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

For a read-only pathfinding tool with 100% schema coverage and no output schema, the description is nearly complete. It covers the core inputs, the wall-type variants, the non-mutation guarantee, and the canvas prerequisite. A minor gap is that it doesn't describe the return format (e.g., list of points, length), but the description already states it returns the path and its length, which is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds the 'type' enum semantics ('Which walls count') and the 'maxCells' search limit concept, but it doesn't add much beyond the schema. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Find a way'), a resource ('from a token or point to another'), and the key constraint ('around walls that block movement (or sight, light, sound)'). It also distinguishes itself from the sibling 'move-token' by explicitly saying 'Moves nothing; move-token moves a token.' This makes the tool's purpose unmistakable.

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

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

The description explicitly says when to use this tool ('Find a way... around walls') and contrasts it with the alternative ('move-token moves a token'). It also notes that it 'Works without a drawn canvas,' which clarifies a common prerequisite. This is strong usage guidance.

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

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

Annotations already establish that this is a safe, read-only, idempotent operation. The description adds genuinely useful behavioral details beyond those annotations: results are ordered nearest first, optional wall/sight filtering, and no canvas requirement is needed. This is meaningful context for an agent deciding how to invoke the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, with two sentences that carry distinct value: the core behavior and the optional sight-filtering mode, plus the important canvasless guarantee. There is no filler or redundant restatement of the tool's title.

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

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

For a read-only list operation with complete parameter documentation and safety annotations, the description is nearly sufficient. It captures ordering, sight filtering, and canvas independence, while the schema handles parameter semantics. The lack of an output schema means some return-format detail is not disclosed, but it is not critical for correct invocation.

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

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

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds little beyond what the schema already documents, although terms like 'scene units' and 'token or point' reinforce the schema's meaning. It does not compensate for any parameter gap because none exists.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: it lists tokens within a distance with nearest-first ordering. It also conveys the optional line-of-sight filtering, making the tool's behavior easily identifiable. It does not explicitly differentiate itself from sibling tools by name, though its scope is distinct enough.

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

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

The description gives useful context about when the tool applies, notably that it works without a drawn canvas and can filter by line of sight. However, it does not explicitly state when to use this tool over alternatives such as measure-distance or check-wall-collision, leaving that routing implicit.

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

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

Annotations already mark the tool as destructive and read-only=false, but the description adds significant behavioral context: default moves documents/subfolders up one level, deleteContents deletes them, and permission requirements. This goes beyond annotations and fully discloses consequences.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three focused sentences: the first states the action and identification method, the second explains default behavior, the third covers the deleteContents option and permissions. Every sentence adds value, and the most important info is front-loaded.

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

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

The description provides all necessary operational details: identification method, behavior with and without deleteContents, and required permission levels. For a 3-parameter tool with a simple output (no output schema), this is complete and leaves no ambiguity for an agent.

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

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

Schema coverage is 100% with descriptions for all parameters, and the description adds meaning for folderName (id or exact name) and deleteContents (default false). It clarifies that deleteContents also includes subfolders and explains the permission implications, enhancing the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Delete a sidebar folder, found by its id or exact name' with a clear verb and resource, and distinguishes it from document deletion by focusing on folders. It is specific and differentiates from siblings like delete-document and journal-delete.

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

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

The description implies when to use this tool (for deleting folders) and explains the default behavior versus deleteContents, giving clear context. It doesn't explicitly name alternatives, but the resource type is unambiguous, and it covers the main decision point (whether to also delete contents).

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

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

Annotations already cover non-destructive (destructiveHint=false) and idempotent aspects)Skip. The description adds 'Contents stay,' directly confirming no data loss, and explains the behavior when multiple folders share a name (error lists them). This provides context beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, each earning its place: the first states the core action and parameters, the second covers ambiguity handling, the third reassures non-destructiveness. No fluff, and key info is front-loaded.

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

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

For a simple rename tool with no output schema, the description covers identification, optional filtering, disambiguation, and non-destructive nature. It doesn't mention return values, but that's not critical given the simplicity. Overall it gives an agent enough to call it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description largely restates the folderName and type semantics ('found by its id or exact name,' 'optionally only among folders of one document type'), but adds the interaction detail that ambiguous names cause an error listing matches. It does not elevate semantics meaningfully beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description states a specific verb and resource ('Rename a sidebar folder') and distinguishes it from siblings like folder-delete and journal-rename by specifying 'sidebar folder' and the id/exact-name lookup. It also clarifies scope with the optional document type filter. This is a clear, distinct purpose.

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

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

Provides clear usage context: folder can be identified by id or exact name, optionally scoped by document type, and explains how ambiguity is resolved (error lists matching names, then use id). It does not explicitly contrast with alternative tools, but it gives enough context for when to call and even how to recover from ambiguous matches.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that the output includes id, name, icon, and description, which is useful. However, it doesn't disclose whether the list is complete, sorted, or filtered by game system, though the mention of 'game system of the world' hints at system-specificity. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the main purpose ('List the conditions') and includes the output fields and a usage pointer. No fluff, every word contributes. It is appropriately sized for a simple read-only list tool.

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

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

The tool is simple with no parameters and no output schema. The description is complete enough to know what it does and when to use it. It could potentially mention that the output is only for the current world's game system, but the mention of 'game system of the world' covers that. Given the simplicity, nothing critical is missing.

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

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

The tool has 0 parameters, so the schema provides no parameter information. The description adds meaning by explaining what the tool returns (id, name, icon, description) and its purpose (to get id for toggle-token-condition). This compensates for the lack of parameters, and the baseline for 0 params is 4, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'available conditions', specifying the output fields (id, name, icon, description). It also distinguishes its purpose from the sibling 'toggle-token-condition' by indicating it provides the id needed for that tool, making it highly distinguishable.

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

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

The description explicitly tells the agent when to use this tool: 'Use it to find the id for toggle-token-condition.' This provides clear context and implies that if you need to toggle a condition, you should first call this tool. It does not mention alternatives, but the explicit usage scenario is sufficient, especially given the large sibling list.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds value by specifying exactly what data is fetched (canvas presence, scene, view, targets) and the fact it reflects the Gamemaster's browser. It also notes the dependency relationship with sibling tools. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first enumerates the returned information, the second provides usage direction. It is front-loaded with the core purpose and has no redundant text. Efficient and well-structured.

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

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

For a zero-parameter read tool, the description is remarkably complete: it enumerates all the data fields returned, names the dependent tools, and conveys the Gamemaster-specific context. Although there's no output schema, the description itself serves as a sufficient guide. It fits the tool's low complexity.

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

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

No parameters exist, so the schema fully covers them (100% coverage). The baseline for 0-param tools is 4, and the description doesn't need to add parameter details. It adequately describes the tool's behavior without mentioning parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads the canvas state: whether a canvas is drawn, which scene is active, view position/zoom, and targets. It distinguishes itself from siblings by naming pan-camera, ping-canvas, and set-targets as consumers. No ambiguity about what it does.

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

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

It explicitly instructs to call this before pan-camera, ping-canvas, or set-targets, which require the canvas. This gives clear when-to-use context. No exclusions, but the primary use cases are well-defined.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing that cards are returned in order and enumerating the specific card fields (name, suit, value, drawn, text, image, origin), which is useful behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that states the operation, scope, ordering, and output fields without any wasted words. Every part of the sentence contributes useful information.

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

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

For a simple read-only tool with two schema-documented parameters and strong annotations, the description covers the output structure and ordering. No additional return-format or side-effect guidance is needed given the annotations and schema.

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

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

Schema description coverage is 100%, so the schema already documents stackId and includeDrawn with clear meaning and defaults. The description does not add parameter-specific semantics beyond the schema, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Read') and a precise resource ('one card stack') and clarifies that it returns the stack's cards in order with named fields. This clearly distinguishes it from sibling tools like list-card-stacks (which lists stacks) and draw-cards (which modifies a stack by drawing from it).

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

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

The description implies usage for reading a single card stack's contents, but it does not explicitly state when to prefer this tool over alternatives such as list-card-stacks or draw-cards. No exclusions or alternative tool mentions are provided, leaving the agent to infer the appropriate selection context.

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

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

Annotations already declare the read-only and idempotent safety profile, and the description adds substantial behavioral context beyond annotations: the response shape varies by game-system adapter. It discloses that item descriptions are omitted, that adapter-less actors expose only name/type/image, and that similar names are suggested rather than guessed, preventing hallucinated lookups. This is meaningful behavioral disclosure beyond readOnlyHint/idempotentHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose — 'Overview of one actor with few tokens' — and every subsequent sentence contributes information about output contents, adapter fallback, identifier semantics, or the sibling tool for full entity data. It is dense but not bloated, and avoids repeating schema text or annotation hints.

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

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

With no output schema present, the description carries the burden of explaining the return contents, and it does so thoroughly: head values, adapter-specific value block, item fields, effects/actions, spellcasting, and the minimal fallback case. It also covers identifier lookup behavior and routes to get-character-entity for deeper item data, giving an agent everything needed to call the tool correctly for a single-parameter read-only operation.

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

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

The schema already documents the identifier parameter at 100% coverage, including 'Id of the actor, its exact name (case does not matter) or the id of one of its tokens'. The description adds useful semantic behavior beyond the schema, namely that similar names are suggested and never guessed. It does not need to repeat the schema text, but the added matching behavior pushes it above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States the tool returns an 'Overview of one actor' and enumerates the included data: head values, adapter-dependent value block, items with id/name/type, effects, actions, and spellcasting. It also differentiates itself from get-character-entity by explicitly pointing there for full item/effect data. The verb and resource are specific enough that an agent can identify what this tool does at a glance.

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

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

The description explains the identifier resolution behavior and names get-character-entity as the alternative when full item/effect data is needed. It also tells the agent when results will be minimal ('Without an adapter for the game system only name, type and image are known'), setting expectations for sparse output. It does not enumerate all possible sibling alternatives like list-characters, so the routing guidance stops just short of exhaustive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: credentials are removed from system data, game data is kept, lookup order is items→actions→effects, and duplicate names are reported with ids instead of picking one. This goes 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no wasted words. The core purpose is front-loaded, and the second sentence packs three important behavioral details (lookup order, data filtering, duplicate handling) efficiently. Every clause earns its place.

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

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

For a read-only lookup tool with 100% schema coverage and no output schema, the description is nearly complete. It explains what data is returned (description, system data with credentials removed, effects), how lookup works, and how duplicates are handled. The only minor gap is not describing the exact response shape, but the absence of an output schema and the read-only nature make this acceptable.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds context about what entityIdentifier can be (id or exact name for items/effects, name for actions) and that characterIdentifier accepts id, exact name, or token id, but this largely mirrors the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('get') and resource ('full data of one item, action or effect of an actor'), and clearly distinguishes it from siblings like get-character, get-document, and get-compendium-item by specifying the entity types and actor scoping. It also explains the lookup order (items first, then actions, then effects), which removes ambiguity about what the tool returns.

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

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

The description gives clear context on when to use this tool: to retrieve full data for an actor's item, action, or effect. It doesn't explicitly name alternatives or exclusions, but the lookup order and the note about duplicate names provide practical guidance. Sibling tools like get-character and get-document are implicitly distinguished by the entity types covered.

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