Foundry MCP

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?

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?

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=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?

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 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?

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?

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?

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?

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.

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

The input schema has one parameter, templateId, with description 'Template ID from handout-template-list' which already fully explains its meaning and source. Since schema_description_coverage is 100%, the description adds no additional parameter-specific information. Baseline 3 is appropriate; the tool description doesn't need to repeat schema content.

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: 'Get the full HTML of a handout template.' It uses a specific verb ('get'), names the resource ('handout template'), and adds that it returns full HTML. This distinguishes it from the sibling handout-template-list, which presumably returns metadata or IDs. The unique purpose is unambiguous.

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

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

Explicit guidance is given: 'Use this as a STYLE REFERENCE — do not copy it verbatim.' It then instructs the agent to generate a unique variation and save via journal-page-create, including implementation details like inline styles because Foundry VTT strips <style> tags. This tells the agent exactly when and how to use the tool, and what to do with the result. No other tool has similar guidance in the sibling set.

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, and idempotentHint=true. The description adds value by specifying that it 'Returns template IDs and descriptions' and implies it does not return full HTML (since it directs to handout-template-get for that). This clarifies the scope of the read operation beyond the annotation's safety profile.

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

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

The description is three concise sentences with no fluff. It front-loads the primary purpose, states the output, and then gives workflow context. Every sentence earns its place, making it easy to scan and understand.

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 is complete. It covers what the tool returns, how it differs from the sibling, and the recommended workflow. Annotations already cover safety, so nothing critical is missing 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?

The schema description for the 'category' parameter is already informative ('Filter by category: wanted-poster, letter, scroll, decree, etc.'), covering 100% of the schema. The tool description does not add additional insight about the parameter, so it meets the baseline but does not exceed 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 clearly states the verb 'List' and the resource 'handout templates', with concrete examples ('wanted posters, letters, scrolls, etc.'). It explicitly differentiates from the sibling 'handout-template-get' by stating it returns only IDs and descriptions, not the full HTML, making the tool's scope 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 workflow guidance: 'Use handout-template-get to read the full HTML. Then generate a unique variation with your own content and save via journal-page-create.' This tells the agent exactly when to use this tool (to browse templates) and what to do next, effectively routing to the correct siblings without 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?

The description contradicts the annotations: it claims 'retries are safe' and that an already-deleted item counts as success, which implies idempotent behavior, while idempotentHint is false. This is a clear contradiction. The description does add transparency about permanence, but the contradiction is a severe issue.

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 core action is front-loaded, followed by a required prerequisite and critical warnings (permanence, retry safety). 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 2-parameter delete with no output schema, the description covers the essentials: how to find the ID, the permanence, and retry behavior. It doesn't discuss errors or side effects, but given the simplicity and annotations, it's largely complete. The idempotency contradiction is noted but doesn't directly detract from this dimension.

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 both parameters already described in the schema. The description reiterates 'from item-list' but adds no new meaning beyond that, so it's at the baseline for high-coverage schemas.

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 ('Remove') and resource ('item from actor's inventory') with a permanent consequence, distinguishing it from update/create tools and other delete tools. It is specific and 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?

Provides explicit sequencing ('Use item-list FIRST to find itemId') and retry guidance ('retries are safe'). It doesn't explicitly state when not to use, but the purpose is clear enough that alternatives aren't needed; the guidance is actionable and context-rich.

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

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

Annotations already mark this as non-read-only and non-destructive, and the description adds useful behavioral details: content must be HTML and a unique folder name is resolved to its ID. It does not go deeper into creation outcomes or error behavior, but the baseline disclosure is adequate.

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 with no filler: the core action, the optional page behavior, and the two cross-references all earn their place.

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

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

For a simple create operation with fully documented parameters, the description plus schema is sufficient to invoke the tool. The only notable gap is not specifying what the successful response returns (e.g., the new journal's ID), and no output schema exists to cover that.

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 explains name, folder, content, and pageType. The description's folder-name resolution and HTML cross-reference add only modest extra value beyond the structured fields.

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 first sentence states a specific action and object: 'Create a new journal entry, optionally with a first page.' That is clear and immediately separates creation from the many journal mutation siblings, though it does not explicitly contrast with journal-update or journal-page-create.

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?

Creation context is implied by the verb and resource, and the description usefully points to journal-page-create for HTML rules. However, it never states when to prefer this tool over journal-update or journal-page-create, and it does not mention how first pages are added after creation.

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, but the description adds valuable context beyond that by disclosing the cascade behavior ('and all its pages') and irreversibility ('This action cannot be undone!'). This gives the agent a clear picture of the operation's consequences.

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

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

Two short sentences with the core action front-loaded and the important warning immediately after. Every word contributes value, and there is no redundancy with the schema or title.

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

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

For a single-required-parameter destructive action with annotations already covering the safety profile, the description provides all needed behavioral context: what is deleted, the cascading scope, and irreversibility. No output schema is necessary for a delete operation, so nothing material 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%, and the journalId parameter is already described as 'The journal ID to delete.' The description adds no additional meaning or constraints for the parameter, so the high-coverage baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Delete a journal entry and all its pages.' This clearly distinguishes it from journal-page-delete and other journal-related siblings by specifying the full scope of deletion.

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 that this tool is for deleting an entire journal entry, not just individual pages, but it never explicitly states when to use it over alternatives like journal-page-delete or journal-update. The destructive warning adds caution but no direct usage conditions.

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 idempotentHint=true, covering safety. The description adds behavioral value by specifying the output includes entry and page counts, which is not evident from the schema or annotations. No contradictions.

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

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

Two sentences with no filler. The first sentence states the core purpose and output; the second provides forward navigation and clarification on where to obtain folder IDs. Perfectly 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 parameterless, read-only listing tool with annotations covering safety, the description fully explains what it returns and how to proceed. It also clarifies the source of folder IDs, removing any ambiguity with folder-list. 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 tool has zero parameters and the schema is fully described (empty). The baseline for 0 params is 4; the description adds no parameter details because none exist, which is appropriate.

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

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

The description states a specific verb and resource ('List journal folders by name with entry and page counts') and distinguishes it from the broader folder-list by specifying it's a journal-specific overview. This clearly differentiates it from sibling tools like journal-list and folder-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 directs the agent to use journal-list next (with or without a folder name) and clarifies that folder IDs come from folder-list with type 'JournalEntry' — making the alternative tool and the selection condition explicit.

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 known. The description adds behavior beyond annotations by specifying the two output modes (plain text vs raw JSON with HTML and metadata) and the default. This gives the agent a clear expectation of what the tool returns without needing to guess.

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 main action and output modes are front-loaded, followed by routing guidance. 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?

Despite no output schema, the description covers the essential return format (plain text or raw JSON) and the parameter behavior. It also provides pointers to sibling tools for ID discovery and page-level retrieval, making it self-sufficient for an agent to call 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 covers both parameters (100% coverage), but the description adds value by explaining the formatAsText parameter's meaning and default ('Default true: pages as plain text (HTML stripped). false = raw JSON with HTML content and page metadata.'). This enriches the schema description, so it's more than just a baseline.

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

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

States a specific verb (get), resource (journal entry), and scope (all its pages) and differentiates between two output formats. It names sibling tools (journal-list, journal-search, journal-page-get) that serve different purposes, so an agent can clearly distinguish it.

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

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

Explicitly instructs when to use this tool vs alternatives: 'Use journal-list or journal-search to find journal IDs; for one page of a long journal use journal-page-get.' This provides clear routing and 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds behavioral context: grouping by folder and returning IDs needed for journal-get, which is useful beyond 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?

Three sentences, each earns its place: purpose, scope variation, and alternative routing. Front-loaded and free of 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 single-parameter list tool, it covers the key aspects: what it lists, how to broaden scope, what it returns, and when to use another tool. It lacks only minor details like output structure or pagination, but these are not critical given the simple nature and annotations.

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 the folder parameter with the same 'omit for all' nuance. The description reinforces but does not add new meaning beyond the schema, so it stays at the baseline 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 uses a specific verb ('List') and resource ('journal entries'), states the grouping behavior, and explicitly differentiates from journal-search. It clearly answers what the tool does and how it differs from its 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?

Provides explicit usage guidance: 'Omit folder to list ALL journals' and directs users to journal-search when the name is known. This clearly indicates when to use this tool versus 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 indicate readOnlyHint=false and destructiveHint=false, so the description doesn't need to cover basic mutation safety. It adds a behavioral detail about Foundry stripping <style> and <script> tags, which is valuable. It doesn't discuss permissions or reversibility, but for a creation tool this is acceptable. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence stating the primary purpose, followed by one sentence with practical guidance. Every word contributes—no filler or redundancy. It is appropriately concise.

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 5 parameters, 2 required, and no output schema, the description covers the main usage scenario (adding text pages with HTML) and points to a template resource. It doesn't mention the return value, but for a creation tool that's minor. It also implicitly differentiates from update/delete siblings. Overall, it is fairly complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant value for the 'content' parameter by explaining how to structure HTML, use inline styles, and link documents. It also mentions handout-template-list as a source of ready-made layouts, which is beyond the schema's simple 'HTML content for text pages'. This elevates the score to 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 ('Add'), a resource ('a page to an existing journal entry'), and differentiates from siblings like journal-create (creates a journal) and journal-page-update (updates a page). It is clear and 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 usage context for text pages: how to use inline styles, link documents via @UUID, and mentions handout-template-list as an alternative for ready-made layouts. It doesn't explicitly state when not to use this tool, but the context for the main text-page case is clear and hints at 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 mark this as destructive, but the description adds the important context that the action cannot be undone. This is genuinely useful behavioral information beyond the structured hints, though it does not mention other effects such as permission requirements or cascading deletions.

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 action is front-loaded, and the irreversibility warning is a valuable addition that fits naturally.

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

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

For a simple delete operation with two well-documented required parameters and no output schema, the description is sufficient. An agent can correctly identify the resource and understand the destructive consequence without additional explanation.

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

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

Schema description coverage is 100%, with both pageId and journalId already described clearly. The tool description adds no additional parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Delete') and resource ('a specific page from a journal'), making it immediately clear what the tool does. It also distinguishes itself from the sibling journal-delete by emphasizing 'specific page.'

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 purpose implies the usage scenario: call this when deleting a journal page rather than a journal itself. However, it does not explicitly state when not to use it, nor does it name alternatives such as journal-page-update or journal-delete.

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

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

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint false, the description adds a new behavioral detail: 'Returns plain text content by default.' This informs the agent of the output format without relying on schema inspection. It does not discuss edge cases like invalid IDs, but that is minor given annotation coverage.

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

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

Two sentences with no wasted words. The core action and key usage context are front-loaded, followed by the default return behavior. 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 read tool with full schema coverage and safety annotations, the description covers the purpose, usage context, and default return format. It does not describe error behavior or the exact structure of the returned output, but given no output schema and the simplicity of the operation, this is acceptable.

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

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

Schema description coverage is 100%, with each parameter documented (journalId, pageId, formatAsText). The description mentions plain text default, which overlaps with the schema's formatAsText explanation, adding no new parameter-level meaning. Thus 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?

The description states a specific action ('Get a specific page from a journal') and identifies the resource (page within a journal). It also distinguishes itself from retrieving the whole journal by noting the multi-page scenario, making it clear how this tool differs from sibling tools like journal-get.

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 'Useful when you only need one page from a multi-page journal' gives a clear context for use. It implies the alternative of retrieving the full journal, though it does not explicitly name that sibling tool or state when not to use it.

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

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

The description discloses the critical replace behavior (content replaces the whole page text) and the need to read first, which is important context beyond the annotations (which do not indicate destructive behavior). It also references HTML rules from create. However, it does not clarify that other fields (src, name) are optional and only updated if provided, which could lead to misinterpretation of partial updates.

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 exceptionally concise and well-structured. Two sentences front-load the core behavior (replace semantics) and reference sibling tools for additional context without redundancy. Every sentence earns its place, making it easy for an agent to parse and act on.

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 incomplete for a mutation tool with no output schema. It doesn't mention the return value, doesn't clarify that only provided fields are updated, and doesn't address non-text pages (e.g., image/video) where content may not be used. This could cause an agent to unnecessarily read a page or send full content when only renaming is desired.

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 all 5 parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful value by explaining the content parameter's role: it replaces the entire page text and must be sent back in full. It doesn't add detail for src and name, but those are self-explanatory from the schema. The extra insight into content 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 clearly states the tool updates a journal page, emphasizing the replace behavior ('content REPLACES the whole page text') and distinguishes it from create/delete/get via explicit references to sibling tools. It is specific about the resource and action, leaving no ambiguity about its 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 provides an explicit workflow: read with journal-page-get, edit, and send full HTML back. It also references journal-page-create for HTML rules, implying when to use this tool vs create. However, it does not explicitly state when not to use it (e.g., for appending) beyond the 'no append' note, and it lacks guidance for non-content updates (like renaming only).

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 description adds value by noting it searches across all folders, is case-insensitive, and returns IDs for subsequent tools. It also includes a performance note ('Faster than listing') which is beyond the annotations. Minor ambiguity remains about whether the search matches both fields simultaneously, but it is not a major 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?

Three sentences with zero waste: the first sentence states the action and scope, the second gives a performance justification, and the third explains the return values. 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 single-parameter, read-only search tool with full schema coverage and safety annotations, the description covers what the tool does, when to use it, and what it returns. No critical information is missing for an agent to invoke it correctly. The absence of an output schema is fine since the description explicitly mentions the IDs returned.

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 query parameter is documented. The description adds meaning by stating the search is across all folders and that the query matches both journal and page names, reinforcing the schema's description. It also clarifies the output usage (IDs for journal-get and journal-page-get), which is beyond schema and aids the agent in chaining 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 states a specific verb ('Search'), resource ('journals'), and scope ('across all folders'), and clarifies it matches by journal name AND page name with case-insensitive substring. It clearly distinguishes from journal-list (which lists all) and other search tools, so an agent can immediately understand the tool's function.

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

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

It explicitly says 'Faster than listing all journals when you know the name,' which indicates when to use it over journal-list. It also mentions that returns are IDs for journal-get and journal-page-get, implying follow-up usage. However, it does not explicitly mention alternatives like compendium-search or state when not to use it, though the given context is sufficient for basic routing.

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 readOnlyHint=false, so the description's 'rename' and 'move' verbs are consistent. It adds useful context by stating 'metadata only' and explaining that a unique folder name resolves to its ID, which goes beyond the schema and annotations.

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

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

The description is a single, dense sentence that front-loads the core action (rename/move) and includes the critical metadata-only caveat. Every clause earns its place with no wasted words.

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

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

For a simple rename/move tool with three parameters and one required, the description covers the main behaviors and the folder resolution nuance. It doesn't mention return values or error handling, but those are not essential given the tool's simplicity and the lack of an output schema.

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

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

Schema coverage is 100% and each parameter has a clear description. The tool description reinforces the folder name resolution behavior but doesn't add meaning beyond what the schema already provides for the parameters themselves, 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?

The description clearly states the tool renames a journal entry or moves it to another folder, and explicitly scopes it to metadata only, distinguishing it from journal-page-update. It names the sibling for page edits, making its 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 clear when-to-use guidance by specifying rename/move operations and pointing to journal-page-update as the alternative for page content. It doesn't explicitly list exclusions, but the reference to the sibling tool is sufficient for an agent to choose correctly.

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