Foundry MCP

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

Annotations only indicate create semantics (not read-only, not idempotent, not destructive), so the description carries the burden of behavioral detail. It adds valuable context: game-system-specific type validation and the fact that the system object is deep-merged over system defaults. No annotation 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 short sentences, each earning its place: scope, type constraints, alternative tool, and merge behavior. The purpose is front-loaded and there is no filler or restatement of schema fields.

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 a nested system object and no output schema, the description covers the required inputs, valid type values, and the main alternative path. It is slightly incomplete in that it does not mention return values or what the agent receives after creation, which would be useful when no output schema is provided.

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 listing pf2e type values that the schema's type property omits, and by clarifying how the nested system parameter behaves ('deep-merged over the system defaults').

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 a new actor') and adds the qualifier 'from scratch', which clearly differentiates it from sibling actor-create-from-compendium. Listing custom NPCs, characters, and creatures as the intended use further disambiguates the tool's 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?

Explicitly directs compendium imports to actor-create-from-compendium, giving the agent a concrete decision rule. It also tells the agent that type must be valid for the world's game system and enumerates the valid values for dnd5e and pf2e, so the agent knows the constraint before invoking.

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 signal that this is a write operation (readOnlyHint=false) and not idempotent, and the description does not add behavioral context beyond 'Import... into the world.' It does not disclose whether repeated imports create duplicates, whether the imported actor is a copy or a reference, or any permission requirements. With no additional behavioral disclosure, the description does not enrich what annotations already 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 redundant wording. The core purpose is front-loaded, followed immediately by the essential identifier-mode guidance. 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?

The description thoroughly explains how to specify the compendium source and mentions the optional name and folder parameters are covered by the schema. However, with no output schema, it does not describe the return value or how the agent can confirm success. It also omits any note about duplicate-import behavior. This is adequate for making a valid call but leaves some post-invocation context unclear.

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 covers each parameter, and the description adds relational semantics by explaining the two mutually exclusive identifier modes: uuid (with exact format and source tools) versus packId + actorId (from compendium-browse). This clarifies that packId/actorId are required only when uuid is absent, adding meaning beyond the individual property descriptions.

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

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

The description states a specific verb and resource: 'Import an actor (monster, NPC) from a compendium pack into the world.' This clearly distinguishes it from sibling tools like actor-create by specifying the source (compendium) and the destination (world). The mention of 'monster, NPC' further disambiguates the actor type.

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 guidance on how to identify the target: either via uuid from filter/search tools or packId + actorId from compendium-browse. However, it does not explicitly contrast this tool with alternatives like actor-create or explain when to prefer this over creating an actor from scratch. Usage is implied rather than explicitly stated.

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 readOnlyHint=false, so the safety profile is covered. The description adds the irreversibility warning ('cannot be undone'), which is more specific than the generic destructive flag and provides useful behavioral context. It doesn't discuss cascading effects or permissions, but for a simple delete with annotations present, this is sufficient.

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 short sentences with zero redundancy. The core action is stated first, and the irreversibility warning follows immediately. Every word adds value; there is 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 single-parameter destructive operation with no output schema, the description covers the essential facts: what it does and its irreversible nature. It could mention what happens if the actorId is invalid or non-existent, but for a simple delete that is a minor gap. The description is adequate 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 fully documents the sole parameter (actorId) with its purpose and type. The description does not add any extra meaning about the parameter, such as format or required semantics beyond what the schema states. 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 specific verb ('delete'), a specific resource ('actor'), and the scope ('from the world'). It clearly distinguishes from siblings like actor-update, actor-create, and actor-get. There is no ambiguity about what the tool does.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, conditions, or exclusions. While the verb 'delete' implicitly suggests a lifecycle action, the description does not explicitly contrast with actor-update or other actor operations, leaving the agent to infer usage.

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 (readOnlyHint=true, idempotentHint=true), the description discloses key behavioral traits: returns paginated {id, name} entries, filters combine with AND/OR, ranges are inclusive, actors lacking a filtered field are silently excluded, and pagination uses limit/offset with total/hasMore. It also details critical value constraints (CR is a number from an exact set, sizes are short codes, creatureType only SRD types) and that compendiums are not searched. This is substantial behavioral context that annotations do not 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 well-structured and front-loaded: a one-sentence purpose, then usage examples, then critical data formats, then pagination details. Every sentence adds value; there is no filler or redundancy. Despite its length, it is concise relative to the complexity of 15 parameters and nested objects, and it is easy to scan due to clear section headers (CRITICAL DATA FORMATS, EXAMPLES).

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 (15 optional parameters, nested ranges, pagination) and the absence of an output schema, the description is remarkably complete. It explains filter combination, value constraints, edge cases (silent exclusion of actors lacking fields), pagination behavior, and directs the agent to actor-get for full stats. It also distinguishes from sibling tools. The only minor gap is behavior when no filters are provided, but the explicit note to use actor-list for unfiltered retrieval covers that 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?

Although the schema covers 100% of parameters with basic descriptions, the tool description adds critical semantic meaning: it explains that CR values must be from the exact set (rejecting '1/4' and '0.7'), sizes use short codes ('small' rejected), creatureType only accepts the 14 SRD base types (subtypes like 'demon' map to 'fiend'), ranges are inclusive, and missing fields are silently excluded. It also clarifies AND/OR semantics across filters. This goes far beyond the schema's per-field descriptions.

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

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

The description opens with a precise verb+resource: 'Search WORLD actors with D&D 5e structured filters (dnd5e worlds only).' It explicitly distinguishes from actor-list (unfiltered) and dnd5e-compendium-filter-actors (compendiums), so the agent knows exactly what this tool does and what it is not. The examples ('undead with CR 1-5', 'PCs in the party') further ground the 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 gives explicit usage guidance: 'Use for ...' with concrete examples, and clearly states when NOT to use it: 'For every actor unfiltered use actor-list; compendiums are NOT searched (use dnd5e-compendium-filter-actors).' It names the alternative tools and the conditions that select them, leaving no ambiguity.

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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: cross-system behavior (non-dnd5e sections such as skills or currency stay empty) and the fallback to uuid-resolve for the raw document. 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?

Four dense sentences with zero filler: purpose is front-loaded with the content list, followed by prerequisite sequencing, downstream consumers, and the cross-system caveat. 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 one-parameter read-only tool with rich safety annotations and no output schema, the description fully covers output contents, ID prerequisites, downstream tool dependencies, and system-specific behavior. Nothing an agent needs 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 coverage is 100% — actorId is already documented as 'Actor ID (from actor-list or actor-filter)'. The description reinforces where the ID comes from and its downstream use, but adds no format, syntax, or example detail beyond the schema. Baseline 3 for high schema coverage 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 ('Get full actor details') and enumerates the content (HP, AC, abilities, skills, speed, proficiency, inventory with item IDs). This clearly distinguishes it from siblings actor-list and actor-filter, which are the ID-finding tools referenced in the same sentence.

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 explicit sequencing ('Use actor-list or actor-filter FIRST to find actorId'), names downstream consumers of the item IDs (dnd5e-roll-attack, dnd5e-roll-damage, dnd5e-item-use), and points to uuid-resolve as the alternative for raw document access. Lacks an explicit 'do not use when X' exclusion, but the routing guidance is strong.

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, covering the safety profile. The description adds valuable behavioral context beyond that: the row limit ('at most 200 rows') and the scope ('in the world'). It also implies the limitation that only name, type, and ID are returned, which is useful for downstream 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?

The description is two sentences, each earning its place. The first sentence front-loads the core purpose and row limit. The second sentence gives usage guidance and a practical note about actor IDs. 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 listing tool with one optional parameter and no output schema, the description covers all essential aspects: what it returns, the row limit, the alternative tool, and why the results matter (actor IDs for rolls, combat, items, effects). 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 description coverage is 100% for the single optional 'type' parameter, so the schema already explains its meaning and allowed values. The description does not add any parameter-specific detail, but it doesn't need to since the schema fully documents it. The baseline of 3 applies: the description neither enhances nor detracts from 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 states a specific verb ('List'), a clear resource ('actors in the world'), and the returned fields (name, type, ID). It also explicitly differentiates itself from actor-filter by naming exactly what actor-filter handles ('by name, CR, creature type, size, folder, HP, AC'). This is a precise, unambiguous purpose statement.

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 guidance: 'For anything beyond a plain listing — by name, CR, creature type, size, folder, HP, AC — use actor-filter, which also paginates.' This names the alternative and the exact conditions for selecting it, leaving no ambiguity about when to use this tool versus its sibling.

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 beyond the annotations by disclosing that system data is DEEP-MERGEDholistically: untouched paths remain intact but arrays are replaced entirely. This is useful behavioral context that the schema and annotations alone do not provide. It does not mention permissions or errors, but the core mutation behavior is well disclosed.

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 that front-load the operation and resource, follow with critical merge semantics, and end with a practical example. There is no filler or redundancy; 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?

With all parameters documented in the schema and the description covering the complex nested-object merge behavior, an agent has enough information to make a correct call. The absence of an output schema and no statement about the return value or error behavior is a minor gap, but it does not block successful 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema by explaining the deep-merge behavior and providing a concrete dnd5e path example. The common-path listing also helps agents construct valid system inputs, which the schema alone only hints at.

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 ('Update'), the resource ('an actor'), and the specific fields affected (name, image, folder, system data). It does not explicitly name sibling alternatives like actor-create or actor-delete, but the 'update' verb conveys the operation distinctly 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 clear usage context: use this tool to mutate an existing actor's top-level fields or system data, with explicit guidance to pass only changed paths. It does not explicitly say when not to use it or name alternatives, so it lacks exclusions, but the intended context is unambiguous.

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: the view change affects 'everyone's view,' coordinates are scene pixels rather than grid squares, and omitted fields preserve current settings. It also reveals the animation mechanism via canvas.animatePan. This is more than the annotations alone 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 sentences with no filler. The primary action and key constraints are front-loaded, the coordinate system clarification is prominent, and the sibling alternative is a single clear sentence at the end.

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, fully-optional-parameter tool with no output schema, the description covers everything needed to invoke it correctly: action, coordinate system, optionality, effect scope, and the alternative sibling. No important gap remains.

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 each parameter with 100% coverage, so the bar is lower, but the description still adds value by emphasizing 'scene pixels, not grid squares' and explicitly stating that all fields are optional. This reinforces the coordinate system and partial-update semantics beyond the individual parameter descriptions.

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

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

The description uses a specific verb and resource: 'Pan and/or zoom the canvas to scene-pixel coordinates' and names the underlying API method. It clearly distinguishes this from canvas-ping by stating the different purpose and explicitly naming the 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 provides explicit guidance on when to use this tool versus the alternative: 'Use canvas-ping to draw attention to a spot instead.' It also clarifies field optionality so an agent knows it can partially update the view without supplying all parameters.

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 doesn't need to justify the write nature. The description adds valuable context beyond annotations: the ping is visible to all clients (broadcast behavior) and stresses that x/y are scene-pixel coordinates, not grid squares. This clarifies important behavioral expectations that annotations do not cover. 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 three concise sentences with zero filler. The core purpose is front-loaded, then usage context, then a crucial parameter requirement. Each sentence earns its place, and the structure is easily scannable.

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 adequate for a tool with 5 parameters (2 required) and no output schema. All parameters are documented in the schema, and the description adds the coordinate-system clarification and the broadcast visibility. It does not explain default values for style/duration, but those are derivable from the schema descriptions. The absence of output schema means no need to describe return values. Overall, 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 the baseline is 3. The description adds crucial clarification that x and y are REQUIRED and are in scene pixels (not grid squares), which directly impacts how an agent constructs valid calls. It also reiterates the purpose of these parameters. This added value justifies a 4 rather than a baseline 3.

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 ('drop'), a specific resource ('ping marker'), and the coordinate system (scene-pixel). It also names the effect ('visible to all clients') and the intended use ('draw players' attention to a spot'), clearly distinguishing it from sibling tools like canvas-pan (which moves the view) and ui-notify (which sends notifications).

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 to use this tool ('Use to draw players' attention to a spot'), giving clear context. It does not explicitly name alternatives or exclude other tools, but the purpose is specific enough that an agent could infer the appropriate scenario. The absence of an explicit 'instead of X' is a minor gap.

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 the description reinforces this with 'IRREVERSIBLE.' It also specifies what gets destroyed ('ALL chat messages'), adding useful context beyond the annotation. 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 short sentences, each carrying essential information: the action, its irreversibility, and the strict usage condition. 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 zero-parameter destructive tool, the description covers the scope, the risk, and the only acceptable trigger condition. It is complete enough for an agent to invoke this tool safely and avoid misuse.

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 zero parameters, so the baseline is 4. The description does not need to elaborate on parameters, and the schema confirms none exist.

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 ALL chat messages.' The use of 'ALL' and 'entire chat log' clearly distinguishes this from the sibling chat-delete tool, which presumably targets individual messages. The scope 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 to use the tool: 'Use ONLY when the user explicitly asks to clear the entire chat log.' This is a clear condition with an implicit exclusion, though it does not name chat-delete as the alternative for deleting individual messages.

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 readOnlyHint=false, so the destructive nature is known. The description adds minimal extra context—it only says 'Delete a specific chat message', which doesn't go beyond the annotations. It could have mentioned permanence or that only that message is affected, but those are already implicit. Thus it adds little beyond what structured data provides.

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: three short sentences that front-load the action, then give usage context and the prerequisite. Every sentence earns its place with no fluff, making it easy 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?

For a simple single-parameter tool with annotations covering destructiveness and no output schema, the description covers the action, usage context, and how to obtain the ID. It does not discuss error handling or return values, but those are not critical given the tool's simplicity and absence of an output schema. Overall, it is complete enough 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 schema already describes the messageId parameter and says to get it from chat-list. The description repeats this instruction, adding no new semantic meaning beyond what the schema provides. Since schema coverage is 100%, the baseline of 3 applies, and the description does not significantly enhance 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 clearly states the action (delete), the resource (chat message), and the specificity (by ID). It also conveys the use case (remove erroneous messages, clean up chat), which distinguishes it from siblings like chat-clear or chat-update without explicitly 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?

It provides clear context for when to use the tool ('remove erroneous messages or clean up chat') and gives a prerequisite ('Use chat-list FIRST to find the message ID'). However, it does not explicitly state when not to use it (e.g., for bulk deletion use chat-clear), so exclusions are only 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral detail by specifying the exact output structure for both text and JSON formats, which goes beyond the schema. No contradictions.

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

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

The description is two sentences with no filler. The purpose and use cases are front-loaded, followed by concise format examples. Every sentence adds useful 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 simple read-only export tool with one parameter and no output schema, the description fully covers what it does, when to use it, and what the output looks like. Nothing an agent needs to correctly invoke it 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 single parameter 'format' is already fully described in the schema (enum with 'text' default and 'json' for structured data), so schema coverage is 100%. The description adds extra value by detailing what each format contains (e.g., '[Speaker] Content' lines and message object fields like id, timestamp, author, etc.), which is not 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?

States a specific verb (export) and resource (full chat log), and specifies the two output formats (text/JSON). It clearly separates itself from siblings like chat-list and chat-get by emphasizing 'full chat log' and 'export' rather than listing or retrieving individual 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?

Provides explicit use cases ('session summaries, recapping what happened, saving chat history') which helps an agent decide when to invoke it. However, it does not name alternative tools or state when not to use it, leaving some inference required given the many chat-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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral details beyond that: 'Returns plain text (HTML stripped)' and 'Messages are returned in chronological order (oldest first)'. It also explains the polling semantics. This adds meaningful context 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?

The description is four sentences, each with a distinct purpose: core function, use cases, return format, polling, filters, and ordering. It is front-loaded with the core purpose and avoids redundancy. Every sentence earns its place, making it highly efficient.

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

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

For a read-only list tool with no output schema and comprehensive annotations, the description covers all essential aspects: purpose, use cases, return format, ordering, polling, and filters. It does not mention edge cases like empty results or error behavior, but these are minor for a read operation. The description is complete enough for an agent to call it correctly without further ambiguity.

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 each parameter already has a description. The description adds usage context for the `since` parameter (polling) and groups the filters (authorId, actorId, type, search) as a coherent set. It doesn't repeat schema details but highlights the intended use of specific parameters, which is helpful. Baseline is 3 due to full coverage, and the added polling guidance 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 ('Read') and resource ('chat messages from Foundry VTT'), then lists concrete use cases ('see what players are discussing, check roll results, or review combat narration'). This clearly distinguishes it from sibling write tools like chat-send, chat-update, and chat-delete by framing it as a read operation. The purpose is unambiguous and actionable for an agent.

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 usage scenarios ('Use to see what players are discussing...') and provides a specific polling pattern ('Use since param with a message ID to poll for new messages'). It does not explicitly name alternatives or state when not to use it, but the context of siblings and the explicit read-only framing make the appropriate use clear. Missing an explicit 'instead of chat-export' or similar, but overall guidance is strong.

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 minimal flags (readOnlyHint=false, destructiveHint=false) and do not disclose behavioral nuances. The description adds valuable context that players see what is posted, explains that actorId shows a portrait, and that flavor acts as a subheading. No contradictions with annotations; both treat this as a mutable, non-destructive write operation.

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, each earning its place: purpose, use cases, parameter guidance, and a critical visibility note. It is front-loaded with the core action and packs dense, useful information without fluff 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 chat-send tool with 6 parameters all fully described in the schema, the description covers usage scenarios, formatting capabilities, parameter behaviors, and player visibility. It does not mention persistence or message length limits, but those are minor for correct invocation. The lack of an output schema is acceptable since the tool's return value is not critical to calling 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 descriptions on every parameter, so the baseline is 3. The description exceeds this by providing concrete examples for flavor ('Narration', 'The Tavern'), explaining the @UUID link syntax, and clarifying that actorId overrides speaker and shows a portrait. This adds practical meaning beyond the raw 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 'Send a message to the Foundry VTT chat log,' clearly stating the verb and resource. It then lists distinct use cases (narration, NPC dialogue, combat descriptions, out-of-character communication) which differentiates it from sibling chat tools like chat-list, chat-update, and chat-delete that manage existing 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 description explicitly states when to use the tool: 'Use for narration, NPC dialogue, combat descriptions, and out-of-character communication with the player.' It provides clear context but does not name alternatives or exclusion criteria, so it stops short of a perfect 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=false, destructiveHint=false, idempotentHint=false, indicating a mutating, non-idempotent operation. The description's 'Edit' aligns with this but adds no new behavioral detail beyond the prerequisite of chat-list. It doesn't clarify what happens when both content and flavor are provided (likely both are updated), but that's not a major gap given the schema covers the parameters.

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 (two sentences) and front-loaded with the purpose. Every sentence earns its place: it states the action, gives concrete use cases, provides a necessary prerequisite, and states a key constraint. No fluff 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 update tool with three parameters (one required) and no output schema, the description covers the essentials: what it does, how to obtain the required ID, and a usage constraint. It doesn't mention the return value or error behavior, but these are not critical for a basic mutation. It could clarify that both fields can be updated simultaneously, but that's a minor omission.

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 all three parameters are documented. The description adds value by specifying that at least one of content or flavor must be provided—a constraint not enforced by the schema (only messageId is required). It also points to chat-list as the source for messageId, which is useful. This exceeds the baseline 3 for full coverage.

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

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

The description clearly states the tool's purpose: 'Edit content or flavor of an existing chat message.' It distinguishes from siblings like chat-send (creating new messages) and chat-delete (removing), and even gives specific use cases ('fix typos in DM narration or update descriptions'), making it easy for an agent to know when this tool applies.

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 a clear prerequisite: 'Use chat-list FIRST to find the message ID.' It also states a necessary constraint: 'At least one of content or flavor must be provided.' However, it does not explicitly mention when NOT to use it (e.g., for new messages use chat-send), though this is implied by the sibling names and 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 only indicate this is a non-read-only, non-destructive call. The description adds behavioral context by revealing that the tool does not automatically roll initiative or start combat, and that actorId must be resolved beforehand. It does not address edge cases like duplicate actors, but the key sequencing behavior is disclosed.

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 convey both the operation and the full prerequisite/follow-up workflow. There is no filler and the most important information 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 mutation tool with full schema coverage and an explicit workflow, the description is largely complete. It omits return-value details, but no output schema exists and the core invocation path is fully specified.

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 value beyond the schema by directing the agent to use actor-list or actor-filter FIRST to obtain the required actorId, which directly supports correct invocation.

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 'Add actor to combat', a concrete verb-resource pair that clearly distinguishes it from sibling tools like combat-remove-combatant or combat-set-initiative. The operation 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 gives an explicit workflow: use actor-list or actor-filter FIRST to find actorId, then add combatants, then call combat-roll-all-initiative before combat-start. It does not list explicit 'when not to use' conditions, but the sequential context is clear and actionable.

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 readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the description doesn't need to repeat those. It adds the workflow context but does not disclose any additional behavioral traits, such as what happens if a combat already exists or how the 'activate' parameter affects the result. The description is consistent with annotations but adds minimal behavioral detail beyond creation.

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 states the core action, the second provides the workflow context. It is front-loaded with the purpose and wastes no words. Every sentence earns its place, making it efficient and easy to scan.

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 two optional parameters and no output schema, the description covers the essential usage context through the workflow sequence. It doesn't explain edge cases like what happens if a combat already exists, but that is a minor gap given the tool's simplicity and the schema's parameter documentation. Overall, the 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?

The input schema provides 100% coverage for both parameters (sceneId and activate) with clear descriptions. The description does not add any extra meaning to the parameters, nor does it need to given the schema's thoroughness. Baseline of 3 is appropriate because 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 'Create new combat encounter' – a specific verb and resource. It also positions itself as the 'First step in combat workflow', which distinguishes it from sibling tools like combat-add-combatant or combat-start. The purpose is unambiguous and well-scoped.

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 provides the workflow sequence: 'After creating: use combat-add-combatant to add actors, then combat-roll-all-initiative, then combat-start.' This tells the agent exactly when to use this tool and what to do next, leaving no ambiguity about its role in the combat lifecycle.

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, so the destructive nature is known. The description adds the key behavioral detail 'without confirmation', which is not in the annotations. This informs the agent that no user confirmation step will occur, which is valuable beyond the structured hints. 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?

Two concise sentences with no filler. The primary action is front-loaded, followed by the usage condition. Every word earns its place, and the description is easily scannable for an agent.

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 destructive action with one optional parameter and no output schema, the description covers the purpose, the usage context, and the behavioral nuance (no confirmation). Nothing essential is missing for an agent to correctly invoke this tool.

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

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

The schema description for combatId states 'Combat ID (uses active combat if omitted)', covering the parameter's meaning and optionality. The tool description does not add any additional parameter guidance, so with 100% schema coverage, the baseline score of 3 applies. The parameter is adequately documented in the schema itself.

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 verb 'Delete', the resource 'combat encounter', and adds 'immediately without confirmation' for precision. It clearly distinguishes from other combat tools like combat-create or combat-get, and its specificity leaves no ambiguity about what the tool does.

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

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

The description provides an explicit condition: 'Use when combat is over or cancelled.' This tells the agent when to invoke the tool, though it doesn't mention explicit alternatives or when not to use it. Given the sibling set includes many combat tools, the guidance is adequate but not 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, destructiveHint=false, idempotentHint=true, so the description doesn't need to repeat those. It adds behavioral context about the return value (combatant IDs needed for other operations) and the sequencing instruction. It doesn't specify behavior when no combat exists, but the 'check if combat exists' phrasing adequately implies that case.

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, front-loaded with the core purpose, then usage guidance and parameter clarification. No wasted words; each 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 getter with one optional parameter and no output schema, the description covers the return contents and how to use it in a workflow. It's sufficient for an agent to call correctly, especially given the strong annotation coverage.

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 combatId with a description 'Combat ID (uses active combat if omitted)'. The tool description adds a slightly richer phrasing 'selects a specific encounter; omit it for the active combat' but essentially repeats the schema. Since schema coverage is 100%, 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 states the tool retrieves combat state including combatants, round, turn, and whose turn it is. It distinguishes itself from sibling combat tools by being the getter and explicitly positions it as the first call before other combat 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?

It explicitly instructs to call first to check if combat exists before other operations, and explains how to select a specific encounter via combatId or use active combat by omitting it. This is clear when-to-use guidance that differentiates from alternatives.

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 key behaviors beyond annotations: auto-advancing rounds and the optional tactical context (position, enemies, distances, line of sight, ASCII map). Annotations indicate this is not read-only, which is consistent. The description adds meaningful state-change details that an agent needs to set expectations.

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, front-loaded with the main action, then key behavioral notes. Every word earns its place; no fluff 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 simple two-optional-param tool, the description covers the primary action, round advancement, and context options. It does not elaborate on edge cases (e.g., invalid combatId, combat already ended), but those are likely handled by the system and not critical for an agent to decide to call the tool. The description is sufficient for a competent 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?

Schema coverage is 100%, so the baseline is 3. However, the description adds significant value for includeContext by detailing exactly what the tactical context includes and when it is advisable to turn it off. For combatId, it relies on the schema's 'uses active combat if omitted', which is already clear. Overall, the description enriches 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 states a specific verb ('advance') and resource ('next combatant's turn'), and explicitly mentions auto-advancing rounds. This clearly distinguishes it from sibling tools like combat-previous-turn (previous turn) and combat-set-turn (explicit turn selection). No ambiguity remains about what the tool does.

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

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

The description gives clear context about the tool's behavior (auto-advance round) and provides guidance on when to set includeContext false ('routine turns to save context'). It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to infer when to use this tool versus others in the combat family. Lacks explicit 'when not to use' but 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?

Annotations already convey that this is a non-read-only, non-idempotent mutation that isn't destructive. The description adds the precise effect (moving to the previous combatant), but doesn't disclose edge behavior such as what happens when already at the first combatant or whether it wraps around. 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 two short sentences with zero wasted words. The core action is front-loaded, and the use-case clarification follows immediately, 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 one-parameter tool whose schema and annotations already cover the safety profile and the optional combatId, the description is nearly complete. It explains what the tool does and when to use it; only niche edge behavior (e.g., starting position) is omitted, which is unlikely to affect 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?

There is only one optional parameter, combatId, and the schema description covers it 100% ('Combat ID (uses active combat if omitted)'). The tool description does not add parameter-level detail, but with full schema coverage and a clearly named parameter, no additional explanation is necessary.

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 uses a specific verb and resource: 'Go back to previous combatant's turn', immediately followed by the intended use case 'undo an accidental combat-next-turn'. This clearly differentiates it from combat-next-turn and from more generic combat-set-turn, so an agent can distinguish it without opening 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 explicitly names the situation where it should be used: after an accidental combat-next-turn. It does not mention alternatives such as combat-set-turn for jumping multiple turns, but the primary use case is clearly scoped, which is sufficient for a simple 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 declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the description doesn't need to restate those. The description adds useful context about the combatantId being distinct from actorId, but doesn't disclose what happens to the combatant's token, whether the combatant is permanently deleted or just removed from the current combat, or whether the combat must be active. With annotations covering the basic safety profile, a 3 is appropriate.

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 with zero waste. The core action is front-loaded, the critical identifier warning is second, and the usage condition is third. 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 two-parameter removal tool with full schema coverage and annotations, the description is nearly complete. It covers the action, the key parameter source, and the usage scenario. The only minor gap is not describing what happens after removal (e.g., is the combatant deleted or just removed from the encounter?), but this is a small omission for a straightforward tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description reinforces that combatantId comes from combat-get and is NOT actorId, which adds practical meaning beyond the schema. However, it doesn't add detail about combatId's 'active combat if omitted' behavior beyond what the schema already states.

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 ('Remove combatant from combat') and immediately distinguishes the key identifier from a common confusion ('not same as actorId'). It clearly differentiates from sibling tools like combat-set-combatant-defeated and combat-toggle-combatant-visibility by focusing on removal from 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?

The description explicitly says when to use this tool ('when creature flees or is removed from encounter') and tells the agent to use combat-get to find the correct combatantId. This provides clear context and a direct alternative/helper tool reference.

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, destructiveHint=false, and idempotentHint=false. The description confirms it's a mutation (rolling initiative) but doesn't elaborate on side effects like overwriting existing initiative values or setting turn order. Since annotations are minimal, the description carries some burden but only partially fulfills 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?

Two sentences, zero wasted words. The primary purpose is front-loaded, followed by ordering guidance and a flag hint. 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?

The description covers the essential usage: what it does, when to call it, and the key flag. It doesn't describe the return value, but no output schema exists and the tool is simple enough that this isn't critical. The schema handles parameter details like combatId defaulting. Adequate 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 three parameters. The description adds value by explaining the npcsOnly flag's rationale ('to let players roll their own'), which goes slightly beyond the schema's 'Only roll for NPCs, skip player characters'. This practical context justifies a score 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?

The description clearly states a specific verb and resource: 'Roll initiative for all combatants at once.' It distinguishes itself from the sibling combat-roll-initiative (singular) by emphasizing 'all at once', making the tool's purpose unambiguous.

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

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

It provides explicit ordering context ('Call AFTER combat-add-combatant, BEFORE combat-start') and explains the npcsOnly flag's purpose. While it doesn't explicitly mention the singular combat-roll-initiative as an alternative, the 'all at once' phrasing and naming make the distinction clear. Slight deduction for not naming the alternative directly.

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 convey that this is a non-read-only, non-idempotent operation, so the description does not need to restate the safety profile. However, it adds no behavioral context beyond the act of rolling—such as whether existing initiative values are overwritten or whether the roll affects combat state. The lack of contradiction keeps it at an adequate 3.

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 purposeful sentences: the core purpose is front-loaded, the ID lookup hint is included, and the sibling alternative is stated without extra detail. No word is wasted.

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?

Everything needed to select and invoke the tool correctly is present: the target combatant IDs, how to obtain them, a sibling disambiguation, and optional parameters are covered by the schema. The only minor gap is that no return/result behavior is described, but the tool is simple and the invocation path 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%, and the schema already documents combatantIds from combat-get, optional formula syntax, and default active combat. The description's mention of combat-get adds no meaning beyond what the parameter schema already states, so baseline 3 applies.

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 object—'Roll initiative for specific combatants'—and immediately distinguishes it from the sibling combat-roll-all-initiative. An agent can tell exactly what resource and scope this tool targets.

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 a concrete prerequisite ('Use combat-get to find combatantIds') and an explicit alternative for the when-not-to-use case ('For rolling all at once, use combat-roll-all-initiative instead'). This leaves no ambiguity about which situation selects 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 declare idempotentHint=true and destructiveHint=false; the description adds useful behavioral context by mentioning the skull icon and that defeated combatants skip their turn. 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?

Two short sentences with the main action first and a when-to-use clause second. 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 boolean setter with full schema coverage and idempotency annotation, the description plus schema fully covers what the tool does, when to use it, and how the optional combatId behaves. An output schema is not essential for this mutation.

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 combatantId, defeated, and optional combatId including the active-combat fallback. The description does not add parameter-specific meaning beyond the schema, so baseline 3 applies.

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 ('Mark') and resource ('combatant') and adds observable outcomes (skull icon, skipped turn), making it distinct from sibling combat-set-initiative, combat-set-turn, and combat-toggle-combatant-visibility.

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 gives a trigger condition: 'Use when creature reaches 0 HP or is otherwise eliminated.' It doesn't name alternatives or exclusions, but the context is clear enough for selecting among combat 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 convey readOnlyHint=false and destructiveHint=false. The description consistently implies a write operation but adds no behavioral detail beyond purpose — it doesn't mention overwriting behavior, permissions, or side effects. It doesn't contradict the annotations, but also doesn't significantly enrich behavioral understanding beyond what structured data provides.

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 short sentences with no filler. The action is front-loaded, and the use-case sentence earns its place by guiding selection. Every word is purposeful.

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 setter with full schema coverage and no output schema, the description plus annotations cover the essential information. It could briefly mention that setting overwrites the existing value, but that is strongly implied by 'set' and the idempotentHint. Minor gap, but overall complete enough.

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 mentions 'initiative value' but adds no parameter-level detail (e.g., range, format) or relationships between parameters. Baseline 3 applies because the schema carries the full 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?

Description clearly states 'Manually set initiative value' and differentiates from the rolling siblings by naming specific scenarios ('readied actions, special circumstances, or fixing rolls'). The verb-resource pair is specific and the tool's role among combat tools 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 gives explicit context for when to use the tool ('Use for readied actions, special circumstances, or fixing rolls'), which implies the alternative is rolling initiative. However, it does not explicitly name the alternative tools (e.g., combat-roll-initiative) or provide 'when not to use' exclusions.

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 (idempotentHint=true, destructiveHint=false), the description discloses critical behavioral details: it does not increment the round, avoids round-based effects like Rage expiry and concentration checks, and that includeContext defaults to true appending tactical context. These are substantive and not implied by 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 tightly constructed sentences: the first states the core action, the second explains the key distinction and why to use it, and the third covers source of IDs and the includeContext parameter. No filler or redundancy; information is front-loaded and efficient.

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

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

For a tool with only three parameters (one required) and no output schema, the description covers the purpose, usage context, behavioral impact, and parameter provenance. There is no missing information an agent needs to correctly invoke this tool.

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

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

The input schema already provides full descriptions for all three parameters (100% coverage), giving a baseline of 3. The description adds marginal value by explicitly stating the purpose of includeContext ('appends the tactical context') and reminding the agent to obtain combatant IDs from combat-get, which reinforces schema content without contradicting it.

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 ('Jump directly to'), a specific resource ('a specific combatant's turn'), and explicitly differentiates from sibling tools by noting it does NOT cycle through intermediate turns or increment the round. This makes its purpose unmistakable and distinct from combat-next-turn.

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 directs when to use this tool over alternatives: 'Use this instead of repeated combat-next-turn calls to avoid triggering round-based effects.' It also names the source of required IDs ('Get combatant IDs from combat-get'). Clear and actionable 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 indicate this is not read-only and not destructive. The description adds behavioral detail by stating it sets round 1, turn 0, returns the combat state, and that includeContext appends tactical context (combatant position, nearby enemies, line of sight, ASCII map). This goes beyond the schema and gives agents a clear picture of the tool's effects.

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

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

The description is compact, front-loaded with the core action and prerequisites, and every clause adds useful information. No filler or redundant restatement 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?

The description covers the essential usage prerequisite, the initial state, and return behavior. With no output schema, the note about returning combat state and tactical context is valuable. A minor gap is that it doesn't mention what happens if combatId is omitted and no active combat exists, but the schema already covers the fallback behavior.

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 value by elaborating on includeContext: it explains the default (true) and exactly what tactical context is appended. It also reinforces that combatId can be omitted to use the active combat, matching the schema's description.

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: 'Begin combat (round 1, turn 0).' It clarifies the initial state and the ordering prerequisite ('Call AFTER adding combatants and rolling initiative'), which clearly distinguishes this from sibling tools like combat-create, combat-add-combatant, and combat-roll-all-initiative.

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?

Explicit sequencing is provided: 'Call AFTER adding combatants and rolling initiative.' This gives a clear condition for when to use the tool. It does not name specific alternatives or explain when not to use it, but the prerequisite is strong 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 indicate this is not read-only and not idempotent, and the description adds useful behavioral nuance: passing hidden sets the state explicitly, while omitting it flips the current state. This clarifies the non-idempotent toggle behavior beyond the bare 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?

Two front-loaded sentences convey the action, purpose, and the critical set-vs-toggle distinction with no wasted words. 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 three-parameter tool with no output schema, the description plus schema covers the required combatantId, optional hidden semantics, and combatId fallback described in the schema. It could add a note about the return value, but nothing essential is missing 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%, so all three parameters are already documented in the schema. The description restates the hidden/toggle behavior rather than adding new parameter-level meaning, which matches the baseline for complete 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 uses the specific verb pair 'Set or toggle' with the clear resource 'a combatant's visibility to players', then grounds it with concrete use cases (hidden enemies, invisible creatures, surprise). No sibling tool covers this visibility behavior, so it is readily distinguishable from the combat sibling set.

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 operational context: use this to hide or reveal combatants to players, with examples of when that matters. It does not name explicit alternatives or exclusions, but there is no closely competing sibling tool for this action, so the context is sufficient.

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 read-only and idempotent, and the description adds useful behavior beyond that: version-dependent execution ('On bridge module 8.11.0+ the selection happens inside Foundry; on older modules the full pack is fetched'), pagination behavior, and the AND combination of types and ids. No contradiction with annotations 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?

Every sentence earns its place: purpose, prerequisite, parameter semantics, version behavior, pagination, and alternative routing. The most important usage facts are front-loaded, and there is no fluff 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 read-only browsing tool with no output schema, the description covers all six parameters, pagination, filtering, batching, version-dependent behavior, and sibling-tool distinctions. Nothing essential to invoking the tool 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?

Although schema coverage is 100%, the description adds meaning not present in the schema: 'types+ids combine with AND,' ids are for batch-fetching in one call, and it gives a concrete example ('every item a class grants, taken from uuid-resolve output'). This materially helps an agent construct correct calls.

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: 'Browse the contents of a compendium pack. Lists documents (monsters, items, spells, etc.).' It also differentiates itself from nearby siblings by explicitly pointing to compendium-list for pack discovery, compendium-document-get for single-document fetching, and the dnd5e/pf2e filter tools for structured stat filters.

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 explicit routing guidance: 'Use compendium-list first to find the packId,' 'instead of N compendium-document-get calls,' and 'For structured stat filters... prefer dnd5e-compendium-filter-* / pf2e-compendium-filter-* instead.' This tells the agent when to use this tool and when to choose a clear alternative.

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, so the safety profile is covered. The description adds the key behavioral detail that actors are transformed into statblocks while other types return core fields plus system data, which is meaningful 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?

Three sentences with no filler: the first states purpose and output behavior, the second routes to alternatives, and the third tells how to find the required ID. The most important information 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 read-only tool with two well-documented parameters, the description fully covers what the agent needs: what the tool returns, how it formats different document types, and how to find inputs. No output schema exists, but the description compensates by describing the return shape.

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 packId and documentId. The description adds value by telling the agent how to source document IDs via compendium-browse and clarifying that filter tools return UUIDs, which helps populate parameters correctly.

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 ('Get a compendium document') and immediately clarifies it returns a readable summary rather than raw data. It distinguishes itself from compendium-document-get-raw and uuid-resolve, so an agent can tell them apart without opening schemas.

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 routing guidance: use this tool for readable summaries, use compendium-document-get-raw for complete raw JSON, use uuid-resolve when already holding a UUID, and use compendium-browse to find document IDs. This fully covers when to use the tool versus its alternatives.

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 and destructiveHint=false, but the description adds valuable context beyond that: it specifies that the tool returns complete raw JSON, including all system fields, which informs the agent about the response's nature and completeness. This goes beyond the annotations without contradicting them.

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 redundancy. The core purpose ('Get the complete raw JSON data') is front-loaded, followed by a concise usage guideline. 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?

For a simple retrieval tool with two clearly documented parameters and annotations covering safety, the description is nearly complete. It clearly states what the tool returns and when to use it. The only minor omission is the lack of mention of potential errors or size concerns, but these are not critical for agent selection and 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%: both packId and documentId have clear descriptions in the input schema. The tool description does not add any additional parameter semantics beyond what the schema provides, which matches the baseline for high 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 clearly states the action ('Get the complete raw JSON data') and the resource ('compendium document'), explicitly mentioning 'including all system fields'. It differentiates from the sibling compendium-document-get by the word 'raw', making the tool's specific purpose 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 provides explicit guidance on when to use the tool: 'Use this when you need the full statblock data for calculations or detailed information.' This gives clear context but does not explicitly mention alternatives or when not to use it, though the sibling compendium-document-get is implied as the more structured alternative.

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, and non-destructive behavior. The description adds context about the purpose and the discovery flow, but does not mention the optional type filtering or that the listing can be scoped by document type. Still, it adds value beyond annotations without contradicting them.

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

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

Two sentences with no wasted words. The purpose is front-loaded, followed by a brief explanation and a clear next-step pointer. Highly efficient.

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

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

For a simple list tool with one optional parameter and no output schema, the description is largely complete. It covers the main use case and routing. A minor gap is the lack of mention that the 'type' parameter can filter results, though the schema documents this. The description could also state what the response contains (e.g., pack names and IDs), but that is not critical.

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% for the single optional 'type' parameter, which has an enum and description. The description does not add any additional parameter meaning beyond what the schema provides, so the baseline of 3 applies.

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 clearly states the verb 'List' and the resource 'compendium packs', and explicitly contrasts with compendium-browse ('use compendium-browse to see their contents'), making the tool's role unambiguous among many compendium-related 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?

Provides explicit guidance: 'Use this to discover what compendiums are available, then use compendium-browse to see their contents.' This tells the agent exactly when to use this tool and points to the next appropriate action.

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?

While annotations already indicate read-only, idempotent, and non-destructive behavior, the description adds rich behavioral details: name matches win and skip content scanning, content matches include ~200-char snippets, packs are scanned lazily in order and results are unsorted, and specific error messages for unknown or non-journal packs. This goes well 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 well-structured with clear sections (main purpose, WHEN TO USE, WORKFLOW, SEMANTICS) and is front-loaded with the core purpose. Every sentence adds value; there is no fluff or redundancy.

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

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

Given the tool's complexity (5 parameters, no output schema), the description provides everything an agent needs: how to construct queries, interpret results (page uuid, matchedIn, snippet), handle ordering, and understand error conditions. It also references the uuid-resolve workflow for retrieving full text. 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?

The input schema already has 100% description coverage, but the tool description adds extra semantics not in the schema: case-insensitive substring behavior, default limit of 25, lazy scan order, the meaning of matchedIn and snippet behavior, and error handling for packIds. It enriches each parameter's meaning beyond the schema.

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

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

The description clearly states it performs full-text search inside JournalEntry compendium packs, matching page names and content. It distinguishes itself from compendium-search, which only sees document names, making its unique purpose 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 includes a dedicated WHEN TO USE section with concrete examples (e.g., 'grappled condition' → query 'grappled', pageTypes ['rule']) and explicitly names the alternative compendium-search and why this tool is preferred for page-level content. It also explains when to use searchContent=false and how to chain with uuid-resolve.

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 adds meaningful behavioral context beyond annotations: it only matches names, it scans ALL compendiums, and it does not see journal page content. This 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?

The description is efficiently front-loaded with the core purpose, then uses a short 'Useful when' clause to set context, and then routes to alternatives. Every sentence earns its place and there is no redundancy or 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, idempotent search tool with four well-documented parameters and no output schema, the description is complete enough for correct invocation. It states scope, matching semantics, limitations, and explicit alternatives, leaving no material gap for an agent deciding whether and how to call 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 description coverage is 100%, so the baseline is 3 and the schema already documents each parameter. The description reinforces that query matches names only, which clarifies the query parameter's semantics, but it does not add significant parameter-level detail 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 a specific verb and resource: 'Search for documents across ALL compendiums by name.' It also clearly differentiates itself from sibling tools by stating what it does not do: structured filters belong to dnd5e/pf2e filter tools, page-content text belongs to compendium-page-search, and UUID lookups belong to uuid-resolve.

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

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

The description gives explicit when-to-use guidance ('don't know which compendium it's in'), explicit when-not-to-use guidance ('Name matching only'), and names concrete alternatives for structured filters, page-content searching, and UUID-based lookups. No inference is required.

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?

Even with readOnlyHint and idempotentHint already set, the description adds substantial behavior: documents lacking a filtered field are silently excluded, pagination semantics (limit, offset, total, hasMore), result shape ({name, uuid}), and follow-up tools (uuid-resolve, compendium-browse). It also discloses the module version requirement. 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 long but tightly organized into CRITICAL DATA FORMATS, SEMANTICS, RESULTS, and EXAMPLES, with the core purpose front-loaded. Every section supplies necessary operational detail rather than padding, and the examples concretely demonstrate valid filter shapes.

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 13-parameter filter tool with no output schema, the description covers what is needed to call it correctly: filter semantics, edge cases, pagination behavior, return shape, and follow-up resolution. The annotations already cover the safety profile, and the description fills the remaining operational gaps completely.

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 has 100% parameter coverage, the description adds critical meaning beyond it: the exact valid CR set including the '1/4' -> 0.25 conversion and rejection of 0.3, size short codes, level applying only to type 'character', and the exclusion of world-only filters. It also explains range inclusivity and AND/OR combination, which the schema alone does not fully convey.

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 ('Search COMPENDIUM packs'), a clear resource (actors), and the D&D 5e structured-filter scope. It explicitly distinguishes itself from actor-filter (world actors) and compendium-search (plain name lookup), so an agent can separate it from near-names without inspecting schemas.

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 explicit usage boundaries: dnd5e worlds only, compendium packs only, and names the alternatives for other cases ('Compendium counterpart of actor-filter', 'for a plain name lookup use compendium-search'). It also states the semantic model (AND/OR, ranges, limits) that governs correct use.

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 include readOnlyHint and idempotentHint, which are consistent with the description. The description adds critical details like rarity casing, spellLevel semantics, price/weight formats, and the exclusion of documents lacking filtered fields. It also mentions limit/offset and the response structure. No contradiction.

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

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

Well-structured with clear sections for critical data formats, semantics, and examples. A bit long but dense with essential information. The examples are particularly useful.

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 explains the response format ({name, uuid} entries, total, hasMore) and provides follow-up tool suggestions. It also notes the bridge module requirement. For a complex filter tool with 14 parameters, this 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 description coverage is 100%, but the description significantly adds value by explaining filter combination (AND/OR), range inclusivity, and the special note that spellLevel only affects spells. It also provides examples that clarify parameter usage beyond the bare schema.

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

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

The description clearly states it searches compendium packs for items with structured filters, specifying it's the compendium counterpart of world-item-filter. It lists the types of items covered (gear, spells, feats, class features) and distinguishes it from other tools.

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

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

Provides clear context on when to use (searching compendium items) and mentions the compendium counterpart relationship. Does not explicitly list alternatives or when-not-to-use, but the scope 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?

Annotations are all false, so the description carries the full burden, and it delivers: it discloses that automation hooks run, dialogs are not suppressed, Midi-QOL auto-resolves attacks/AC/damage, and HP loss is applied. This goes well beyond annotations and warns about the observable side effects of activation.

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?

Every sentence adds distinct information and the most important purpose/contrast is front-loaded. The length is justified by the complex spatial/AoE instructions; nothing reads as 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 high-complexity combat tool with no output schema, the description covers purpose, prerequisites, coordinate math, target requirements, and sibling selection. An agent has enough to invoke it correctly and understand expected in-world effects.

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 already 100%, so baseline is 3, but the description adds crucial usage semantics: targetTokenIds are required for attacks, templatePosition has different meanings for circle vs cone/line, and provides concrete formulas for direction and pixel coordinates. It also clarifies spellLevel upcasting with an example, which is not 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?

Open with 'Activate an item with full Foundry automation' and immediately names Midi-QOL hooks, making the action and resource clear. It explicitly distinguishes itself from sibling dnd5e-item-use by noting that this version does not suppress hooks or dialogs. This is a specific verb+resource with clear differentiation.

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?

States when to use it: 'Use for combat actions' and 'Prefer this over dnd5e-item-use when targets, templates or automation matter.' It also names the alternative and gives the deciding condition, plus points to scene-get and item-list for prerequisites. No ambiguity remains about 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 discloses that dialogs are suppressed and that it returns the raw use result as JSON, which are behavioral traits. However, it does not explicitly state the side effects of using an item, such as whether consumables are actually consumed or spell slots are expended. Since all annotations are false (readOnlyHint, destructiveHint, idempotentHint), the description carries the full burden, and it only partially covers the behavioral implications. It mentions the consume parameter indirectly through the schema but not in the description itself. This is a moderate gap.

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 plus the differentiation clause, all front-loaded with the purpose and usage guidance. There is zero wasted text; every sentence earns its place by either stating what the tool does or when to use it. The structure is efficient and scannable.

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 7 parameters and no output schema, the description covers the essential contextual information: what it does, when to use it, and what it returns. It does not explain error cases or prerequisites (e.g., the actor must own the item), but these are fairly obvious from the domain. The differentiation from the sibling and the note about 'without targets' covers the main usage constraints. Given the complexity, this is reasonably complete, though it could mention that using an item may have permanent game-state effects.

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 has 100% description coverage for all 7 parameters, so the schema already documents each parameter's meaning. The description adds minimal additional parameter semantics—it mentions the item types supported and the 'dialog-free' nature, but does not clarify parameter interactions or provide examples. This is exactly the baseline where the schema does the heavy lifting, so a 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 clearly states the tool's action (use an item via item.use()), the resource (actor's inventory), and the scope (consumables, spells, weapons, features). It also explicitly differentiates from the sibling dnd5e-item-activate by naming the alternative and the conditions that select it. This makes the purpose unambiguous and distinct from similar tools.

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

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

The description provides explicit usage guidance by stating 'CHOOSING: this tool for quick, dialog-free usage without targets; dnd5e-item-activate when targets, AoE templates, or automation modules (Midi-QOL) matter.' This tells the agent exactly when to use this tool versus the alternative, and also implies when not to use it. This is explicit and actionable.

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 only negative hints (readOnly=false, etc.), so the description adds needed behavior: it is a raw check without skill proficiency)Skip and results appear in Foundry chat. It does not detail the full roll formula, but the key output modality is disclosed.

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 cover the action, use case, and output location with no redundancy or filler. Every sentence earns its place and the core identity 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 2-parameter roll tool with a complete schema and no output schema, the description adequately covers what is rolled, when to use it, and where results are displayed. Together with sibling names, an agent has enough context 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?

The schema already documents both parameters completely: ability enum with code expansions and actorId source. The description adds no additional parameter detail beyond what the schema provides, 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 states a specific verb and resource: 'Roll raw D&D 5e ability check' with the qualifier '(no skill proficiency)'. It clearly differentiates from skill-based rolls and related siblings by noting when no skill applies.

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 provides usage conditions: 'Use for contested checks or when no skill applies.' The exclusion of skill proficiency implies when not to use it, but it does not name an alternative tool such as dnd5e-roll-skill directly.

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 positive safety signals: readOnlyHint=false, no idempotency or destructivity hints, so the description carries the behavioral burden. It usefully scopes this tool to the attack roll only, but it does not say what the call returns, whether it posts to chat, or which game rules such as advantage and modifiers are applied.

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, prerequisite, and alternative routing with no filler. The most important information 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?

For a simple two-parameter tool, the description plus schema is nearly sufficient: it explains the prerequisite and the boundary between attack and damage. It is slightly incomplete because there is no output schema and the description does not say what the agent should expect after the roll resolves.

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 both parameters already have clear descriptions, so the baseline is 3. The description reinforces that itemId comes from actor-get, but adds no genuinely new meaning beyond what the schema already states.

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 action and resource: 'Roll attack with a weapon/spell'. It also distinguishes this tool from dnd5e-item-use by noting that the full sequence (roll + damage if hit) belongs to that sibling, so an agent can tell them apart immediately.

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 an explicit prerequisite: 'Use actor-get FIRST to find itemId'. It also states the exact condition that should route an agent to dnd5e-item-use: 'For full attack sequence (roll + damage if hit)'. This is actionable and unambiguous about when this tool is the right choice.

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 non-read-only and non-idempotent, and the description consistently says it performs a damage roll. However, it does not disclose side effects such as chat output, resource consumption, or whether a result is returned, so it adds only modest 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 tightly written sentences with the purpose front-loaded and the usage sequence following immediately. There is no filler or repetition of schema 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 simple three-parameter roll tool with no output schema, the description covers the required prerequisite, the triggering condition, and the critical-case behavior. An agent has enough information to call it at the correct point in the attack flow.

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 describes all three parameters with 100% coverage, establishing a baseline of 3. The description goes further by explaining how to obtain itemId via actor-get and by clarifying the critical parameter's role in a crit flow, adding value 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 names the exact verb and resource ('Roll damage for a weapon/spell') and ties the action to the attack-then-damage flow. This clearly distinguishes it from dnd5e-roll-attack and other roll tools in the sibling list.

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

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

It explicitly says to call after dnd5e-roll-attack confirms a hit, and gives the critical alternative ('set critical=true for crits'). It also provides a prerequisite ('Use actor-get FIRST to find itemId'), though it does not contrast with other item-usage tools like dnd5e-item-use.

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 are all false/neutral, so they do not disclose much about side effects. The description adds useful behavioral context by stating that results appear in Foundry chat, which tells the agent the tool produces visible game-state output rather than just returning a value. This is meaningful 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?

Three short sentences, each earning its place: the first states the core action, the second gives the triggering use case, and the third gives a necessary prerequisite. No filler or redundant 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 simple two-parameter roll tool with no output schema, the description covers the action, when to use it, a key prerequisite, and where results go. It is sufficiently complete for an agent to invoke it correctly; a minor gap is that it does not describe what happens on invalid actor IDs or whether the save is automated against a DC, but that is not essential for selection and 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 coverage is 100%, and the ability parameter already includes a full enum with expanded descriptions. The description adds workflow guidance ('Use actor-list first to find actorId') but does not enrich parameter semantics beyond what the schema already 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?

The description opens with a specific verb-resource pair, 'Roll D&D 5e saving throw,' and clarifies the domain enough to distinguish it from siblings like pf2e-roll-save, dnd5e-roll-ability, and dnd5e-roll-skill. The phrase 'resisting spells, traps, or effects' also helps identify saving throws versus ability checks or attacks.

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 to use the tool: 'Use when resisting spells, traps, or effects.' It also gives a practical prerequisite, 'Use actor-list first to find actorId.' However, it does not explicitly say when not to use it or name an alternative roll tool, so it stops 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 indicate it is not read-only and not destructive. The description adds that results appear in Foundry chat and that actorId must be obtained from actor-list, providing useful behavioral context beyond what annotations supply.

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 waste, front-loading the purpose and including essential usage and output details. No redundant or vague language.

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, it covers the purpose, output location, and prerequisite. Everything an agent needs to invoke it correctly 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?

Schema fully documents both parameters with descriptions and enums. The description adds a specific instruction for obtaining actorId (use actor-list), which goes beyond the schema and adds value.

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 (roll) and resource (D&D 5e skill check), clarifies it is for ability checks with proficiency, and mentions the output location (Foundry chat). This clearly distinguishes it from sibling tools like dnd5e-roll-ability and dnd5e-roll-save.

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 an explicit condition for use ('ability checks with proficiency') and a prerequisite ('Use actor-list first to find actorId'). While it doesn't name alternative tools directly, the context implies when not to use it, making it sufficiently clear.

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 this is a write operation and not idempotent, so the description does not need to restate that. It adds useful behavioral nuance by noting that 'values are strings' and that 'paths are dnd5e; other systems differ', which helps an agent anticipate system-specific failures or path-format issues. The worked example also clarifies the change-mode semantics.

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: two sentences plus a thin JSON example. It front-loads the core action, then provides a detailed illustrative example that anchors the parameter semantics. No words are wasted, and the system-specific caveat is packed into the final clause without bloat.

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 8 parameters, nested objects, and no output schema, the description gives enough context to invoke it correctly: it explains what the tool does, provides a realistic changes payload, and warns about system-specific path differences. It does not describe the return value or error behavior, but those are less critical for a create operation and the schema already documents all parameters.

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 value beyond the schema by giving a concrete example of the changes array structure, clarifying that mode 2 in the example means a +2 AC bonus, and warning that data paths are dnd5e-specific. This practical elaboration helps an agent construct valid parameters without merely restating 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: 'Add a custom active effect to an actor', immediately distinguishing it from sibling tools like effect-update, effect-delete, and effect-list. It further clarifies scope with 'buff, debuff, custom condition' and gives a concrete dnd5e example that leaves no ambiguity about what the tool does.

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

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

The description establishes clear context: this tool is for creating custom active effects on actors, which separates it from effect-update and effect-delete. It does not explicitly name sibling tools or give when-not-to-use guidance, but the 'custom' qualifier and the create-versus-update phrasing imply the appropriate use case.

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, readOnly=false, and idempotent=false, so the safety profile is carried by structured data. The description adds the 'active effect' scoping but does not disclose additional behavioral details such as permanence or behavior with inactive effects. No contradiction with annotations 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?

Two short sentences with no wasted words. The core purpose is front-loaded, and the necessary prerequisite is stated immediately after. 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?

This is a simple deletion tool with two fully documented parameters, annotations covering destructive behavior, and no output schema needed. The description provides the necessary workflow prerequisite, making it complete 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?

Schema description coverage is 100%, and both parameters are clearly documented with names and descriptions. The description reinforces the effect-list prerequisite but does not add significant meaning beyond the schema, so a 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 action ('Remove an active effect') and the target resource ('an actor'), making the tool's purpose immediately clear. It also names the prerequisite workflow with effect-list, which helps distinguish it from effect-update or effect-toggle-status.

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 the agent to use effect-list first to find effect IDs, giving concrete workflow guidance. It does not explicitly contrast this with effect-update or effect-toggle-status, but the removal purpose and prerequisite are clear 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'active effects' scoping and explains what effects do in general, but it does not disclose additional behavioral details such as error behavior (e.g., missing actor) or return structure. With annotations in place, this is a reasonable middle score.

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

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

Two sentences with no filler. The first sentence front-loads the primary action and scope; the second adds useful conceptual context about effects. 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?

For a single-parameter read-only tool with annotations carrying the safety profile, the description is adequate. It defines the return scope ('all active effects') and gives examples of effect types. It lacks an explicit return format, but no output schema exists and the simplicity of the tool makes this a minor 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 actorId parameter is already fully documented. The description does not add extra semantic detail beyond what the schema provides, which matches the baseline expectation for high 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 ('Get') and resource ('all active effects on an actor'), and enumerates the kinds of effects returned (conditions, buffs, debuffs, custom). This clearly distinguishes it from sibling mutation tools like effect-create, effect-delete, effect-update, and effect-toggle-status, which all alter effects rather than list 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 clearly implies when to use this tool: any time you need to see all active effects on an actor. It does not explicitly name alternatives or add exclusions, but the scope is unambiguous and read-only intent is clear, so an agent can infer the correct context without confusion.

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 signal a non-read-only, non-destructive mutation, and the description adds the key dnd5e-only restriction plus the concrete add/remove semantics and a list of core status IDs. There is no contradiction, and the extra behavioral context is useful but not exhaustive.

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 most important selection criteria (system restriction and PF2e alternatives) are front-loaded in the first sentence. The status ID list is the only substantial addition and is directly useful for invocation, with no redundant 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 simple toggle tool with four well-documented parameters, the description supplies the system scoping, alternative routing, and valid status IDs needed to call it correctly. No output schema exists, but the operation's return value is not essential for selection or 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 coverage is 100%, so the schema already documents all parameters. The description adds value by enumerating the core D&D 5e statusIds and giving examples, which is especially helpful because no enum is defined 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 a specific verb and resource: 'Toggle a D&D 5e condition/status on an actor.' It also disambiguates from PF2e sibling tools by naming pf2e-set-condition and pf2e-remove-condition, so an agent can distinguish this from the large sibling list.

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

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

It gives an explicit system constraint ('dnd5e worlds only') and explicit direction for PF2e worlds, naming the correct alternative tools. This leaves no ambiguity about when this tool should be selected over its closest 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 indicate this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the constraint that it updates 'active' effects, which is useful context. However, it omits important behavioral details such as the fact that the 'changes' array replaces existing changes (only in the schema) and that duration is also updatable, which is not mentioned in the description.

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

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

The description is a single, concise sentence that is front-loaded with the core action and scope ('Update an existing active effect on an actor'). It lists the key modifiable fields without redundancy, 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?

Given the tool has 7 parameters, nested objects, and no output schema, the description is quite brief. It does not mention that duration can be updated, nor does it explain that the changes array replaces existing changes (a potentially surprising behavior). The agent would need to read the schema to fully understand the tool's semantics, so the description is only partially complete for this complexity level.

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 fully documents all parameters. The description provides a high-level summary of what can be modified but omits duration and does not add per-parameter meaning beyond the schema. It also does not explain the replacement semantics for 'changes', which is described in the schema but not reinforced.

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 updates an existing active effect on an actor and lists the modifiable fields (name, icon, disabled state, changes). This distinguishes it from siblings like effect-create, effect-delete, effect-list, and effect-toggle-status, which have different purposes.

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 the tool is for updating existing effects but does not explicitly contrast with alternatives or state when not to use it. It does not mention effect-toggle-status for toggling disabled state or effect-create for new effects, leaving the agent to infer the appropriate context from the schema and tool names.

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 mutation implied by readOnlyHint=false, the description adds the key behavioral invariant that Foundry maintains separate folder trees per document type, and it defines parentId's nesting/root semantics. It doesn't describe return value or failure modes, but annotations already signal non-read-only behavior, lowering the burden.

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: the first states the core action and object; the second explains the two contextual behaviors that matter for correct invocation. No filler.

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

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

Given six parameters fully described in the schema and no nested objects, the description supplies the missing system-level context (type separation, nesting, root omission) needed to call the tool confidently. The only notable omission is the response/return behavior, which is not covered because no output schema exists, but the call itself is fully specified.

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 schema already documents all six parameters. The description adds non-redundant meaning for type (separate tree per type) and parentId (nests inside another folder; omit for root), helping the agent map those fields correctly.

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 action – 'Create a folder of the given document type' – and differentiates from sibling folder-delete/get/list/update by naming the creation operation. The per-type folder-tree note further clarifies what a folder creation means in Foundry.

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 makes the invocation context clear: use when creating a new folder of a known document type, including the root-vs-nested choice via parentId. It does not explicitly name alternatives like folder-update, but no competing create tool exists among siblings, so the lack of exclusion is not a real gap.

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 by disclosing irreversibility ('Permanently delete'), cascade defaults, orphan-to-parent/root behavior, and the dangerous combination of both flags. The destructiveHint=true annotation is consistent and the description adds meaningful behavioral detail about what gets destroyed.

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-structured: it states the core action first, then explains flags and defaults, and ends with a high-visibility warning. Every sentence earns its place, and the bold warning is appropriately emphasized without bloat.

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, this description fully covers what an agent needs to know: audacity of the operation, default behavior for sub-folders and documents, how to opt into recursive deletion, and a safety warning. FolderId is already documented in the schema, so no critical context 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 value beyond the schema by explaining how the two boolean flags interact as a pair, including the combined consequence of both being true. It also reinforces default behavior and the warning about data loss, which the schema descriptions only hint at individually.

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 action and resource: 'Permanently delete a folder.' It clearly differentiates from sibling folder tools (folder-create, folder-get, folder-list, folder-update) by focusing on deletion and cascade behavior. The two flags and their roles are explicit.

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 conveys when this tool applies: when a folder needs permanent deletion. It does not explicitly compare against alternatives, but it does give important usage context by explaining default orphan behavior and cautioning that setting both flags can wipe a lot of data. This is clear context though not a formal when/when-not statement.

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 readOnly/idempotent annotations, it discloses that both flags default to false and, crucially, that includeContents is not recursive despite the subfolder option. The parenthetical 'fetch each subfolder for its own contents' exposes a non-obvious behavior an agent must know before invoking.

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 carry the essential operation, flag semantics, defaults, and the nested-content caveat with no filler. The headline verb/resource appears first, and each 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 single-folder fetch, this covers the required folderId, both optional behaviors, defaults, and the non-nested nuance. It does not describe the shape of the base folder object or not-found behavior, but with no output schema those are minor gaps for this small tool.

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

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

The schema already documents all three parameters, so the baseline is 3. The description adds the default-false behavior for both booleans and explains how the two flags interact, which goes beyond the field-level schema text.

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 'Get a single folder', which names a specific verb and resource and distinguishes it from folder-list and folder-create. It also clarifies the scope of the two optional include flags, so an agent immediately knows this returns one folder, optionally with its subfolder tree or direct document IDs.

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 conditional guidance: includeSubfolders=true returns the full tree, includeContents=true only direct document IDs, and it explicitly tells the agent to fetch each subfolder when nested contents are needed. It stops short of naming sibling alternatives such as folder-list for retrieving multiple folders, so it is not a full 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral context by naming the output fields, stating the optional document type filter, and explicitly excluding tree structure and contents. This goes beyond what the annotations provide, though it does not discuss pagination or ordering.

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 tightly written sentences, with the core purpose and output shape front-loaded. The second sentence efficiently states exclusions and routes to the relevant sibling tool. Every phrase earns its place without 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 list endpoint with one optional enum parameter and no output schema, the description gives enough to invoke it correctly: what it lists, what fields are returned, the optional filter, and what it intentionally omits. The annotations cover safety, and the schema covers parameter semantics, leaving no critical 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?

The sole parameter is fully documented in the schema with an enum and a detailed description of what each type represents and what omitting it does. The tool description merely paraphrases "optionally one document type" without adding new semantic information. Schema coverage is 100%, 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?

The description uses the specific verb "List" with resource "folders in the world" and states the returned fields (id, name, type, parent). It explicitly distinguishes itself from folder-get by noting it does not return a tree or contents. This is unambiguous and differentiates from sibling folder tools.

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

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

The description clearly states when to use this tool versus folder-get: for a flat folder listing, not subfolders or contents. It also explains the optional type filter, directing agents toward the right invocation. No competing list tool is named, but the primary routing decision is fully covered.

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 beyond the annotations by detailing a nuanced tri-state behavior for parentId, explaining what happens when parentId is omitted, set to a string, or null. It also discloses that a string parentId combined with clearParent: true is rejected, which is exactly the kind of behavioral edge case an agent needs to know.

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 clause states the tool's purposeaving, and the remainder focuses entirely on the one genuinely tricky parameter interaction. Every sentence earns its place, with no padding 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?

All seven parameters are already documented in the schema, and the description resolves the only ambiguous behavior around parent reassignment. It does not mention return values or error handling, but given the absence of an output schema and the schema's complete parameter coverage, this is sufficient for an agent to invoke the tool correctly.

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

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

Even though schema coverage is 100%, the description adds meaningful parameter semantics by clarifying the interaction between parentId and clearParent特效 — specifically that omitting both leaves the parent unchanged and that string+true is invalid. This is extra value beyond the schema's property-level descriptions.

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

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

The description opens with 'Update a folder' and immediately enumerates the mutable fields: name, parent, color, description, or sort. This clearly identifies the verb and resource, and the sibling list contains folder-create/delete/get/list, so there is no ambiguity about which operation this tool performs.

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?

Though it does not explicitly name alternatives like folder-create or folder-delete, the usage context is unambiguous: this tool modifies an existing folder. The tri-state explanation also provides clear guidance on how to leave the parent unchanged versus moving to root.

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 idempotentHint=true and destructiveHint=false. The description adds context about the scope (all connected clients) and the specific effect on the session pause indicator, which goes beyond the annotations. No contradictions.

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

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

Two concise sentences with zero fluff. The primary action and scope are front-loaded, followed by the alternative. 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?

For a zero-parameter tool with annotations covering safety and idempotency, the description fully equips an agent to call it correctly. It states what happens, to whom, and how to reverse it. No output schema is present, so return-value details are unnecessary.

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 baseline is 4. The description adds no parameter-specific information because there are none; it correctly focuses on the action and scope.

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 exact verb 'pause' and resource 'game', specifies scope 'all connected clients', and clarifies the effect 'freezes the session pause indicator'. Clearly distinguishes from the sibling 'game-resume' which reverses the action.

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 names the complementary tool 'game-resume' and the condition for using it ('to unpause'), providing clear guidance on when to use this tool vs the alternative.

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 and idempotentHint, so the safety profile is covered. The description adds value by naming the underlying property (game.paused) and specifying the return format (paused: true/false), giving the agent more behavioral context than the annotation metadata 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?

Two short sentences deliver all essential information with no fluff. The action, target field, and return value are each present and front-loaded.

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

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

For a zero-parameter, read-only status tool, this description is fully complete. It covers what the tool does, the relevant state field, and the exact returned value, while the annotations cover side-effect safety. There is nothing an agent needs to know to call it correctly that 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 accepts zero parameters, so there are no parameter semantics to clarify. The baseline for a zero-parameter tool is 4, and the description accurately reflects that no arguments are needed by simply being about a state check.

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 checks the current pause state via a specific verb ('Check') and resource ('game paused'), even referencing the underlying field game.paused. It is immediately distinguishable from the sibling game-pause and game-resume tools because it queries rather than mutates.

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 'Check whether the game is currently paused' makes the read-only usage context clear and implies it should be used to inspect state rather than change it. However, it does not explicitly name alternatives or state when not to use it, such as 'use game-pause to pause the game.'

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 idempotentHint=true and destructiveHint=false, so the core safety profile is covered. The description adds the meaningful scope 'for all connected clients,' but it does not describe what happens if the game is already running or any client-visible effects beyond resuming.

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?

A single sentence conveys the action, the target resource, and the scope without wasted words. The parenthetical 'unpause' usefully reinforces the verb without adding bulk.

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, side-effect-reaching command, the description is complete: it states exactly what happens and who is affected. The no-output-schema case does not create a gap because the return value is unlikely to be central for this simple control action.

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 zero parameters, so there are no parameter semantics for the description to clarify. Baseline 4 is appropriate because no parameter documentation burden 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 uses a specific verb ('Resume (unpause)') and names the exact resource ('the game') affected. It also clarifies scope ('for all connected clients'), making it immediately distinguishable from the sibling game-pause and game-pause-get tools.

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

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

The description explains what the tool does but gives no explicit guidance on when to invoke it or when to choose an alternative. It does not mention preconditions such as the game being paused, nor does it point to game-pause or game-pause-get as related 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?

Annotations already establish readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds behavioral context beyond annotations: it states the output is HTML, and it warns about Foundry VTT stripping <style> tags, implying the returned HTML may include style tags that must be converted to inline attributes. This practical context about output format and constraints adds value 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?

The description is compact and front-loaded: the core purpose is in the first sentence, followed immediately by usage constraints and downstream actions. Every sentence carries essential information, and there is no redundancy with annotations or schema. It's 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 single-parameter retrieval tool with robust annotations (read-only, idempotent), the description fully equips the agent: it explains what the output is (full HTML), how to use it (as style reference, not copy), and what to do next (generate variation, save via journal-page-create with 'text' type). There's no output schema, but the description covers the return value sufficiently for the agent's task. Nothing essential is missing.

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