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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable beyond-annotation context: 'Read-only for members,' the subtle shared=false native-document access nuance, and the return contract ({ok:true,data} vs {ok:false,error}). No contradictions.

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

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

Each sentence earns its place: purpose, sibling routing, access implications, and error contract. The description is efficient and front-loaded with the core purpose.

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

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

For a zero-parameter read-only list tool with an output schema and strong annotations, the description covers purpose, alternatives, behavioral nuance, and error patterns. Nothing an agent needs to call this 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?

The tool has zero parameters, so the schema fully describes the input surface. Baseline 4 applies; no parameter-specific semantics are needed.

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

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

States exactly what the tool does: 'List native and shared documents visible in the configured campaign.' It also distinguishes itself from siblings by naming document_list and document_read for alternative purposes, making the tool's role clear and distinct.

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 document_list for asset-library filters and document_read for content. This tells an agent when not to use this tool, which is strong usage differentiation.

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

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

The description adds meaningful behavioral context beyond the annotations: read-only access for campaign members, the caveat that /health reachability does not imply feature support, unknown unprobed capabilities, and idempotence via repeating reads not changing state. It also discloses return-shape and error-handling behavior, which annotations do not cover.

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

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

Every sentence earns its place: purpose, usage guidance, behavioral caveats, and failure semantics are all included without redundant padding. The key orientation purpose is front-loaded, and the caveats are grouped logically.

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 zero parameters, rich annotations, and an output schema, the description fully covers what an agent needs to correctly select and invoke this tool. It explains orientation scope, sibling routing, membership permissions, idempotence, and error response behavior.

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

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

The tool has 0 parameters and schema coverage is 100%, so there are no parameter semantics to explain. The description appropriately avoids fabricating parameter guidance, meeting the baseline for a no-parameter tool.

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

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

The description clearly states the verb 'Read' and the resource scope: campaign identity, role, health, current map, and capability evidence. It also distinguishes itself from map_list and session_list, making its purpose specific and unambiguous.

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

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

It explicitly says 'Use this for orientation' and directs the agent to alternatives: 'use map_list for all maps and session_list for sessions.' This gives clear when-to-use guidance and names the sibling tools that handle related but different needs.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false. The description adds specific behavioral context: 'The old DM becomes PLAYER, ownerId stays unchanged, and local role/system caches are invalidated after success.' It also warns 'Role changes and broadcasts are not guaranteed idempotent,' which aligns with the idempotentHint. This goes beyond the annotations by detailing the side effects. However, it does not state what permissions the caller must hold (e.g., must be admin/owner to transfer), which is a minor gap.

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

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

The description is about four sentences, each carrying distinct information: purpose, prerequisite, side effects, and return format. It is front-loaded with the action and includes a warning. No filler, but it could be slightly tightened (e.g., merging the return-format sentences). Still, every sentence earns its place, so a 4 is appropriate.

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 purpose, prerequisites, side effects, non-idempotency, explicit do-not instructions, and return value format ({ok:true,data} vs {ok:false,error}). It also distinguishes tool-body failures from MCP argument errors. Given the tool's complexity and the existing output schema (which presumably defines the data structure), nothing essential is missing for an agent 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 already provides 100% coverage with a clear description: 'Existing campaign member UUID to become DM; the owner passes their own user UUID to reclaim the role.' The description repeats the same idea ('owner reclaim uses the owner's own ID') but adds no new meaning. Per the rubric, when schema coverage is high, baseline is 3, and the description does not elevate it further.

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

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

The description states a specific action: 'Transfer the campaign DM role to an existing member, or reclaim it as owner.' It names the resource (campaign DM role) and the two modes, clearly distinguishing it from sibling tools like campaign_get (inspection) and character_update (different resource). The verb 'transfer' is precise and 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 explicitly directs the agent to 'Use campaign_get to inspect current role/ownership first' and reiterates 'inspect campaign_get before considering another transfer.' It also provides an explicit negative: 'Do not simulate this with separate role edits.' This gives clear when-to-use and when-not-to-use guidance, plus a precondition that prevents misuse.

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

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

The description goes well beyond the annotations: it discloses that the operation is not atomic or idempotent, explains the roster read-back and conditional assignment, details failure return shapes including ok=false with a created character ID, and notes when creation status is unknown. Annotations only carry high-level hints, so this behavioral detail is highly valuable.

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

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

The description is front-loaded with the core purpose and each subsequent sentence provides operationally relevant information about alternatives, failure modes, and recovery. It is long, but the density of caveats is justified for a create tool with non-idempotent behavior.

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

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

Given the full schema descriptions, annotations, and output schema, this description closes the remaining gaps: error contracts, non-idempotency, recovery advice, and the fact that campaign gameSystem determines the initial schema. Nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, and the input schema already fully documents all three parameters: name length/trimming, data object semantics, and token_image_url default/omission. The description adds the gameSystem-dependent schema context, but parameter meaning is already carried by the schema, so the 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 exactly what the tool does: it creates a new character sheet and ensures it appears in the current campaign roster. It explicitly contrasts with character_update for existing sheets and token_add for token placement, so an agent can distinguish this tool from its 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?

It gives direct routing guidance: use character_update for existing sheets and token_add for placing a linked token, and clarifies creation does not place one. It also warns not to trust character_validate as a save gate, providing concrete when-not-to-use guidance.

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

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

The annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, but the description adds crucial context: the deletion is permanent with no undo, it does not remove map tokens, re-invocation may return a not-found error, and the exact success/failure response shapes are specified. This exceeds what annotations alone provide and does not contradict 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 longer than average, but every sentence adds necessary operational context: scope, alternatives, side effects, repeat behavior, and error contract. It is front-loaded with the core purpose and then flows logically through exclusions and return behavior.

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 one parameter, a rich output schema, and annotations covering safety and idempotency, the description still provides everything an agent needs: ownership requirements, no undo, no token removal, repeat behavior, and a precise success/error return contract. Nothing important is missing.

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

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

The input schema already covers the single parameter at 100%, including that it must be a character sheet ID owned by the user, not a map token ID. The description reinforces this in prose but does not add substantially new parameter-level meaning beyond the schema.

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

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

Opens with a specific verb and resource: 'Delete a character sheet permanently (owner only).' It clearly distinguishes itself from sibling tools by noting it is different from token_delete and character_update, so an agent can correctly identify the operation.

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 when-to-use and when-not-to-use guidance, including 'use character_get to inspect the sheet first,' 'use token_delete to remove only a placed map token,' and the exclusion that 'DM authority alone does not grant deletion rights.' This fully routes the agent to the correct sibling alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, but the description adds meaningful context beyond them: preserving unknown fields, gameSystem-specific interpretation, visibility of keeper data.notes, repeated reads not altering the sheet, and the ok/error return envelope. This is substantial added behavioral detail with no contradiction.

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

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

The description is dense yet compact, with the primary action front-loaded and every sentence earning its place by adding routing, permission, data-interpretation, or error-handling context. There is no filler or repetition of annotation values.

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 a single simple parameter, rich annotations, and a thorough description covering discovery, permissions, data semantics, idempotency, and failure modes, an agent has everything needed to select and invoke this tool correctly. The output schema also covers return-value structure, 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?

The input schema already documents character_id fully at 100% coverage. The description reinforces that the ID is discovered via character_list and that the sheet may use its own gameSystem, but it does not add significant new meaning beyond the schema's parameter description.

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

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

The description opens with a specific verb and resource: 'Read a full character sheet by ID', which clearly states the operation. It also distinguishes itself from sibling tools by explicitly naming character_list for roster discovery and character_update for patching, so an agent can tell them apart.

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 routing guidance: 'Use character_list to discover roster IDs and character_update to patch a sheet.' It also gives access context by explaining who upstream allows to read, which helps an agent decide when this tool is appropriate.

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

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

With destructive/non-idempotent annotations already set, the description adds real value: async dispatch semantics (sent:true,confirmed:false,status:"pending" is not a business ACK), no shared transaction with healing, no reliable capability probe, older servers silently ignoring the event, and retry guidance via events_poll. However, the corrupted sentence "there is no v1.5.0 permits the owner or DM but never a spectator" is incoherent and leaves the gating model ambiguous.

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 critical spend/async/retry information is reasonably front-loaded, but the description is long for two parameters and contains a broken, self-contradicting sentence about gating that costs reader comprehension. Some hedging ("no reliable capability probe," "may silently ignore") earns its place, but the corrupted line does not.

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 a destructive mutation tool with an output schema and full annotations, the description covers auth requirements, async result handling, error shapes ({ok:false,error} vs MCP argument errors), and retry discipline. The only real gap is the garbled gating sentence, which leaves the spectator/permission model 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?

Schema coverage is 100%, so the baseline is 3, but the description adds a useful anti-pattern clarification that index "selects an array entry, not a dice count," plus the guidance to inspect character_get for valid pools and remaining uses. This meaningfully supplements the schema without contradicting it.

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

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

The opening sentence gives a specific verb+resource+scope: "Spend one remaining use from a DND_5E character's Hit Dice pool through WS." It explicitly distinguishes itself from roll/heal siblings (dice_roll, token_hp_update). The trailing garbled sentence about gating slightly muddies the otherwise clear purpose, so it falls short of a clean 5.

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 prerequisites (owner or DM, campaign assignment), routes the agent to character_get for inspection, and clarifies that dice_roll/token_hp_update handle rolling and healing separately with no shared transaction. It also prescribes post-call behavior (read events_poll before further action, never blindly resend). It stops short of an explicit when-not-to-use rule, so 4 rather than 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 provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds valuable behavioral context beyond those: no creation or roster changes on repeat calls, the successful return shape {ok:true,data}, failure shape {ok:false,error}, and the distinction between tool-body failures and MCP argument-schema errors. 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 four sentences and every sentence earns its place: what it does, sibling routing, idempotency/read-only guarantee, and return/error behavior. The primary purpose is front-loaded, and there is no redundant filler.

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

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

For a zero-parameter list operation with rich annotations and an output schema, the description is complete. It covers the operation's scope, safety, idempotency, return format, error format, and the relationship to sibling tools—everything an agent needs 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 tool has zero parameters, so the baseline is 4. The description adds no parameter details because none are needed; the schema already reflects an empty parameter set. There is no gap requiring 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?

The description uses a specific verb and resource: "List the configured campaign roster to discover character IDs and assignments." It also differentiates itself from character_get and character_create, so an agent can distinguish it from close siblings without opening their schemas.

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

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

The description explicitly says when to use this tool versus alternatives: "Use character_get for one full sheet or character_create to add a sheet." It also clarifies that the operation is read-only and safe on repeat calls, giving clear context for invocation.

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

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

Goes far beyond the destructive/openWorld/idempotent annotations: recursive merge semantics, array/scalar replacement, null-as-explicit-value, in-process locking scope, lost concurrent browser saves, updatedAt guard conflicts, and stale-intent caveat. It also discloses which fields upstream validation may discard and how errors surface.

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-loads purpose, prerequisites, and alternatives before the caveats. Dense and long, but nearly every sentence carries distinct, non-redundant operational information; only the concurrency/validation sentences 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?

An output schema exists, yet the description still summarizes return shapes ({ok:true,data} vs {ok:false,error}) and distinguishes tool-body failures from MCP argument-schema errors. Combined with the merge and concurrency rules, nothing material 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 coverage is 100%, so baseline is 3, but the description adds real meaning: the 'request-field object' shape with an example, the top-level allowlist (name/data/tokenImageUrl), and the recursive merge rule for nested dictionaries. The example `{"data":{"hp":{"current":5}}}` is not in the schema.

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

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

States a specific verb and resource ('Patch an existing sheet') plus the defining behavioral trait ('preserving unspecified fields'). Names the siblings it is not (token_hp_update, character_create) so an agent can distinguish it 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?

Explicitly prescribes prerequisites and alternatives: 'Use character_get first', 'use token_hp_update for a signed HP change', 'character_create for a new sheet'. When-to-use and when-to-use-something-else are both covered.

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

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

The annotations already indicate read-only, idempotent, and non-destructive behavior, and the description adds valuable context beyond that: version-specific validation reliability, the guaranteed addition of validation_reliable and validation_note, and the exact success/error return shapes. There is no contradiction with the annotations.

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

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

The description is front-loaded with purpose and usage, then covers reliability caveats and return behavior. It is a bit dense, but every sentence earns its place by conveying risks and edge cases that 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 single-parameter read-only tool with rich annotations and an output schema, the description is complete. It covers ownership, reliability caveats, success versus failure shapes, and MCP-level argument-schema errors, 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 input schema fully documents character_id at 100% coverage, so the baseline is 3. The description reinforces that the character must be owned and that validation is fixed-system, but it does not add meaningfully new parameter-level semantics beyond the schema.

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

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

The description opens with a specific verb and resource: 'Read upstream validation diagnostics for an owned character.' It also distinguishes itself from character_get by explicitly routing field inspection to that sibling, so an agent can tell the tools apart.

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

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

The description gives explicit guidance: use character_get to inspect fields and do not rely on this tool as a save gate. It also clarifies that repeating the call does not repair or save data, which helps an agent decide when not to invoke it.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds actionable behavioral details: repeated reads do not consume messages, DICE_ROLL entries are excluded, older servers reject cursor history, and failure modes return ok:false. This goes well beyond the annotation hints.

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

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

The description is dense but every sentence earns its place: purpose, routing, permissions, pagination procedure, server caveat, exclusions, idempotence, and error contract. The most critical usage guidance 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 an output schema present and rich annotations, the description covers all operational essentials: pagination protocol, server compatibility, exclusions, and error format. Nothing an agent needs to invoke or interpret the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches the cursor parameter with lifecycle semantics ('pass nextCursor unchanged', 'stop at null', 'Do not construct cursors or offsets') and clarifies the limit's pagination role. Slight deduction because the limit parameter is not discussed beyond the schema.

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

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

The description opens with a specific verb and resource ('Read persisted campaign messages') and immediately distinguishes itself from events_poll. It also states exclusions (DICE_ROLL entries), leaving no ambiguity about what the tool returns.

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

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

Explicitly routes usage: 'Use chat_read for narration history; use events_poll for dice results and live events.' It also provides a clear pagination walkthrough (start without cursor, pass nextCursor unchanged, stop at null) and notes server compatibility caveats.

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 flag non-readonly, non-idempotent, open-world behavior, and the description adds substantial context beyond them: upstream cooldown may reject, each accepted send creates a new message, 'sent:true,confirmed:false' is dispatch and not a business ACK, and events_poll must be read before retrying. This is exactly the caveat detail an agent needs to avoid blind retries.

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 alternatives, and every sentence carries operational weight. However it is dense and slightly repetitive around retry/ACK language ('do not retry blindly' and 'never blindly resend'), which costs a point on tightness.

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 an output schema existing, the description still frames the result contract (sent/confirmed/status on dispatch, {ok:true,data} vs {ok:false,error}, MCP-level schema errors), leaving no ambiguity about what a successful call does or does not guarantee.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds genuinely new semantics: 'type' does not change the authenticated role and, on v1.5.0, the server derives the broadcast category from the authenticated role. That is meaning beyond the schema's field description.

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

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

The opening sentence states a precise verb and resource ('Post one campaign chat message') and immediately scopes the two modes (narration vs player dialogue). It is trivially distinguishable from siblings like chat_read and dice_roll, which the description names 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?

It names alternatives and their selecting conditions: chat_read for history, dice_roll for dice rather than chat text posing as a roll. It also states the authentication prerequisite (authenticated campaign membership) and a clear exclusion ('type is a message category, not a role grant').

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful version/auth context (DM-only reads in v1.5.0) and the return/error contract ({ok:true,data}, {ok:false,error}, MCP schema errors), but much of the 'does not mutate' framing restates idempotentHint.

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

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

Front-loaded with purpose and the alternative tool, then dense behavioral notes. Every clause carries information, though the single dense paragraph mixes usage, versioning, parameter and error details without much structural separation.

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 an output schema, annotations, and 100% parameter coverage, the description supplies the remaining operational context: cross-system source resolution, the v1.5.0 DM restriction, forwarding/capping behavior, and error-shape distinctions. Nothing an agent needs before calling is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by disclosing forwarding semantics ('search, challenge rating and offset are forwarded'), the hard cap at 100 without local lower-bound validation, and the cross-system behavior of an empty source.

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 library templates') and ties it to the downstream sibling token_place_creature, which disambiguates it from character_list immediately. An agent can tell what it retrieves and why without reading 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?

Explicitly routes the agent: 'Use character_list for campaign character sheets; this does not create either a character or a token.' It also names the version-specific access rule (v1.5.0 restricts library reads to the DM) and the empty-source behavior, giving concrete when/when-not conditions.

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

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

Annotations already flag non-readOnly, open-world and non-idempotent, but the description adds substantially: a 2.1-second minimum gap with 30/minute, the server-authoritative budget and secret routing, and the crucial disclosure that sent:true/confirmed:false is a dispatch, not a business ACK. It also clarifies that the bridge performs no RNG or rules math and points to events_poll for error visibility.

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 core routing rule and the send/ACK caveat are front-loaded in the first few sentences, and every clause carries operational value. It is dense and slightly sprawling, with error-shape details tacked on at the end, but there is no obvious filler to cut.

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 non-idempotent, open-world mutation tool, the description covers permissions, rate limits, delivery semantics, failure handling, and where to observe results. With an output schema present, it need not explain return values, and it still documents the success/failure envelope shape and MCP-vs-tool error distinction.

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 four parameters are already documented, and the description still adds field-level constraints the schema omits: characterName capped at 200 and purpose at 300 characters on newer servers, plus that purpose does not alter dice calculation. It does not restate the expression grammar, which is fine since the schema 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?

The opening sentence states a specific verb+resource ('Roll server-authoritative dice') plus the side effect ('publish the result to the permitted audience'), which no sibling tool offers. It also explicitly distinguishes itself from saved_roll_list, so an agent can route between them 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?

Explicitly names the alternative for stored expressions ('use saved_roll_list'), warns that saving a macro is not execution, states who may roll (authenticated campaign users; DM/PLAYER, not spectators), and gives an operational rule ('never retry on missing results'). These are concrete when-to-use/when-not conditions rather than implied guidance.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description adds substantial behavioral context beyond them: whitespace preservation for content, trimming of name/description, scope-based permission enforcement (USER personal, CAMPAIGN requires DM, GLOBAL upstream), a 900 KiB UTF-8 cap, a shared rate limit of 30 requests/minute/user, and the return envelope shape. It also notes that each accepted call creates a separate asset. No annotation contradiction exists.

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

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

The description is longer than average, but every sentence carries operational value, including routing, limits, permissions, and response format. It is front-loaded with purpose and alternatives before diving into behavioral details. It could be slightly tightened, but it remains well-structured and free of 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?

Despite the tool's six parameters and rich schema, the description leaves no essential gap: it covers when to use it, alternatives, permissions by scope, size limits, rate limits, return behavior, and a pointer to document_share for linking. The presence of an output schema and detailed input schema further reduces the burden, and the description is more than sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description still adds semantic value by clarifying that 'Name and description are trimmed; content preserves whitespace' and that scope rights are enforced upstream. These nuances are not fully captured in the schema property descriptions, so the description meaningfully supplements the structured input definitions.

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

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

The description opens with a specific verb and resource: 'Create a new txt/md document from inline content through REST.' It explicitly distinguishes itself from siblings by naming document_upload (PDF/larger local files) and document_update (replace existing text). An agent can immediately identify what this tool does and how it differs from alternative document 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 gives explicit routing guidance: 'Use document_upload for PDF or larger local files, and document_update to replace existing text.' It also clarifies when document_share is needed ('Creation does not separately link a personal asset; use document_share for that'). This leaves no ambiguity about when to choose this tool over its 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, but the description adds substantial context beyond them: local downloaded copies survive deletion, repeating the call is idempotent in effect yet may return a not-found error (clarifying the idempotentHint), there is no undo, and the return shape distinguishes success, tool-body failures, and MCP schema errors. This meaningfully enriches what the annotations alone convey and does not contradict 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 dense but not bloated; each of its seven sentences earns its place (purpose, sibling routing, permissions, destructiveness, idempotency caveat, undo absence, return contract). The core purpose is front-loaded before caveats. It is slightly long, but for a destructive, irreversible operation the thoroughness is justified.

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 one parameter, the description is complete: it covers the action, cascade effect on share links, permission context, error/return contract, and irreversibility. The output schema exists and the description still explains the {ok:true,data} vs {ok:false,error} contract, which is more than sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, and the schema already explains that document_id is a 'Document asset ID to remove globally, including all campaign sharing links; not a single link ID.' The description reinforces this via the document_unshare contrast but adds no new parameter-level detail beyond the schema. Baseline 3 is appropriate since 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?

The description opens with a specific verb and resource: 'Delete a document asset and all of its share links.' It explicitly differentiates itself from document_unshare ('remove only one campaign link') and document_read ('inspect content first'), making the tool's scope unmistakable without needing to inspect 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 explicit routing guidance: use document_unshare when only one campaign link must be removed, and use document_read to inspect content before deleting. It also states that permission enforcement is handled upstream. An agent knows exactly when to pick this tool over its 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, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond those: upstream filters by access, USER scope uses an explicit current-user filter for admins, repeated listing does not consume or modify assets, and success/failure return shapes are specified. 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 front-loaded with purpose and filters, immediately followed by sibling routing, then behavioral notes and return/error semantics. Every sentence adds distinct value; there is no filler or repetition of schema content.

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

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

For a 5-parameter read-only list tool with an output schema, the description is complete: it covers scope semantics, access filtering, idempotence, success shape, tool-body failure shape, and MCP-level argument errors. Nothing critical 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 coverage is 100%, so the baseline is 3. The description adds meaningful param nuance beyond the schema, particularly that USER restricts to personal assets with an explicit current-user filter for admins and that null scope leaves filtering to upstream. This clarifies behavior that raw schema descriptions only hint at.

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

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

The description opens with the specific verb 'List' and resource 'document assets', then names the exact filters (scope, search, page). It also explicitly distinguishes itself from campaign_document_list and document_read, so an agent can tell sibling tools apart immediately.

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

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

It gives clear routing guidance: use campaign_document_list to discover personal documents shared into the campaign, and use document_read for content. It also explains read-only access and upstream filtering, which helps the agent decide when this tool is appropriate versus alternatives.

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

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

Annotations carry readOnlyHint/idempotentHint, but the description adds crucial nuance: binary reads 'atomically replace downloads/<id>.pdf locally' while 'readOnlyHint refers to the upstream resource.' It also discloses upstream visibility checks, conditional-read semantics, and the {ok:false,error} failure envelope — all context the annotations alone do not provide.

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

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

Front-loaded purpose, then usage, behavior, return modes, and error format in a logical order; every sentence carries information. Slightly longer than strictly necessary since the output schema already documents return fields, but the density is justified by the tool's two modes and local side effects.

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

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

Given the output schema covers return values and annotations cover safety hints, the description still supplies everything an agent needs: discovery flow, local file side-effect disclosure, conditional caching semantics, and the distinction between tool-body failures and MCP argument-schema errors. Nothing needed 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 coverage is 100%, so baseline is 3. The description adds genuine value by explaining the etag's behavioral consequence — '304 returns not_modified=true without content, so retain your cached copy' — which goes beyond the schema's request-side description of If-None-Match. It reinforces the mode-dependent return fields but leans partly on the output 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?

Opens with a specific verb and resource: 'Read an accessible document as text or a local binary download.' It also distinguishes itself from siblings by naming document_list/campaign_document_list for ID discovery and document_update for content replacement, so an agent can route correctly without opening other 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?

Explicitly routes the agent: 'Use document_list/campaign_document_list to discover IDs; use document_update to replace txt/md content.' It also explains when to use the etag parameter (conditional read with 304 handling) and how to interpret the not_modified response, leaving no ambiguity about invocation flow.

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

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

Annotations already mark this as non-readonly, non-idempotent, and non-destructive, but the description goes further: it explains that sharing broadens access without copying, duplicate-link behavior is upstream-controlled, and retries cannot be assumed idempotent. It also documents success/error return shapes and MCP error behavior, adding real behavioral context.

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

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

The description is moderately sized but front-loaded with the core purpose and then covers usage, behavioral caveats, and return formats in a logical order. Every sentence earns its place, though the return-format and MCP-error sentences add density.

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 write operation with an output schema and rich annotations, the description covers the essential context: who may use it, what side effects occur, what makes it non-idempotent, how to undo it, and what response shape to expect. 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% and the parameter description already explains that document_id must be a shareable DOCUMENT asset UUID, not a filename, and must satisfy ownership checks. The tool description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description names a specific action ('link a shareable document asset into the configured campaign'), scopes it to DM only, and contrasts it with siblings like document_unshare and document_upload. This makes the tool’s role immediately distinguishable from other document and campaign 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?

It gives explicit when/how guidance: use campaign_document_list to inspect existing links, document_upload to create an asset first, document_unshare to revoke, and explicitly warns against document_delete for this purpose. The DM-only restriction further clarifies appropriate invocation 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?

Despite annotations already marking destructive and idempotent hints, the description adds meaningful specifics: what remains intact (asset, other links, local downloads, global access), that repeats may error, and the success/failure return shape. It clarifies the idempotency nuance rather than contradicting it.

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

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

The description is dense but each sentence earns its place: purpose, prerequisites, alternatives, side-effect boundaries, idempotency behavior, and error modes. The most critical scoping 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 single-param mutating tool, this description is exceptionally complete. It covers permission context, preconditions, alternative tool routing, side effects, repeat-call behavior, and return/error semantics without requiring the agent to infer anything important.

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

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

The input schema already fully documents document_id with a clear description, so the baseline is satisfied. The description adds extra value by explaining how to recognize invalid targets via shared=false in campaign_document_list, which helps the agent pick the correct ID.

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 one document share link from the configured campaign (DM only).' It clearly differentiates from sibling document_delete by explaining that unshare only revokes one link while deletion removes the asset everywhere.

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 when-to-use guidance: DM only, inspect campaign_document_list first, and avoid unsharing documents where shared=false. It also names document_delete as the correct alternative for full asset deletion.

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

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

The annotations already mark this as destructive, non-idempotent, and open-world, and the description adds substantial context beyond them: upstream-enforced edit rights, rights depending on asset scope and membership rather than uploader identity, empty content clearing text, metadata/notification side effects, and no promised full-operation idempotency. It also describes success, tool-body failure, and MCP argument-error response shapes. Nothing contradicts the annotations.

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

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

The definition is front-loaded with the core action and alternatives, and most sentences carry useful constraints or failure behavior. It is slightly dense and has minor redundancy around returning upstream REST data versus the explicit {ok:true,data} response shape, but it is not padded.

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

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

Given the destructive non-idempotent mutation, two required parameters, output schema, and permission complexity, the description covers the critical context an agent needs: replacement semantics, edit-rights dependency, alternatives, side effects, and error behavior. The output schema carries return-value detail, so the description's return notes are supplementary rather than 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 meaningful semantics beyond the schema: content replacement is wholesale rather than merge-patching, empty content clears the text, and PDF content cannot be edited. The document_id meaning is already well covered by the schema, so this is not a full 5.

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: replace an entire txt/md document's content. It explicitly distinguishes this from merge-patching, PDF editing, reading, creating, and uploading, so the agent can identify the correct operation without opening sibling schemas.

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

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

It gives explicit when-to-use guidance: call document_read first to avoid losing text, use document_create for a new asset, use document_upload for PDF, and consult campaign_document_list's canEdit when available. The exclusions and alternatives are unusually clear.

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

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

Annotations only mark side effects and idempotency; the description adds major operational detail: retries duplicate assets, CAMPAIGN scope requires the DM, signature/size-cap checks, default 30/min rate limit, 400 preservation, and exact success/failure response shapes. This is far beyond annotation coverage.

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

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

Though long, every sentence carries a distinct operational fact: purpose, alternatives, filesystem constraint, idempotency warning, access control, limits, error behavior, and return format. It is front-loaded with purpose and routing and contains 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 mutating, non-idempotent upload tool with 6 parameters, this description covers file source prerequisites, permissions, rate limits, duplication risk, return values, and error classification. Output schema exists and is further supplemented by explicit response documentation, so nothing an agent needs 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% with rich parameter descriptions, so the baseline is 3. The description adds extra meaning for scope (CAMPAIGN requires that campaign's DM) and file_path (size cap and signature checks), justifying a small bump 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 opening sentence specifies the exact operation: uploading an existing local PDF/txt/md file as a document asset via multipart REST. It also differentiates from siblings by naming document_create for inline text and document_share for linking existing assets, so an agent can select the right tool.

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

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

The description gives explicit routing guidance: use document_create for inline text, document_share for linking existing assets, and this tool when uploading a file. It also states the filesystem prerequisite ('client-local paths must be mounted'), which is a clear when-not condition.

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?

Although annotations already declare readOnly/idempotent/non-destructive, the description adds substantive behavior beyond them: lazy WS connection, no game-state mutation, stale marking on connection failure, 500-event eviction buffer, cursor_reset after restart, has_more pagination, and the warning that broadcasts are not correlated ACKs. This is unusually rich disclosure for a read tool.

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

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

Purpose is front-loaded in the first clause and every sentence carries operative information, but the passage is long and some material (the ok/data envelope) duplicates the output schema. Dense rather than padded, but denser than strictly needed.

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 stateful polling tool with an output schema already present, the description still covers the non-obvious failure modes an agent must handle: eviction gaps, cursor resets, pagination, stale-on-failure, and MCP-level vs tool-body error shapes. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond it: it explains the since/next_seq relationship ('Returns earliest seq > since first') and the resume protocol ('advance using next_seq'). It leaves the limit semantics entirely to the schema, keeping it just short of a 5.

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 ('Read buffered campaign events and asynchronous write errors') with the crucial scope qualifier 'without consuming them'. It explicitly distinguishes itself from the sibling chat_read, 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?

Gives an explicit trigger ('Use after WS writes') and names the alternative plus its selecting condition ('use chat_read for persisted chat history'). It further excludes a wrong use case ('this is not durable dice history'), which is the strongest form of 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?

Annotations already mark this non-read-only, destructive, and non-idempotent, but the description adds substantial operational context: DM-only structural actions, v1.4.0 player-roll behavior, unverified legacy permissions, non-idempotent effects, and dispatch-pending semantics that are not a business ACK. It also explains the dice_roll queue exception and requires events_poll inspection before resending.

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, then details are grouped by usage, permissions, action parameters, and return behavior. It is dense and largely earns its length for a complex multi-action tool, though the return-value explanation partially overlaps the output schema and some version caveats could be tighter.

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 eight-action, permission-sensitive combat tool with seven parameters, the description covers purpose, alternatives, action-parameter requirements, gating rules, version caveats, dispatch semantics, and error handling. An output schema exists for return shape, and the description still adds the important ACK/pending interpretation.

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

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

With 100% schema coverage the baseline would be 3, but the description goes far beyond the schema by mapping required companion parameters per action, gating roll to specific systems, clarifying expression as a fallback rather than an override, and noting version-specific character_name behavior and CoC7e DEX ordering.

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

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

The first sentence gives a specific verb and resource set: modify campaign combatants, initiative values, order, or combat lifecycle. It also names initiative_read and events_poll as alternatives, so an agent can distinguish it from sibling read/poll 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?

It explicitly routes state reading to initiative_read and result/error checking to events_poll, and warns against blindly resending. It also gives permission context, but does not fully spell out when to choose between individual actions for a given player intent beyond the action-parameter mapping.

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

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

Goes well beyond the annotations by disclosing timeout semantics (up to two seconds, timeout returns state=null/stale=true and is not proof combat is inactive), cache staleness under refresh=false, idempotence rationale, WS authentication requirement, recipient filtering, and freshness generation rules. This is exactly the kind of behavioral context annotations cannot 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 purpose and alternative routing, then behavior and return contract. Dense but every sentence carries operational information; the only mild cost is readability from packing many clauses together.

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 routing, permissions, timeout semantics, caching, idempotence, and the success/failure return envelopes even though an output schema exists. Nothing an agent needs to call this correctly 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?

Schema coverage is 100% so the schema already documents the single 'refresh' parameter, but the description adds real meaning: the two-second wait, the null/stale timeout result, and the stale-marking cache path. That is more than restating the schema, though not exhaustive.

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 ('Read initiative state') plus the key negative scope ('without changing turn order or advancing combat'), which immediately separates it from initiative_manage. An agent can identify this tool's role 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?

Explicitly names the alternatives and when to use them: initiative_manage for modifying combat, events_poll for broadcast history. Also states the access precondition ('Campaign members may read') and the refresh=true/false selection rule.

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 and idempotentHint=false, and the description reinforces rather than repeats them by explaining the consequence: every accepted call produces a new map, so retries duplicate state. It also discloses the empty-token/empty-annotation initial state, upstream asset-access checks, server-enforced clamping of width/height and grid defaults, fixed false defaults for fog/illumination/exploration with no inputs to change them, and the difference between REST permission errors and tool-body failures.

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 and sibling routing are front-loaded, and every sentence carries operational content. It is dense to the point of being a wall of text, however, and the return-value/error sentences could be tightened given an output schema exists.

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 six-parameter non-idempotent mutation with an output schema, it covers everything an agent needs: assets must pre-exist (no upload), DM-only authorization, clamping behavior, non-idempotency, and the split between upstream diagnostics and {ok:false} tool-body errors.

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 meaning the schema cannot express: dimensions are capped at 500 squares and grid sizes outside 10..500 are coerced to 50, both server-enforced. It also explains that fogEnabled/globalIllumination/explorationEnabled are deliberately absent as inputs, pre-empting a hunt for missing parameters.

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

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

Opens with a specific verb and resource plus a scope qualifier: "Create a campaign map using existing image assets (DM only)." It immediately distinguishes itself from map_list and map_switch, and the phrase "not an uploaded image" rules out a plausible misreading of image_url.

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 map_list to inspect, map_switch to activate, and notes that creation does not switch the current map. It also gives a genuine when-not-to-call rule: "Each accepted call creates another map; do not blindly retry an uncertain result," which directly explains the non-idempotent annotation.

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

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

The description goes well beyond the annotations: it discloses that deletion is destructive with no undo, that repeating the call may return a not-found error, that the current map cannot be deleted, and that success returns {ok:true,data} while failures return {ok:false,error}. It also explains the upstream response shape and error handling, which is valuable context not present in the annotations.

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

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

The description is dense but well-organized: it front-loads the core action and constraints, then covers alternatives, error behavior, and return format. Every sentence adds information, though the length is slightly high for a single-parameter tool. Still, the density is justified by the destructive nature and error semantics.

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 single-parameter tool, the description covers all essential context: prerequisites (map_list, map_switch), the current-map restriction, idempotency behavior, return shapes, and error handling. The output schema exists, so return values need not be detailed further. Nothing an agent needs to call this 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?

The schema already documents map_id with 100% coverage, so the baseline is 3. The description adds the critical constraint that map_id must not be the current map, which is not in the schema description. This extra semantic guidance justifies a 4.

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

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

The description states a specific verb ('delete') and resource ('campaign map'), and explicitly distinguishes itself from token_delete and map_switch. It also names the sibling map_list for inspection, making the tool's purpose and scope unambiguous.

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

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

The description gives explicit when-to-use guidance: inspect with map_list first, use map_switch to select another current map before deletion, and use token_delete for single-token removal. It also warns that upstream rejects deletion of the current map with HTTP 400, which is a clear exclusion condition.

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/openWorld, so the bar is lower, yet the description adds real value: permission nuance ('Read-only for campaign members; non-DMs may see only the current map') and the explicit non-effects (no switching, no token placement). 'Repeated calls leave game state unchanged' merely restates idempotentHint, which costs it a point.

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 purpose, then alternative routing, then permissions, then failure modes — a sensible ordering with no padding. Slight redundancy remains: idempotency is restated despite idempotentHint, and the return-shape sentence is partly redundant with the output 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 zero-parameter read tool with a full annotation set and an output schema, the description supplies everything an agent still needs: scope, the sibling it is not, caller-dependent visibility, and the distinction between tool-body failures and MCP argument errors.

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 takes zero parameters, so there are no parameter semantics to explain and the description neither omits nor misstates anything. Baseline 4 applies; nothing in the schema needs 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+resource ('List maps accessible in the configured campaign') plus the agent-facing goal ('choose a map ID and inspect dimensions'), which distinguishes it from the related write tool map_switch. An agent can route correctly 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?

Explicitly names the alternative and the condition that selects it: 'Use map_switch to activate one; listing does not switch maps or place tokens.' It also contextualizes why to call it (to obtain a map ID). It stops short of spelling out a when-not-to-use case, but the alternative routing is unusually clear.

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

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

Annotations already flag destructive=true, idempotentHint=false, and openWorldHint=true, but the description goes well beyond them: it discloses that REST persistence and WS dispatch are separate, that persisted=true does not prove clients received the change, that a WS failure yields ok=false with data.persisted=true, and that the agent must not replay or roll back. It also explains the broadcast receipt semantics (sent=true, confirmed=false, status='pending') and directs the agent to events_poll rather than expecting an ACK. This is unusually rich operational context.

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

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

The purpose is front-loaded and almost every sentence carries operational weight, but the prose is dense and run-on in places, and the version note ('v1.5.0 retains the REST-first current-map rule') is borderline filler for a one-parameter tool.

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

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

An output schema exists, so the description does not need to explain return values, yet it usefully clarifies the ok=true/ok=false envelope and the distinction between tool-body failures and MCP argument-schema errors. Combined with the failure-handling guidance, it is effectively complete, with only minor redundancy against the output schema.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema already documents that map_id is an existing map ID from map_list. The description adds no syntax or format detail beyond that, so the baseline of 3 applies.

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

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

The first sentence states a specific verb and resource: 'Set the current campaign map through REST, then notify via WS map.change.' It explicitly distinguishes itself from siblings, noting map_list is for choosing an existing map and token_move changes a token rather than the active map. An agent can select this tool 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?

Alternatives are named with the condition that selects them: use map_list to pick an existing map, and token_move is explicitly not for the active map. The 'DM only' constraint and the warning that repeating may re-notify even when the map is already correct give clear 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?

The description goes well beyond the annotations by disclosing that no dice are rolled, no campaign-visible message is sent, the server enforces a 50-per-campaign limit, and creation is not globally serialized. These are important side-effect and concurrency traits not captured by readOnlyHint, idempotentHint, or destructiveHint alone.

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

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

The description is longer than minimal, but each sentence contributes useful context such as alternatives, side-effect behavior, limits, and return shape. It is front-loaded with the core purpose, though the concurrency and MCP-error details could be trimmed without losing essential guidance.

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 output schema, the description is complete: it states ownership, limits, side effects, return conventions, and error behavior. An agent has enough information to decide when to call it and what to expect.

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 schema already documents both parameters with trimming constraints. The description reinforces that the expression is parsed without rolling, but it does not add meaning beyond what the schema provides.

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

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

The description uses a specific verb and resource: 'Save a private dice-expression macro for the current user and campaign.' It also explicitly distinguishes itself from dice_roll and saved_roll_update, 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 clearly tells the agent when to use this tool versus alternatives: use dice_roll to execute, use saved_roll_update to edit, and this tool to create. It also clarifies that members manage only their own macros, providing scoping guidance.

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

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

Annotations already signal destructive and idempotent behavior, and the description adds substantial context: deletion is limited to the macro only, roll history is unaffected, repeated invocation may yield a not-found error, and no dice are rolled. No contradiction with the annotations exists.

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

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

The description is compact and every sentence adds value: action first, then alternatives, access constraints, destructive scope, idempotency behavior, and error/response format. No filler or redundant restatement of the tool name.

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 deletion tool with an output schema and rich annotations, the description is fully adequate. It covers prerequisites, access boundaries, side effects, retry behavior, and return shapes, leaving no operational ambiguity.

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

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

Schema description coverage is 100%, and the macro_id parameter is already documented as owned by the authenticated user in the configured campaign. The description reinforces the ownership constraint but adds little beyond the schema, so baseline 3 is appropriate.

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

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

States the specific action ('Delete'), resource ('your Saved Roll'), and scope ('configured campaign'). It is clearly distinguished from the sibling update/list operations by naming the deletion action and contrasting it with saved_roll_update.

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 to saved_roll_list for identification and saved_roll_update for alteration without deletion. It also clarifies ownership constraints, cross-user/cross-campaign 404 behavior, and repeated-deletion outcomes, giving clear when-to-use and retry guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds context that no dice are rolled, macros are not consumed, and no individual get is needed. It also discloses success and error return shapes. The description does not contradict annotations and adds meaningful behavioral detail beyond the structured fields.

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 tightly written, with every sentence contributing: scope, usage pointers, read-only behavior, non-consumption, and return format. It is front-loaded with the core purpose and keeps alternatives and error handling to a short tail. 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 zero-parameter read-only listing tool with a rich annotation set and output schema, the description is nearly complete. It covers purpose, follow-up actions, side-effect-free behavior, and error envelope. It does not enumerate exact response fields, but the presence of an output schema lessens that need; a short note on pagination or ordering would push it to a 5.

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 schema carries no parameter burden. The description adds useful return and usage semantics: it explains what the list contains, what it does not do, and how the response is structured. This compensates adequately for the absence of parameter-level documentation.

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

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

The description states a specific verb and resource: 'List complete Saved Roll macros owned by the current user in this campaign.' It clearly distinguishes from sibling tools like saved_roll_create, saved_roll_update, and saved_roll_delete, and even directs users to dice_roll and saved_roll_update for follow-up actions. This is unambiguous and contextually grounded.

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 explains when to use this tool: to list saved rolls, without needing an individual get, and without rolling dice. It also mentions that repeating the list does not consume macros and that it is read-only for campaign members. This provides clear usage context and effective routing relative to dice_roll and saved_roll_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?

Beyond annotations, it discloses that replacing values does not roll dice, that repeated writes may change update metadata and thus full idempotency is not guaranteed, and that upstream validates expressions and enforces ownership. It also explains the success/error return envelope, which is valuable context not present in the annotations.

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

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

The description is dense but well-organized: action first, then sibling routing, then update semantics, then behavioral caveats, then return format. Every sentence earns its place and no unnecessary filler is present.

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 partial-update mutation tool, this is complete: what it updates, how to find the target ID, what happens with nulls and multiple writes, ownership validation, and both success and failure response shapes. The presence of an output schema does not create a gap because the description covers the relevant behavior.

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

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

Schema description coverage is 100%, so the schema already documents name, macro_id, and expression meanings plus null-count semantics. The description adds the useful pointer to use saved_roll_list to find macro_id, but otherwise largely restates what the schema already covers.

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

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

The description uses a specific verb ('Change') and names the exact resource and fields ('name or expression of your Saved Roll in this campaign'). It also distinguishes itself from related siblings by pointing to saved_roll_list for ID lookup and dice_roll for execution.

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 tells the agent when to use this tool ('Change the name or expression') and names alternatives with their conditions: use saved_roll_list to find the ID and dice_roll to execute. It also clarifies the partial-update contract: supply at least one field, null leaves it unchanged.

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 read-only/idempotent/non-destructive, and the description adds concrete non-obvious behavior: notes are shared with all members and repeated reads do not end or resume sessions. It also discloses the success/error return envelope, going beyond the annotation hints.

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

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

Every sentence carries distinct information: scope, sibling routing, safe-read behavior, and failure semantics. There is no filler, and the most important functional scope 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 zero parameters and strong annotations plus an output schema, the description covers all remaining decision-relevant details: result ordering/count, active-session inclusion, shared notes, read-only guarantees, and MCP error behavior. Nothing essential is missing.

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

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

The tool has zero parameters, so the schema needs no help; the description's mention of the campaign scope is context rather than parameter documentation. Baseline 4 applies because there is no parameter burden to compensate for.

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

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

The description opens with a specific verb-resource pair and exact scope: 'List this campaign's latest 50 sessions in descending sessionNumber order, including active sessions.' This leaves no ambiguity about what the tool returns and contrasts with sibling session 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?

It explicitly routes lifecycle changes to session_manage and recaps to session_notes_update, telling an agent when not to call this tool. It also clarifies that reads are safe and repeated reads have no lifecycle side effects, which is strong when-to-use guidance.

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

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

Annotations already say destructiveHint=true and idempotentHint=false, but the description goes further: it explains non-idempotency in practical terms, discloses that notes and save_state apply only to end, and clarifies that save_state is not a bridge-side backup. It also warns that empty end text does not clear an existing recap and that the tool does not wait for a WS business ACK. These are meaningful behavioral nuances beyond the annotations.

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

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

The description is dense but every sentence earns its place: purpose, sibling routing, lifecycle rules, notes/save_state constraints, and return format. It is front-loaded with the core action and ends with structured return behavior, with 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 non-idempotent, destructive, state-changing tool with conditional parameters, the description covers what is needed: when each action applies, what fails, how notes and save_state behave differently per action, return success/error shapes, and the DM-only restriction. The presence of an output schema means detailed return fields are not required, and the description still summarizes the success/error envelope.

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%, which establishes a baseline of 3. The description adds extra semantics beyond the schema: notes are 'campaign-wide', nondefault notes/save_state values are rejected for start/pause, and save_state requests an 'upstream' snapshot rather than a local backup. These details enhance understanding of all three parameters, so a score above baseline is warranted.

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

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

The description opens with a specific verb-resource pair ('Start, pause, or end a campaign session') and immediately scopes the tool to 'REST (DM only)', which clearly distinguishes it from read-only or notes-related tools. It also explicitly names the two most relevant siblings (session_list and session_notes_update), so an agent can differentiate without inspecting schemas.

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

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

The description explicitly instructs when to use alternatives: 'Use session_list to inspect history and session_notes_update to edit or clear a recap without another lifecycle transition.' It also explains that pause/end fail if no active session exists, and warns against repeating start/end to repair notes because changes are not idempotent. This is concrete, actionable usage guidance.

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

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

Annotations already signal destructive and non-idempotent behavior, and the description adds meaningful details: repeated writes may alter metadata, empty text clears the recap, the tool does not end the session or broadcast a recap event, and it explains the distinction from session_manage. 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?

Every sentence is informative and earns its place. The description front-loads the core purpose, then gives usage routing, behavioral caveats, and return/error semantics in a compact but complete block.

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

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

Given the tool's destructive and non-idempotent nature, the description is remarkably complete: it covers lifecycle impact, permissions, ID discovery, clearing behavior, idempotency caveat, return shape on success, tool-body failures, and schema-error handling. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a useful edge-case nuance by explaining that empty text clears the recap 'unlike empty notes on session_manage end,' and it reinforces the complete-replacement semantics. This goes slightly beyond the schema, but most parameter meaning is already present there.

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: 'Replace a session's shared recap.' It also distinguishes itself from the lifecycle tool by saying 'without another lifecycle transition' and later 'Does not end the session or broadcast a recap event.' This clearly differentiates it from session_manage.

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 direction: use session_list to find the ID, and use session_manage to start/pause/end instead. It also notes the DM-only restriction and clarifies that all campaign members can read notes, which helps an agent decide whether this tool is appropriate for the situation.

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

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

Goes far beyond annotations: explains non-idempotency ('every accepted call creates another token'), coordinate clamping and whole-square requirements on newer servers, the controlled_by autoassign/null-vs-omit distinction, REST persisted=true but broadcast_confirmed=false, and the recommendation to inspect events_poll or the VTT. Also describes upstream permission/bounds/image checks and the ok/error return shape. This is exactly the behavior an agent cannot infer from annotations alone.

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

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

Dense but well structured, with purpose and alternatives first, then behavioral caveats, then return semantics. It is longer than typical but nearly every sentence carries operational value for an 11-parameter, version-sensitive mutation tool. Minor redundancy around persistence/broadcast 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?

Output schema exists, yet the description still adds the important success/error distinction (tool-body {ok:false,error} versus MCP argument-schema errors) and the broadcast caveat. Combined with DM-only scope, upstream checks, and idempotency, an agent has what it needs to call this correctly and interpret ambiguous results.

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; the description adds value by clarifying map-unit coordinates, integer 1..10 width/height, the controlled_by null-versus-omitted wire semantics, and what character_id linking does. It doesn't re-document every parameter, but the added semantics are meaningful 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?

States a specific verb, resource, scope, and audience: 'Create a manually configured token on a campaign map (DM only).' It immediately names the sibling tools it is not (token_place_creature, token_move, character_create), so an agent can select it without opening other 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?

Explicit routing: use token_place_creature for library templates, token_move for existing tokens, character_create when a new sheet is needed, and this tool only for a manually configured token. That covers when to use and when not to use in a single front-loaded sentence.

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 destructiveHint and idempotentHint, and the description adds substantial context beyond that: what destruction entails (removes the placed token, not the linked sheet/HP; removes combatants and repairs initiative order), no undo tool, and repeat-call behavior (token absent but may return not-found). All of this is consistent with the annotations rather than 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?

Front-loaded with the core action and the alternative tools, then back-loaded with behavioral and return details. It is dense but mostly earns its place; a couple of clauses (restating destructiveness, error paragraph) slightly overlap with what annotations and the output schema already carry.

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?

Very complete: it covers the mutation's side effects, idempotent-effect behavior, the {ok/data/error} return contract, and where diagnostics surface, while an output schema exists to carry structured returns. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and both params are fully documented there, including the token-vs-character-ID distinction. The description reinforces that same distinction but adds no new syntax or format detail beyond the schema, so the 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+resource and scope ('Delete one token from a campaign map (DM only)'), and explicitly names the sibling alternatives (token_move, token_hp_update). An agent can distinguish this from token_move/token_add 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?

Explicitly routes the agent: use token_move to reposition, token_hp_update for HP edits, and clarifies token_delete takes a map token ID rather than a character ID. It even warns not to send a second initiative write, which is actionable when-to-use guidance.

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

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

Annotations cover the safety profile (destructive, non-idempotent, openWorld), and the description goes well beyond them: it discloses the ownership/DM authorization requirement, the spectator exclusion, that repetition re-applies the delta, and the critical async distinction that a 'sent:true,confirmed:false,status:pending' dispatch is not a business ACK. That pending-vs-confirmed semantics is exactly the kind of behavioral context annotations cannot express.

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 and the sibling routing are front-loaded, and every section carries real operational weight (auth, idempotency, async ACK, error modes). It is somewhat dense and repeats return-shape information ('sent:true,confirmed:false' then '{ok:true,data}') that an output schema already covers, which costs a point but does not obscure the essential guidance.

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, non-idempotent, async, authorization-gated mutation, the description supplies everything needed: the target entity, the auth requirement, idempotency warning, the pending-vs-confirmed dispatch model, follow-up via events_poll, and the success/failure envelope shapes. Nothing an agent needs to invoke it safely is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters in detail (signed delta semantics, campaign-assigned character ID vs map token ID). The description restates 'positive heals, negative damages' and the token-vs-character distinction without adding syntax or format detail beyond the schema, so the 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 gives a specific verb+resource ('Apply a signed HP delta to a character sheet') and immediately corrects the misleading name by stating it operates on a character sheet, 'not to a token ID.' It explicitly routes to siblings (character_get for inspection, character_update for an absolute patch), so an 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 the alternatives and the conditions that select them ('use character_get to inspect HP or character_update for an absolute sheet patch'), and adds an operational rule for the async flow ('Read events_poll for results/system.error ... never blindly resend'). When-to-use, when-not-to-use, and post-call behavior are all explicit.

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

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

With annotations present, the description still adds substantial non-structured context: bridge role rejection, upstream control/plane/session restrictions, null token fields, whole-square coordinate enforcement, footprint clamping at map edges, and the crucial caveat that the write is not a correlated broadcast ACK (broadcast_confirmed=false, no map.changed emitted by REST). It also explains why repeated identical writes are not a no-op (notifications), which reconciles with idempotentHint=false rather than contradicting it.

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

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

Front-loaded with the core operation, and nearly every sentence adds an operational constraint or failure mode. It is dense and somewhat run-on, with the error-contract sentence trailing at the end where it is least visible, 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 mutation tool with real upstream permission, coordinate, and broadcast semantics, the description covers preconditions, edge-case behavior, and the success/failure envelope. It goes beyond what the output schema alone conveys by warning against assuming the move was observed.

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 carries the per-parameter burden and 3 would be the baseline. The description still adds meaning beyond the schema: whole-square coordinate requirements on newer servers, clamping of the token footprint at map edges, and the instruction to read the returned position rather than trust the requested one. Some sentences duplicate schema text verbatim (the PLAYER/DM map line on map_id).

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 with scope: "Set an existing token's absolute position through REST." It immediately distinguishes itself from token_add (creation) and map_switch (active map), so an agent can route 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?

Names the sibling alternatives explicitly (token_add for creating, map_switch for changing the active map) and states the role conditions under which this tool applies (DM may use any campaign map, PLAYER only the current campaign map). It also points to events_poll/VTT as the verification path. It stops short of explicitly stating exclusion cases for the move itself, so a 4 rather than 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description goes well beyond them: DM-only read, failure before creation when no usable image exists, map-bound position constraint, per-call token creation, no broadcast receipt, upstream image-access validation, and a pointer to events_poll for visibility. It also discloses return shapes and the tool-body vs MCP error distinction.

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-loads the purpose and routing guidance before the behavioral detail, and most sentences carry distinct information (failure mode, DM-only, repeat-creation, error shapes). It is somewhat dense and there is minor redundancy re-stating the return shape despite an output schema, but 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 4-required-param mutation with full schema coverage, annotations, and an output schema, the description covers every decision-relevant gap: prerequisites, DM-only scope, failure conditions, non-idempotency, and how to observe results. 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%, so the schema already documents all four parameters including the image-source requirement and the x/y bounds. The description's 'Position must be within the map' and image references restate rather than extend the schema, 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 ('Create a visible 1x1 token from a library template') and immediately scopes it (DM only). It explicitly contrasts itself with the sibling token_add, so an agent can differentiate the two without reading 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 routes the agent: 'use creature_search to obtain a template ID' for the prerequisite, and 'use token_add for custom size, layer, controller, visibility, or a character link' for the alternative. This is a textbook when/when-not/alternative breakdown.

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