Foundry MCP

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

Annotations declare this is a non-read-only, non-idempotent, non-destructive creation that stays within the world (openWorldHint=false). The description adds that 'system is deep-merged over the defaults', which explains how partial system data is handled — genuine context beyond the annotations. It stops short of disclosing validation errors, required permissions, or what a successful create returns, so not a 5.

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

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

Compact and front-loaded: the core action and examples come first, followed by type constraints, the sibling pointer, and the merge behavior. The type enumeration is a bit dense inline, but every sentence carries information an agent needs before calling.

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

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

For a creation tool with no output schema and full schema coverage, the description supplies the missing decision context: the sibling alternative, per-system type values, and merge semantics. Minor gaps remain around whether creation triggers sheet initialization or defaults, but nothing essential to a correct call is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: the type enum is expanded per game system (including pf2e types like hazard, loot, familiar, army that aren't in the schema text), and it explains that the type 'must fit the game system'. It also clarifies the deep-merge semantics of the system parameter, which the schema leaves as a bare 'additionalProperties' object.

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

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

States a specific verb and resource ('Create an actor from scratch') and enumerates concrete examples (custom NPCs, characters, creatures). It also explicitly distinguishes itself from the sibling actor-create-from-compendium, leaving no ambiguity about which tool builds an actor manually.

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?

Gives an explicit alternative for creating from a compendium monster ('actor-create-from-compendium') and lays out the valid type values per game system (dnd5e, pf2e). The agent knows both when to use this tool and which argument values are legal.

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

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

Annotations already signal that this is a write operation (readOnlyHint=false) and not idempotent, and the description does not add behavioral context beyond 'Import... into the world.' It does not disclose whether repeated imports create duplicates, whether the imported actor is a copy or a reference, or any permission requirements. With no additional behavioral disclosure, the description does not enrich what annotations already provide.

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

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

The description is two sentences with no redundant wording. The core purpose is front-loaded, followed immediately by the essential identifier-mode guidance. Every sentence earns its place.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is two short sentences with zero redundancy. The core action is stated first, and the irreversibility warning follows immediately. Every word adds value; there is no filler or repetition.

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

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

For a single-parameter destructive operation with no output schema, the description covers the essential facts: what it does and its irreversible nature. It could mention what happens if the actorId is invalid or non-existent, but for a simple delete that is a minor gap. The description is adequate for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents the sole parameter (actorId) with its purpose and type. The description does not add any extra meaning about the parameter, such as format or required semantics beyond what the schema states. Baseline 3 is appropriate.

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

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

The description states a specific verb ('delete'), a specific resource ('actor'), and the scope ('from the world'). It clearly distinguishes from siblings like actor-update, actor-create, and actor-get. There is no ambiguity about what the tool does.

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

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

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

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

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

Annotations already cover read-only/idempotent safety, but the description adds genuinely non-obvious behavior: actors lacking a filtered field are silently excluded (PCs have no CR, vehicles no abilities, root-level actors no folder), filters AND across fields but OR within an array, and the response carries total and hasMore. That silent-exclusion rule is exactly the kind of trap an agent would otherwise hit.

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?

Front-loaded purpose sentence, then a CRITICAL DATA FORMATS block, then one concrete example. Given 15 nested parameters, every section carries information an agent needs; 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?

Fifteen nested params, no output schema — yet the description compensates by declaring the return shape ({id, name} entries plus total/hasMore) and the field-availability exclusions. Nothing essential for a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema cannot express: CR must come from the exact set 0/0.125/.../30 with the 1/4->0.25 mapping and 0.7 rejected, ranges are inclusive with min=max for exact match, and a worked example showing combined filters with recursive folder. This meaningfully reduces malformed 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?

States a specific verb and resource ('Search WORLD actors with D&D 5e structured filters'), gives the scope restriction (dnd5e worlds only) and the return shape ({id, name}, paginated), and explicitly names the two sibling tools it is not (actor-list, dnd5e-compendium-filter-actors). An agent can distinguish it from all 100+ siblings immediately.

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

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

Explicit routing: use actor-list when unfiltered, dnd5e-compendium-filter-actors for compendium content, and this tool for filtered world searches. It also tells the caller to chain into actor-get for full stats, which is the key follow-up decision.

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 this a safe, idempotent read, so the description spends its words on non-obvious behavior instead: the statblock follows the dnd5e data model and sections like skills or currency stay empty in other systems. That is a genuinely useful caveat an agent would otherwise misread as missing data. It does not discuss permissions or error cases, which keeps it below 5.

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 what is returned, then downstream dependencies, then the system caveat and the raw-document escape hatch. No filler and no repetition of the schema.

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

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

There is no output schema, and the description compensates by listing the statblock contents and warning that some sections may be empty in non-dnd5e systems. For a one-parameter read tool with full annotation coverage, 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 description coverage is 100% and the single actorId parameter is already documented in the schema as coming from actor-list or actor-filter. The description adds nothing further about the parameter's form or constraints, 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?

States a specific verb and resource ('Get full actor details') and enumerates the returned fields (HP, AC, abilities, skills, speed, proficiency, inventory). It is clearly distinguishable from actor-list and actor-filter, which return collections rather than a full statblock.

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?

Names the condition that selects an alternative: use uuid-resolve with "Actor.<id>" when the raw document is wanted instead of the statblock. It also states the downstream workflow (item IDs are needed by dnd5e-roll-attack, dnd5e-roll-damage, dnd5e-item-use). It stops short of telling the agent to obtain the ID via actor-list/actor-filter, but the schema covers that.

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, non-destructive, so the safety profile is handled. The description adds value beyond that with the hard 200-row cap and the returned field set (name, type, ID), which matters because there is no output schema. It stops short of describing ordering or what happens when the cap is hit.

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 waste. The primary behavior and row cap come first, the escalation path second — front-loaded exactly as an agent scanning tools would want.

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 tool with full annotations, this covers purpose, limits, returned fields, and the alternative. The only gap is the ambiguity around whether the `type` param belongs to this tool or should be delegated to actor-filter.

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 is fully documented in the schema (100% coverage), so the baseline is 3. However, there is mild friction: the description enumerates "creature type" as an actor-filter concern even though actor-list itself has a `type` filter param, which could make an agent second-guess whether to pass it here.

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?

Specific verb + resource ("List actors in the world") plus an explicit scope statement ("plain listing, at most 200 rows"). It names the returned fields and contrasts itself with actor-filter, so an agent can distinguish it from siblings without opening a 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?

It explicitly routes the agent: use this for a plain listing, use actor-filter for anything by name, CR, creature type, size, folder, HP, AC. The when-to-use and the alternative are both named outright rather than 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 only state the safety profile (readOnly=false, idempotent=false, destructive=false). The description adds the crucial behavior the annotations cannot convey: system is DEEP-MERGED, pass only changed paths, and arrays are replaced whole, which is a real data-loss caveat. That is exactly the value-add expected beyond annotations.

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

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

Purpose is front-loaded in the first clause, then merge semantics, then an example, then dnd5e path hints and the damage-tool routing. Every sentence carries distinct information with no filler or repetition of the schema.

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

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

For a 7-param nested-object mutation tool with no output schema, the description covers the hard parts: merge behavior, tokenId scoping, and common paths. The notable gap is that the schema declares zero required parameters and the description never says an actorId or tokenId must be supplied for the operation to make sense.

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 already 100%, so the baseline is 3. The description goes further by illustrating deep-merge semantics for `system` with a worked example and naming common dnd5e paths, plus disambiguating tokenId vs actorId. It doesn't compensate for the odd schema fact that no parameter is required.

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

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

Specific verb+resource: 'Update an actor's name, image, folder, or system data', plus the tokenId scope variant. It explicitly names an alternative (dnd5e-apply-damage) and reaches into the actual mechanic (deep-merge of system), so an agent can tell it apart from actor-create, token-update, and item-update without opening schemas.

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

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

Gives a concrete when-not: 'For HP after damage prefer dnd5e-apply-damage (resistances, temp HP)', and clarifies that tokenId targets one token's own actor instead of actorId. It does not address the potential confusion with token-update for token-level changes, so the routing is good 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 declare it's non-destructive, idempotent, and not read-only. The description adds that changes apply 'for everyone's view' (broadcast effect) and clarifies units. But it omits permission requirements, whether the change is reversible, and what happens if the canvas isn't loaded. With annotations covering safety, 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 sentences, front-loaded with the core action and scope, followed by optional-parameter behavior and sibling contrast. 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?

Complete enough for a niladic-ish (all-optional) view-control tool: purpose, scope, units, parameter omissibility, and sibling alternative are all covered. No output schema exists, so return values needn't be described. Only permission/prerequisite context is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by explaining that all fields are optional and that omitting x/y keeps the centre and omitting scale keeps the zoom, which reinforces the schema's omissibility semantics and clarifies intent beyond the field-level descriptions.

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

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

The description clearly states a specific verb+resource: 'Pan and/or zoom the canvas (canvas.animatePan) for everyone's view.' It also distinguishes units ('in scene pixels, not grid squares') and points to the sibling alternative 'canvas-ping draws attention to a spot instead.' An agent can immediately understand what the tool does and that it affects the shared view.

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 states when to use this tool by explaining pan/zoom behavior and explicitly contrasting with canvas-ping for drawing attention. It also gives usage details about optional fields. However, it doesn't mention prerequisites (e.g., VIEW_CANVAS permission) or when not to use it beyond the single sibling contrast.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes further by disclosing the exact serialization contract (line format for text, field list for JSON), which is real behavioral value an agent needs to consume the output.

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 action and modes, then a compact per-format spec. Every clause carries information about either selection or output shape; nothing is padding.

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

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

With no output schema, the description correctly shoulders the burden of describing returned data for both formats. It is nearly complete; only minor details such as ordering, scope limits, or whether the export can be triggered for a subset of the log are unaddressed.

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 enum is documented, so the baseline is 3. The description earns an extra point by spelling out what each format value actually produces — '[Speaker] Content' per line versus message objects with id, timestamp, author, speaker, content, flavor, isRoll.

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 ('Export the full chat log') plus the two output modes, so the agent can tell it apart from chat-list or chat-send. It does not explicitly name a sibling, but the 'full export' framing is distinct from the incremental chat 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 parenthetical 'session summaries, recaps, archives' implies when this is useful, but there is no explicit when-to-use/when-not guidance and no mention of chat-list as the alternative for paginated browsing. Usage is inferable rather than 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 readOnly, idempotent and non-destructive, so the safety bar is low; the description adds genuinely new context by stating results are plain text with HTML stripped and returned in chronological order, which tells the agent how to interpret the payload. It stops short of describing pagination behavior or how limit interacts with since/before.

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

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

Two dense sentences with the resource, format and ordering stated first and the polling hint last. No filler, and the most load-bearing 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 an 8-parameter, zero-required read tool with full schema coverage and annotations, the description covers purpose, output format and ordering adequately. Minor gaps remain: it never mentions the default limit of 20, the available filters, or that returned messages carry the IDs needed for subsequent since/before calls.

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

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

Schema description coverage is 100%, so every parameter is already documented, and the description's only parameter remark ('since = a message ID to poll') largely restates the schema text. The seven other filters (type, limit, before, search, actorId, authorId, includeRolls) get no added meaning from the description, 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?

A specific verb and resource are coupled with concrete content cues ('what players discuss, roll results, combat narration'), so the agent immediately knows this is the chat-read tool. It does not explicitly name the sibling it differs from (chat-export, chat-clear, chat-update), leaving that differentiation to be inferred from the names.

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 'since = a message ID to poll for newer messages' clause gives one concrete usage pattern, but there is no statement of when to prefer this over chat-export or how to page backwards versus forwards beyond the schema's own wording. Usage is implied rather than explicitly routed.

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 this is a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds genuinely new behavioral context: the message is the sole visibility channel for players, HTML is passed through, and actorId changes how the post is attributed and rendered. It doesn't say what comes back (a message reference) for follow-up edits.

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?

Purpose is front-loaded in the first clause and the reminder about player visibility lands early. The single dense paragraph packs in a lot of useful detail, though the trailing document-link syntax is a run-on fragment rather than cleanly structured 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?

With no output schema and a mutation annotation set, this covers the essentials an agent needs: what to send, how it renders, who sees it, and how to link documents. The only real gap is return-value information, which matters because follow-up edit/delete calls need the new message's ID.

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 a 3 is the floor, but the description earns more: it supplies the @UUID[Type.id]{Label} link syntax that appears nowhere in the schema, and gives concrete examples for flavor ("Narration", "The Tavern") plus the portrait behavior of actorId. The speaker/actorId precedence is left to the schema, which already covers 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?

States a specific verb and resource ("Send a message to the Foundry chat log") and enumerates the content types it carries. It does not name the sibling boundary against chat-update or chat-list, so an agent must infer that this is the create path and the others are read/edit paths.

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 list of use cases (narration, NPC dialogue, combat descriptions, OOC) implies when to reach for it, and the note that players only see what is posted here hints at why. But there is no explicit exclusion or pointer to chat-update for editing an existing message, which is the most likely confusion among 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, idempotentHint=true and destructiveHint=false, so the safety profile is covered without the description. The description adds that the result carries combatant IDs consumed by mutation tools, which is useful, but it says nothing about what happens when no active combat exists or whether the read reflects live state.

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: purpose and returned fields first, then the interoperability hint, then the parameter rule. No filler, and the most decision-relevant 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?

With no output schema, the description responsibly lists the returned fields (combatants, round, turn, current turn, combatant IDs), which is what an agent needs to know. The one meaningful gap is the empty state — whether a missing active combat yields an error or an empty result.

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 single parameter's own description already states "uses active combat if omitted," so the schema carries the semantics. The description only restates that default rule rather than adding format or validation detail; 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 and resource ("Get combat state") and immediately enumerates what is returned: combatants, round, turn, whose turn it is. It names the downstream sibling tools (combat-roll-initiative, combat-set-combatant-defeated) that depend on its output, so an agent can place it precisely among the combat-* 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?

Explicitly says "combatId selects a specific encounter; omit it for the active combat," which gives an unambiguous selection rule, and it signals the tool is a prerequisite for initiative/defeat tools. It stops short of stating when-not to call it (e.g., when no combat is active), so it is clear but not fully 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?

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 declare non-read-only, idempotent, non-destructive. The description adds genuinely useful semantic context beyond them: no round increment and, crucially, that round-based effects (Rage expiry, concentration, durations) do not fire. It could still clarify whether turn-start effects trigger, so not a full 5.

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?

Front-loaded with the core action, followed by the sibling contrast and then parameter provenance. It is dense but every clause carries weight; the em-dash-heavy phrasing is slightly harder to scan but not wasteful.

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

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

For a mutating, idempotent tool with no output schema, the description covers what it changes and what it deliberately avoids, which is the critical information. Edge cases such as an invalid/absent combatantId are left unstated, but nothing essential for correct invocation 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 already documents combatantId, combatId, and includeContext – including '(from combat-get)' and '(default true)'. The description largely restates what the schema already carries, so the 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?

States a specific action (jump to a combatant's turn) on a specific resource, and immediately contrasts it with combat-next-turn so the agent can distinguish it from the sibling without reading schemas. The scope constraints (no intermediate cycling, no round increment) sharpen the purpose further.

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 alternative (repeated combat-next-turn) and the behavioral condition that selects this tool over it (no round-based effects firing). It also tells the agent where combatant IDs come from (combat-get), so invocation context is complete.

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

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

Annotations declare non-readonly, non-idempotent, non-destructive, so the mutation profile is known; the description adds valuable facts beyond that: the exact state transition (round 1, turn 0), the return of combat state, and what includeContext appends (a combat-next-turn block). It does not address what happens if called on an already-started combat (reset vs. error), a meaningful gap for a non-idempotent op.

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, front-loaded with the core action and state, followed by timing and return behavior. 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?

With no output schema, the description compensates by stating that combat state is returned and what includeContext adds. Remaining ambiguity is about error/re-entry behavior on an already-running combat, which an agent would need for a non-idempotent 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 both parameters are already documented in the schema; the description's only added semantic is naming the appended payload 'as combat-next-turn,' which is a small but real elaboration over 'Append tactical context (default true).' Baseline 3 for fully covered params 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 ('Begin combat') plus exact resulting state (round 1, turn 0), which immediately separates it from combat-create, combat-next-turn, and combat-set-turn 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?

Explicit sequencing guidance: 'Call AFTER adding combatants and rolling initiative,' which tells the agent the prerequisite steps. It does not name the sibling tools that satisfy those prerequisites (combat-add-combatant, combat-roll-all-initiative) or say what to do if no combat exists yet, so it falls short of full alternative 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 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, idempotentHint, and non-destructive, so safety is covered. The description still adds real behavioral context: ids triggers a batch fetch in one call rather than N separate calls, and types+ids combine with AND. It does not describe the shape of returned documents, which is the remaining 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?

Front-loaded with the core action and packId dependency, and every clause carries routing or filtering information. The semicolon-chained style is dense and a touch crowded, but no sentence is filler.

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

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

For a read-only browse tool with full schema coverage and strong annotations, the description covers identity, selection semantics, and the batch-vs-single-call tradeoff. No output schema exists, and the return shape (document summaries, pagination metadata) is never described, which is the one notable 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 coverage is 100%, so baseline is 3, but the description genuinely adds semantics beyond the schema: 'types' selects SUBtypes, 'ids' is a batch selector for cases like every item a class grants or uuid-resolve output, and the two filters AND together. That combination rule is not stated 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 and resource ('Browse the contents of a compendium pack') plus concrete examples of content types (monsters, items, spells). It explicitly separates itself from compendium-list (which supplies packId) and from compendium-document-get, so an agent can distinguish it from siblings without opening a 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?

Explicit routing: use compendium-list to get packId, use ids to batch-fetch instead of N compendium-document-get calls, and use dnd5e-compendium-filter-* / pf2e-compendium-filter-* for stat filters. It names alternatives and the exact condition that selects each, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile needs no repeating. The description adds genuinely new behavioral context — the shape of the rendered result (statblock fields for actors, core fields plus system data for other types) — which matters because there is no output schema. It stops short of noting size limits or pagination, hence a 4 rather than 5.

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

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

Three tight sentences with no waste: purpose first, then the return shape, then sibling routing. Each clause earns its place and the most decision-relevant 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 two-parameter read tool with no output schema, the description covers what is returned, how the return differs by document type, and how to obtain the required IDs. 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% and both parameters are documented there, so the schema carries the load. The description adds no format or syntax detail for packId/documentId beyond the schema; it only implies where IDs come from. 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?

States a specific verb and resource ('Get a compendium document') plus the scope of the returned value ('as a readable summary'), including what an actor document becomes (statblock with HP, AC, abilities, attacks). It is clearly distinguishable from compendium-document-get-raw and uuid-resolve, which it names.

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 routes the agent: use compendium-document-get-raw for raw JSON, uuid-resolve when holding a UUID, and compendium-browse to obtain document IDs. The conditions that select each sibling tool are stated rather than inferred.

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 carry the read-only/idempotent/safe profile, and the description adds substantial context beyond that: name matches stop content scanning and yield null snippets, content matches carry ~200-char snippets, packs are scanned in order until limit, and results are unsorted. That is exactly the behavior an agent needs to interpret results correctly.

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

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

Three dense paragraphs, each front-loaded with its point: what it searches, the sibling contrast and version requirement, then result semantics. No filler sentences; parentheticals carry real information.

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

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

No output schema exists, and the description compensates by explaining the match shape (page uuid, matchedIn, snippet) and pointing to uuid-resolve for full text. An agent has everything needed to call it and to act on the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by illustrating pageTypes values (rule, spells, class/subclass) and explaining the cost tradeoff of searchContent=false, which helps the agent choose parameter values rather than just parse them.

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: full-text search inside JournalEntry compendium packs, covering both page names and content. It explicitly distinguishes itself from the sibling compendium-search ("sees only document names"), so an agent can separate the two without opening either 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?

Gives a concrete when-to-use framing ("The tool for rules/lore text"), a worked example query with pageTypes, names the alternative and its limitation, and states the bridge module 8.11.0+ prerequisite. It also tells the agent when to prefer name-only matching via searchContent=false.

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 readOnly, idempotent, non-destructive and closed-world behavior, so safety is covered. The description adds genuine behavioral framing: 'Name matching only', which tells the agent this is not a full-text search and will not surface matches buried in document bodies. It stops short of describing result shape 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 purpose is front-loaded before the routing clause, and every phrase earns its place – three siblings are dispatched in a single compact sentence with no filler. Density is high but readable.

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 name search, the definition plus annotations cover invocation fully and no output schema exists to explain returns. The only minor gap is that it never hints at what a result looks like (name list vs. full documents) or how limit defaults, which an agent might want before calling.

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 four parameters (query, type, limit, system) are already documented, including the case-insensitive substring semantics of query. 'Name matching only' reinforces the query parameter's scope but adds no syntax or format detail beyond the schema. Baseline 3 applies when the schema carries the 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?

States a specific verb ('Search'), resource ('documents across ALL compendiums') and a scope qualifier ('by name'), which immediately separates it from the filter and page-search siblings. The 'ALL compendiums' emphasis also communicates the cross-pack breadth that no sibling offers.

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 triggering condition ('when you do not know which pack holds a monster, item or spell') and routes to three concrete alternatives by name: dnd5e-compendium-filter-* / pf2e-compendium-filter-* for structured filters, compendium-page-search for journal text, uuid-resolve when a UUID is in hand. Nothing is left to inference.

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

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

Annotations cover the safety flags (readOnly=false, destructive=false, idempotent=false), and the description adds domain behavior the schema cannot express: temp HP absorbs first, and typed damage interacts with resistances, immunities and vulnerabilities. This is exactly the extra context the annotations do not carry.

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?

Front-loaded with the core action and scope, then triggers, then the parameter rule. Slightly dense with parentheticals, but every clause carries information and nothing 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?

For a mutation tool with no output schema, the description covers targeting, damage pipeline, and invocation timing. It omits what happens at 0 HP and what the call returns, minor gaps given the rest of the 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?

Schema coverage is 100%, so baseline is 3, and the description goes beyond it with a non-obvious selection rule: 'With several tokens of one actor pass tokenId, not actorId.' It does not explain the default when neither id is supplied, but it clearly adds value.

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

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

States a specific verb and resource ('Apply damage to an actor or to ONE token') and scopes it to dnd5e worlds/module 8.14+, which separates it cleanly from dnd5e-apply-healing and dnd5e-roll-damage without needing 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?

Gives concrete triggers: 'Use after your own damage roll, or when dnd5e-item-activate reports applied false', plus a routing rule for tokenId vs actorId. It stops short of naming the sibling to prefer in adjacent cases (e.g. dnd5e-apply-healing) or stating when not to call it.

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

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

Annotations declare a non-read-only, non-destructive, non-idempotent mutation, so the safety profile is already covered. The description adds a genuine behavioral trait not in the annotations: HP is clamped and stops at its maximum, and it discloses the module version prerequisite.

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 front-loaded sentence with no filler; the leading verb tells the agent what the tool is at a glance. The stacked parentheticals make it slightly dense but every clause carries information.

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

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

For a mutating tool with full annotation coverage and no output schema, the description covers the essentials: target selection, the HP cap outcome, and the world/module prerequisites. Return-value detail is not needed since no output schema exists, though error/failure behavior is unaddressed.

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 four parameters and the baseline would be 3. The description adds a disambiguation rule the schema lacks: when several tokens belong to one actor, pass tokenId to target the right one.

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 ('Heal an actor or ONE token') plus scope constraints (dnd5e worlds only, module 8.14+). This is clearly distinguishable from the sibling dnd5e-apply-damage, though the sibling is not named explicitly.

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?

Gives real usage context: it only works in dnd5e worlds on module 8.14+, and it explains the multi-token case ('With several tokens of one actor pass tokenId'). It does not name an alternative tool or state when-not-to-use, so it stops short of the top band.

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 a safe idempotent read, but the description adds substantive behavior: AND across filters, OR within arrays, inclusive ranges, exclusion of documents lacking a filtered field, response shape (total/hasMore), a bridge version requirement, and that results are thin {name, uuid} objects needing uuid-resolve or compendium-browse to hydrate. That is well beyond the annotation bar.

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?

Front-loaded purpose sentence, then scannable CRITICAL DATA FORMATS and EXAMPLES blocks, then a single runnable example. Every line carries a constraint or routing decision; nothing is filler.

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

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

For a 13-parameter tool with nested range objects, no output schema, and no required parameters, the description covers the risk areas: data formats, filter combination logic, field-exclusion behavior, pagination signals in the response, and the follow-up call needed to turn results into documents. 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%, yet the description still adds meaning: it enumerates the exact valid CR set and shows the fraction conversion ('1/4' -> 0.25; 0.3 is rejected), spells out min = max for exact matching, and warns that creatureType has no subtypes ("demon" -> "fiend"). These are real constraints beyond what the schema text conveys.

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 (search), resource (compendium packs for actors), and differentiator (D&D 5e structured filters, dnd5e worlds only). It explicitly positions itself against two siblings, actor-filter and compendium-search, so the agent can distinguish it without opening any 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?

It names both alternatives and the condition that selects them: actor-filter for world actors, compendium-search for plain name lookup. It also states the negative case (world-only filters such as folder, hasPlayerOwner, currentHp do not exist here), which prevents a whole class of failed calls.

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

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

Beyond the annotations, the description explains AND/OR filter combination, inclusive range semantics, exclusion of documents lacking a filtered field, response fields total and hasMore, result shape {name, uuid}, follow-up tool usage, and the bridge module version requirement. These are substantive behavioral details for correct invocation.

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

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

The description is front-loaded with purpose, then organized into critical data formats, filter behavior, response shape, and an example. Despite its density, every section supports correct use of a 14-parameter tool and no content is redundant with the schema.

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

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

For a complex 14-parameter search tool with no output schema, the description supplies the missing response shape, pagination fields, follow-up workflow, filter logic, data formats, domain restriction, and an example. It provides enough context for an agent to call and use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 14 parameters. The description still adds valuable semantics beyond the schema: price is normalized to gp, weight is in lb, decimals are allowed, ranges are inclusive, and filters combine as AND across fields and OR within arrays.

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: search COMPENDIUM packs for Item documents using D&D 5e structured filters. It scopes the tool to dnd5e worlds and explicitly identifies it as the compendium counterpart of world-item-filter, which helps separate it from unrelated siblings.

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

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

The description gives clear context for use: dnd5e worlds only, compendium item search, and follow-up paths via uuid-resolve or compendium-browse with IDs. It does not explicitly compare against compendium-search or state when not to use this tool, so it falls short of full when/when-not guidance.

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

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

Beyond the annotations, it discloses critical runtime behavior: Midi-QOL rolls and applies HP, fastForward skips dialogs, awaiting_user_dialog is not an error and must not be retried, and appliedDamage/appliedHealing report per-token results. It also warns against modeling one-off circumstances as effects because effects hit every copy of an unlinked token. No contradiction with annotations; the description substantially enriches the behavioral picture.

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

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

The text is dense but almost every clause carries operational value, and the core purpose is front-loaded before the edge-case guidance. It could be easier to scan if split into short bullets, but it is not padded or repetitive. Minor readability cost keeps it from a 5.

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

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

For a complex 17-parameter tool with no output schema, the description covers the important gaps: output semantics (appliedDamage/appliedHealing, applied false), dialog/status behavior, AoE coordinate conventions, target requirements, and the sibling alternative. Nothing essential for correct invocation appears to be missing.

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

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

Although schema coverage is already high at 88%, the description adds cross-parameter meaning and pitfalls: targetTokenIds is for attacks, attackMode/ammunition/consume answer fastForwarded dialogs, attackerTokenId selects among multiple tokens, and templatePosition uses a pixel formula. It also clarifies how one-off modifiers should be supplied instead of effects. This is well beyond what the schema alone conveys.

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: 'Activate an item with full Foundry automation (Midi-QOL hooks, targets, AoE templates): attacks, spells, abilities.' It explicitly distinguishes this from the quick-use sibling by ending with 'dnd5e-item-use is the quick use without targets.' An agent can tell exactly what this tool does and when it differs from the simpler alternative.

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

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

It gives explicit routing rules: use targetTokenIds for attacks, use dnd5e-apply-damage when applied is false, and use dnd5e-item-use for quick use without targets. It also explains how to encode one-off circumstances via advantage/disadvantage, attackBonus, damageBonus, and targetAcBonus rather than creating effects. This is about as strong as usage guidance gets.

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

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

Annotations declare a mutating, non-idempotent, non-readonly operation, and the description adds real behavioral context beyond that: dialogs are suppressed, the return is raw JSON, and on module 8.14+ a self-targeted heal is applied with a result carrying status/appliedHealing or a no_roll_performed warning. It stops short of spelling out consumption semantics or failure modes, but the disclosure is well beyond what annotations carry.

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 front-loaded clauses with no filler: the action, the sibling routing rule, and the 8.14+ edge case. Dense but each sentence carries distinct information; the version-gated note is slightly tucked at the end but still 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?

There is no output schema, so the description does the work of describing the return ('raw result as JSON' and the status/appliedHealing/warning fields). Combined with 100% schema coverage for inputs, an agent has enough to invoke and interpret results, though the consume side-effect and spell-slot interplay are left implicit.

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 seven parameters (consume, scaling, activityId, showInChat, activityType, etc.). The description adds only the general 'target-free' framing, not parameter-level meaning, so the 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?

States a specific verb and resource ('Use an inventory item via item.use()') and enumerates the item categories it covers (potions, scrolls, spells, weapons, features). It explicitly distinsecs itself from the sibling dnd5e-item-activate, so an agent can route without opening either 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?

Provides an explicit when-to-use vs alternative rule: 'Quick, target-free use; dnd5e-item-activate when targets, AoE templates or Midi-QOL matter.' The selecting condition for the sibling is named, leaving little to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, destructive all false), so the bar is lower; the description still adds value by disclosing that results appear in Foundry chat and by stating the mutual-exclusion rule 'Never both advantage and disadvantage'. It does not mention permissions or what a failure/loss looks like, but the added constraints are meaningful.

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

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

Three short sentences, each earning its place, with purpose stated first, routing second, and the behavioral constraint last. 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?

For a 4-param roll tool with no output schema, the description covers purpose, routing, chat output, and the advantage/disadvantage rule. Remaining gaps (permissions, whether a target must be selected) are minor for a read-only dice roll.

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 50%: actorId and ability are documented, but advantage/disadvantage have no descriptions in the schema. The description partially compensates by constraining how advantage and disadvantage interact ('Never both'), which is exactly the rule an agent would otherwise get wrong.

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

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

States a specific verb+resource ('Roll raw D&D 5e ability check') with a scope qualifier ('no skill proficiency') that cleanly distinguishes it from the sibling dnd5e-roll-skill. An agent can pick the right roll tool without opening either 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?

Gives explicit usage conditions ('contested checks or when no skill applies'), which is real routing guidance rather than implied. It stops short of naming the alternative tool (dnd5e-roll-skill) directly, so it's clear but not fully explicit about 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 declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description needn't restate it. It adds real behavioral context: a versioned rule ("Never both advantage and disadvantage (module 8.13+)") and the actor-get prerequisite. It stops short of saying the result is posted to chat or how a hit/failure resolves, keeping it below 5.

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

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

Three tightly written sentences, each carrying a distinct piece of information, with the core action front-loaded ahead of prerequisites and alternatives. 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?

With no output schema and annotations covering safety, the description supplies prerequisites, alternative routing, and the adv/disadv constraint. It omits the return shape (e.g. success/failure, chat output) and the meaning of the version guard, so it is strong but not airtight for a 4-param 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 coverage is only 50% – itemId and actorId are self-documented, but advantage/disadvantage carry no schema descriptions. The description partially compensates by stating they are mutually exclusive ("Never both..."), but adds no semantics for when to set either or the 8.13+ caveat's effect on them.

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?

"Roll attack with a weapon/spell" states a specific verb and resource, and the actorId/itemId framing makes the target unambiguous. It also explicitly distinguishes itself from dnd5e-item-use, so an agent can separate the two roll tools without opening either 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?

Names the prerequisite ("Use actor-get FIRST to find itemId"), the alternative and the condition that selects it ("For full attack sequence... consider dnd5e-item-use instead"), plus a hard constraint (never both advantage and disadvantage). when/when-not/alternatives are all present.

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?

Annotations already declare this is not read-only and not idempotent, but the description adds real value beyond them: the output destination ('Results appear in Foundry chat') and a validation constraint ('Never both advantage and disadvantage (module 8.13+)'). The prerequisite on actorId also flags a required lookup step. It stops short of describing what a save result contains or any failure modes.

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

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

Four short, front-loaded sentences with zero filler: purpose, usage context, output location, prerequisite, constraint. Every sentence earns its place.

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

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

With no output schema, the description usefully tells the agent where results surface (Foundry chat), covers the actorId prerequisite, and flags the advantage/disadvantage conflict. Complete enough to invoke correctly, though it leaves the mechanics of advantage/disadvantage and any error behavior unstated.

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 50% – actorId and ability are documented in the schema, while the advantage/disadvantage booleans are bare. The description compensates with the mutual-exclusivity rule for those two flags, which is genuine semantic information, but it still doesn't explain what setting advantage=true actually does. Adequate but not full compensation.

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 ('Roll D&D 5e saving throw') that cleanly separates it from the sibling roll tools (dnd5e-roll-ability, dnd5e-roll-skill, dnd5e-roll-attack, dnd5e-roll-damage). An agent can pick it out without opening any 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?

Gives a clear usage context ('Use when resisting spells, traps, or effects') and a prerequisite ('Use actor-list first to find actorId'). It does not explicitly name the alternative tools or state when not to use it, but the resource is narrow enough that no exclusion is really needed.

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

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

Adds useful side-effect context ('Results appear in Foundry chat') and a constraint ('Never both advantage and disadvantage'), which goes beyond the annotations. Annotations already declare non-read-only, non-idempotent behavior; the description does not explain output format or failure modes.

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

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

Three tight sentences, front-loaded with the action and ending with a hard constraint. Every sentence carries operational information.

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

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

Covers actorId sourcing, skill-code usage, output destination, and the advantage/disadvantage rule. No output schema exists, and return-value detail is not described, but the chat-result note largely covers it.

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

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

Schema coverage is 50%, so the description helps: it clarifies that skill codes (not names) are used via examples, and it states the advantage/disadvantage mutual exclusion, which the schema does not enforce. actorId points back to actor-list. Some fields like advantage semantics remain undocumented.

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 ('Roll D&D 5e skill check') and gives examples (Stealth, Perception). Not fully distinguished from dnd5e-roll-ability or roll-dice siblings, but the skill-check framing is clear.

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 says 'Use for ability checks with proficiency' and directs the agent to actor-list first to get actorId. Does not compare against dnd5e-roll-ability or roll-dice, so the sibling routing is incomplete.

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, covering the safety/mutation profile. The description adds a useful behavioral note that changes carry string values and follow dnd5e data paths ('other systems differ'), plus the single-token scoping caveat. It does not address permissions, whether an existing effect is overwritten, or what happens on invalid paths.

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?

Front-loaded with the core action and scope, followed by the changes/mode explanation and a compact worked example. It is appropriately sized for a 10-parameter nested tool, though the example JSON is dense and the final system-compatibility clause could be tightened.

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 10 parameters and nested objects with no output schema, the description covers the two aspects an agent is most likely to get wrong: the actor-vs-token targeting and the shape/semantics of 'changes'. Remaining fields (duration, statuses, disabled, origin, img) are self-documenting at 100% schema coverage, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully exceeds it: it provides a concrete worked example of a 'changes' entry and warns that paths are dnd5e-specific while other game systems differ. That path/format guidance is real added value over the raw schema, elevating it above baseline.

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

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

States a specific verb+resource ('Add a custom active effect') and scopes the target precisely ('to an actor, or to ONE token via tokenId'). It distinguishes itself from the effect-update/effect-delete/effect-list siblings by making clear this is the creation path, and it names what is being created (buff, debuff, custom condition).

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

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

The description implies the creation use case and explains the actorId-vs-tokenId selection ('instead of actorId: that token's own actor'), which is useful routing. However, it never explicitly names effect-update, effect-delete, effect-toggle-status, or effect-list as alternatives, nor states when NOT to use this tool (e.g., to modify an existing effect).

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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds the useful constraint that tokenId affects only ONE token's own actor, but says nothing about permanence, permissions, or side effects beyond what the annotations imply.

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

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

Two sentences with zero filler; the destructive action and the necessary lookup step are both 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 destructive tool with full annotation coverage, no output schema, and a fully documented schema, the description covers what to delete and how to discover the ID. It could note whether the deletion is permanent, but nothing required to invoke 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%, so all four parameters are already documented in the schema. The description reinforces the effectId source (effect-list) and the single-token scope of tokenId, adding marginal value over the schema 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 and resource ('Remove an active effect') and clarifies the two targeting modes (actor vs a single token via tokenId). It is not the name restated, but it doesn't explicitly differentiate itself from the adjacent effect-update or effect-toggle-status 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?

'Use effect-list first to find effect IDs' gives a clear prerequisite workflow for the required effectId. It stops short of stating when to prefer this over effect-toggle-status or effect-update.

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, destructiveHint=false, so the safety profile is fully covered. The description adds only the scoping fact that tokenId targets a single token's own actor, without noting return format, ordering, or whether a missing token yields an error.

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 front-loaded sentence with the actor/token scope first and the effect kinds in parentheses; there is 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?

For a three-optional-parameter read tool with full schema coverage and clear annotations, the essentials are present, but the description omits what a caller gets back (no output schema) and whether no-actor means default/all, leaving some inference to the agent.

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

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

Schema coverage is 100% and each parameter (actorId, sceneId, tokenId) is documented in the schema with defaults and sources. The description reinforces the actorId-vs-tokenId mutual exclusion, which is marginal added value over an already complete 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 (List) and resource (active effects on an actor or one token), and enumerates what counts as an effect (conditions, buffs, debuffs, custom). Clearly distinguished from the mutating siblings effect-create/effect-update/effect-delete/effect-toggle-status, though it doesn't explicitly name them.

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

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

The description implies when to use it (to read effects) and clarifies that tokenId selects one token's effects 'instead of' actorId, but offers no explicit when-not guidance, no exclusion against siblings, and no prerequisites.

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 non-readOnly, non-destructive, non-idempotent and closed-world, so the safety profile is covered; the description adds real behavioral context about token-scoped application ("only that goblin prone") and world-type gating. It stops short of saying what happens when the status is already present/absent or how the change is reported.

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?

Front-loaded scoping rule and target-selection caveat come first, followed by the useful status-ID enumeration; no sentence is redundant and the status list compensates for the absent enum.

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 6-parameter mutation tool with no output schema, the description covers target selection, world gating, alternatives and valid values adequately. Return/shape information and the no-op case (status already applied) are the only noticeable omissions.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the semantic difference between actorId and tokenId in worlds with duplicate actor copies, and a concrete list of valid status IDs since no enum is defined. That is genuine 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?

States a specific verb (toggle) and resource (a D&D 5e condition on an actor or a single token), and immediately distinguishes itself from the PF2e alternatives by naming pf2e-set-condition / pf2e-remove-condition. An agent can route between this and the sibling set without opening either 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?

Explicitly scopes usage to dnd5e worlds and names the PF2e replacement tools for the other case, plus clarifies the actorId-vs-tokenId selection rule when several copies of an actor exist. Both the when and the when-not are 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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds targeting semantics (per-token application) beyond that, but says nothing about whether omitted fields are preserved (partial vs full update), what 'changes' replacement implies for existing data, or any permission requirements.

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

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

A single front-loaded sentence with the entity affected stated first and the mutable field list trailing. Efficient, though the trailing field enumeration is partly redundant with the parameter names and the shouted 'ONE' is a little stylized.

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 9-parameter mutation tool with nested objects and no output schema, the description plus 100%-covered schema and safety annotations give an agent enough to invoke it. The remaining gap is update semantics (replace vs merge, and how 'changes' interacts with a tokenId-scoped effect) which neither description nor annotations resolve.

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% across all 9 parameters, including the nested changes/duration objects and mode enum inlined in the schema, so the baseline is 3. The description's trailing field list (name, icon, disabled, changes, duration) merely restates a subset of the schema without adding format or interaction detail.

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 (Update) and resource (existing active effect), scopes it correctly ('on an actor, or on ONE token via tokenId'), and enumerates the mutable fields. 'Existing active effect' cleanly separates it from sibling effect-create, effect-delete, and effect-toggle-status.

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

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

Implies the tool is for modifying an effect that already exists, and it does route the agent between actorId and tokenId targeting ('on ONE token via tokenId'). However, it never states when to prefer effect-toggle-status over setting 'disabled' here, nor any preconditions such as needing the effect to be found via effect-list first.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantive behavior beyond them: permanence, what happens to children/documents when flags default to false (they orphan to parent/root), and the compounding effect of setting both flags. It omits any note on permissions or failure modes, so not a 5.

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

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

Three tight sentences, front-loaded with the action and its permanence, followed by flag mechanics and finally the safety warning. No filler and the riskiest information is not buried.

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

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

For a destructive mutation with no output schema, the description covers permanence, defaults, child/document handling, and a user-confirmation caution — enough detail to call it safely. Minor gaps remain around required privileges and post-delete state, but nothing that would cause a wrong invocation.

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

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

Schema coverage is 100% and the schema descriptions already state the defaults and orphan behavior for both flags. The description largely restates that semantics, though it helpfully conveys the combined effect of both flags being true. Baseline 3 is appropriate when the schema carries the parameter detail.

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 ('delete') and resource ('folder') with the scope qualifier 'permanently', which cleanly separates it from folder-update, folder-get, and folder-list in the sibling set. An agent can identify this as the destructive folder operation 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?

Provides clear operative context: which flags do what and the strong recommendation to 'confirm with the user first' before wiping a populated tree. It does not name an alternative tool (e.g., moving folders vs deleting), so it stops short of full when/when-not 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?

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.