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

Annotations already declare destructive=true, non-idempotent, not read-only. The description adds real value beyond them: mutating actions 'persist to the Novel and are audited', read-only actions do not mutate, and the undo route is specified. It stops short of describing what persisted state looks like or what 'audited' implies operationally.

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 capability, then structured into mutation semantics, revert path, and explicit use/do-not-use guidance. Dense but each clause carries a distinct rule; no obvious filler, though it is longer than strictly necessary.

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, return values need not be explained. The description covers mutation persistence, undo, default target behavior, the force bypass, and sibling routing — everything an agent needs to invoke this multi-action 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 coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: generate defaults target to novel when one is active, and a '!force' prefix bypasses the guard. Those are behavioral rules for parameters not encoded anywhere 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?

Opens with a specific verb set and resource ('Generate, load, or list adventure content') and immediately scopes each action into mutating vs read-only. It also names the siblings it is distinct from (manage_history, manage_story), so an agent can route 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 provides 'Use when' (GM wants a scaffold, single encounter, or to load a module) and 'Do NOT use when' (recording a story beat → manage_story). It also names the revert path via manage_history, giving complete routing guidance.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses that mutations persist to the Novel and are audited, that list/get are read-only, that the most recent mutation is revertible via manage_history undo, and that terminal tasks are immutable. These are non-obvious behavioral traits that an agent could not derive from the annotation flags 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 opening sentence front-loads the core purpose, followed by mutability/audit facts, the undo path, and a compact when/when-not block. Every sentence carries distinct information with no filler, despite covering a large action surface.

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

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

For a 7-parameter mutation tool with an output schema present, the description covers purpose, mutability, audit/persistence, undo, immutability constraints, and sibling routing. Return values need not be explained because the output schema exists, so nothing an agent needs to invoke 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?

Schema coverage is 100%, so the baseline is 3, but the description adds lifecycle meaning to the action parameter by glossing how each value is used ('logging an action (advance)', 'settling it (complete/fail/cancel)'). This clarifies the operational intent of the enum beyond the bare schema listing, though it does not add syntax or format detail for the other parameters.

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

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

The description states a specific verb and resource ('Manage durable NPC/agent tasks and their action lifecycle') and enumerates the concrete operations (create, start, advance, complete, fail, cancel, list, get). It is clearly distinguishable from siblings like manage_scene, manage_npc, and manage_history, which are each named with a disambiguating condition.

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

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

It has explicit 'Use when' and 'Do NOT use when' sections, and routes the agent to alternatives with the exact call syntax: manage_history (action: undo), manage_scene (action: oracle), manage_npc. Both the positive triggers and the exclusions are spelled out, leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds action-level transparency: mutating actions admit, retract, and reconcile persist to the Novel and are audited, while list/get/evidence/conflicts are read-only. It also notes that the most recent mutation can be reverted with manage_history. It stops short of detailing permissions or exact undo scope, but goes well beyond the annotations.

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

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

The description is dense but well-structured: a definition, a mutating/read-only split, a revert note, and then explicitly labeled 'Use when' and 'Do NOT use when' sections. Every sentence serves routing or selection, and the most important distinctions are 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?

Given a 12-parameter tool with an output schema and rich annotations, the description covers purpose, action semantics, mutability, alternates, and a revert path. Output values are left to the output schema, and safety hints are covered by annotations. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters in detail. The description adds meaning for the action enum by mapping each action to an intent (e.g., admit for recording what an entity believes, retract for suppressing evidence), but does not elaborate on the other parameters beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource, defines the domain as per-entity subjective epistemic state, and explicitly distinguishes it from objective truth, shared lore, raw observation, and consumed reference material. It names the sibling tools for each contrasting domain, making it easy to route correctly.

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 'Use when' guidance mapping each action to a concrete scenario and a 'Do NOT use when' section that names alternatives (manage_causal, manage_world, manage_lore, manage_perception, manage_corpus). The inclusion of the revert path via manage_history further clarifies the lifecycle.

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

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

Annotations already flag this as a destructive, non-idempotent, non-read-only tool, and the description adds substantial context beyond that: proposals are ledgered before admission, unadmitted proposals are not truth, refused proposals are preserved as evidence, mutations are audited, and list/state are read-only. It also discloses the origin_source-vs-ingress override rule and points to manage_history (action: undo) for reverting the most recent mutation.

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?

It is a dense block rather than a short one, but it is front-loaded with the core semantic and each sentence carries distinct information (ledger behavior, action routing, exclusions, revert path). Slightly long, 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 an 11-parameter, six-action mutation tool with an output schema, the description covers the mutable lifecycle, read-only exceptions, action selection, and revert path. Nothing an agent needs to invoke it 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 baseline is 3, but the description adds real semantics the schema does not: origin_source is honored only by propose, ingress always records machine-originated state, and undo lives in a separate tool. That said, several parameters (key, scope, from, expected_version, source_ordinal) get no added meaning.

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

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

The description names a specific verb+resource ('Validate objective-state transitions against committed history') and frames the tool's core semantic — objective truth vs. belief — which immediately separates it from manage_belief and manage_perception. It also enumerates the six actions so the agent knows the tool's full surface 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?

Explicit 'Use when' clauses map each action (propose/admit/reject/ingress/list/state) to a scenario, and a 'Do NOT use when' section names three concrete alternatives (manage_belief, manage_perception, manage_world) with the condition that selects each. This is about as good as routing guidance gets.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is partly covered. The description adds real value beyond that: it separates mutating actions (which persist to the Novel and are audited) from read-only actions, and points to the undo route. It does not describe failure modes or per-action side effects, so it stops short of a 5.

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

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

Given 25 parameters and 11 actions, the description is compact and front-loads the action inventory before the behavioral and aliasing notes. Every sentence carries weight (scope, audit/undo, alias precedence, sibling exclusion). Minor density in the alias sentence, but 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 large multi-action tool with an output schema already present, the description covers what the schema cannot: the read/write split, audit behavior, undo routing, alias precedence, and the sibling boundary. It is close to complete; per-action return shapes are rightly deferred to 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 coverage is 100%, so baseline is 3, but the description earns extra credit by explaining the aliasing rules: personality{} aliases description/voice/background/goals and details{} aliases ability_scores/skills/feats/talents/equipment, with a top-level value overriding its grouped alias. That precedence rule is not evident from the schema alone and materially affects how an agent should build the call.

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 ('Manage player characters') and then enumerates the full action surface — create, stage, import, sheet, set_active, personality, voice, signal, remove, roster_list. It explicitly differentiates from the closest sibling ('Do NOT use when: managing NPCs — use manage_npc'), so 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?

It gives an explicit when-to-use ('working with player characters'), an explicit when-not ('managing NPCs'), names the alternative sibling, and additionally documents the undo path via manage_history (action: undo). Nothing about selection is left to inference.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so safety is partly covered. The description adds valuable context beyond annotations: that mutations persist to the Novel and are audited while reads do not mutate, and that update_source requires artifact provenance and capture's source_id fallback. It could still note irreversibility of delete more explicitly, but the audit/persistence details are strong.

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 every clause earns its place: purpose, mutation/audit semantics, undo route, parameter fallbacks, and explicit when/when-not with alternatives. Front-loaded with the core purpose before routing 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?

An output schema exists so return values need not be explained. Combined with annotations covering safety and the description covering scoping, persistence/audit, undo, parameter fallbacks, and sibling routing, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds genuine semantics beyond the schema: capture's source_id fallback to entity_id, and update_source requiring artifact provenance. These are behavioral constraints on parameters not spelled out in the schema descriptions.

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

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

States a specific verb and resource: managing a cross-Novels codex library of reusable content, and enumerates the kinds (NPCs, factions, rooms, spells, adventures, voice profiles). It distinguishes itself from siblings by explicitly naming manage_lore and manage_note as the route for Novel-scoped content.

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 (storing reusable content for later import, enumerating/reading/deleting) and when-not-to-use with concrete alternatives (manage_lore action:set, manage_note action:set). It also routes undo to manage_history and states provenance requirements for update_source.

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 mutating, destructive, non-idempotent behavior; the description adds that mutations persist and are audited, and points to manage_history for undo. It also clarifies init seed semantics. This goes beyond annotations, though it doesn't detail all side effects (e.g., what data is lost on end).

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 usage guidance and caveats. Sentences are dense but each earns its place; no obvious filler, though it could be slightly 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?

Given the tool's complexity (6 params, multiple actions, destructive mutations) and the presence of an output schema, the description covers key operational context: audit trail, undo path, seed semantics, and action scope. It leaves minor gaps like all action prerequisites or full side effects, but is largely complete.

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

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

Schema coverage is 100%, so parameters are fully documented in the schema. The description adds behavioral nuance for seed and participant order but does not elaborate on outcome or participant_id beyond what the schema states. Baseline 3 is appropriate.

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

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

Description states a clear verb+resource ('Manage combat encounters in the active Novel') and mentions the mutating vs read-only distinction. It does not explicitly differentiate from sibling manage_condition beyond a do-not-use note, which is helpful but partial.

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 lists when to use ('starting, advancing, ending a fight, or changing its participants') and when NOT to use ('applying a status effect — use manage_condition (action: apply)'). Names the alternative tool directly.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real context: mutating actions persist to the Novel and are audited, read-only actions do not mutate state, and the undo path is manage_history. It stops short of stating what removal actually destroys or whether undo is time-limited, so a 4 rather than 5.

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

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

Four tightly packed sentences, each carrying distinct information (action scope, persistence/audit behavior, undo route, routing exclusions). The use/when-not framing is front-loaded and scannable.

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

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

With annotations covering the safety profile and an output schema present, the description only needs to cover routing and behavioral quirks — which it does, including the audit/persistence trait and the undo alternative. 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 action, condition, entity_id, and rounds. The description maps actions to use cases (apply/remove/list) but adds no syntax or format detail beyond the schema, making the baseline 3 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 (manage) plus resource (mechanical/narrative conditions on entities) and explicitly contrasts itself with manage_combat for damage/combat state. An agent can distinguish this from its many siblings without opening the schema.

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

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

Provides explicit when-to-use ('applying, removing, or listing conditions') and when-not ('recording damage or combat state — use manage_combat'), naming the alternative tool and action. It also routes undo to manage_history. This is the full when/when-not/alternative pattern.

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 give a tool-wide destructiveHint/openWorldHint, but the description adds action-level resolution: register/route/grant/deny/access/consume persist to the Novel and are audited, while list/get/acquisitions are read-only. That action-level write/read split and the audit disclosure are exactly the 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?

Information-dense and front-loaded, with the core definition first, then mutation/read split, then use/don't-use routing. It is a single long semicolon-chained paragraph, which slightly taxes scanning for the action-to-purpose mapping.

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 exists (so return values need not be explained), the description covers concept, per-action semantics, write/audit behavior, undo path, and sibling exclusions. Nothing needed to call a 13-param, enum-heavy 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; the description goes further by tying enum action values to their parameter roles (register, route, grant/deny, access, consume, acquisitions), which helps select the right action and its companion fields. It does not add syntax or format details for individual fields 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?

Names the resource (cold reference material / corpus documents) and the operations (register, route, grant/deny, access, consume, acquisitions), and crisply defines the concept: consumption records what an entity acquired, 'distinct from belief and from lore.' An agent can distinguish this from manage_belief/manage_lore/manage_codex 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?

Provides an explicit 'Use when' clause mapping each action to its intent, a 'Do NOT use when' clause naming three sibling alternatives, and routes undo to manage_history (action: undo). When-to-use, when-not-to-use, and alternatives are all present.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds real context beyond them: mutating actions persist to the Novel and are audited while read-only actions do not mutate state, mutation is reversible via manage_history (action: undo), and set's direction only shifts NPC dispositions when scope is also set. That is a conditional side-effect rule and a recovery path an agent could not infer from 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?

Four tightly packed sentences, zero filler, with the mutating/read-only distinction and the sibling exclusion front-loaded before the conditional detail. Each sentence adds information.

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

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

With an output schema present and 100% schema coverage, the description need not restate returns or parameters. It covers scope of operation, mutation semantics, sibling disambiguation, and the undo path — everything needed to call this 9-parameter 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 carries the per-parameter burden and baseline is 3. The description adds a genuine cross-parameter rule ('direction shifts NPC dispositions only when scope is also set') that the schema does not express, exceeding baseline.

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

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

States a specific verb+resource ('Manage countdown timers in the active Novel') and explicitly distinguishes itself from the closest sibling ('use manage_vow (action: milestone)' for vows). An agent can route correctly 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?

Explicit 'Use when: starting, advancing, removing, or listing clocks' and 'Do NOT use when: tracking a vow's progress' with the named alternative. Both the positive and negative conditions are stated.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, but the description adds materially: mutating actions persist to the Novel and are audited, read-only actions do not mutate state, and the most recent mutation is revertible via manage_history. What's missing is any statement of permission/auth requirements or confirmation semantics for destructive removes.

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

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

Three dense sentences with zero filler: scope first, then mutation/audit behavior plus the undo path, then the use/don't-use routing. Every clause earns its place and the most decision-relevant information is front-loaded.

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

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

With an output schema present, return values need not be described. The description covers scope, mutation semantics, audit/persistence, revert path, and the sibling-boundary exclusion, leaving nothing an agent needs to select or 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% across all 7 parameters, including the action enum, so the schema carries parameter meaning and the baseline is 3. The description adds only indirect hints (factions and 'their progress clocks'), and notably 'progress clocks' is not represented in any parameter, so it does not extend parameter understanding.

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

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

States a specific resource (factions/organizations in the active Novel) and enumerates the concrete operations via the 'Use when' clause (creating, revising, removing, listing factions and their progress clocks). It distinguishes itself from sibling manage_world explicitly, so an agent can route 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?

Provides both inclusion ('Use when: creating, revising, removing, or listing factions') and exclusion ('Do NOT use when: tracking a faction's territory rooms — use manage_world (action: create_room)'), naming the alternative tool and action. It even routes undo operations to manage_history (action: undo), which is explicit alternative guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, so the safety profile is covered. The description still adds real value beyond them: both directions mutate and persist immediately, and the operation restores a per-badge snapshot limited to the most recent mutation. It does not explain the irreversibility/state-loss implied by destructiveHint, so not a 5.

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

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

Front-loaded with the core verb and scope, and the when/when-not guidance is compact. However, the undo/redo definitions are stated twice (general sentence and again in the 'Use when' clause), and the '(readOnlyHint false)' parenthetical repeats the annotation verbatim, adding mild 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?

An output schema exists, so return values need no explanation. For a single-enum-parameter tool, the description covers purpose, both action semantics, mutation/persistence behavior, and sibling routing — everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 100% with a single enum parameter, so the schema already documents undo/redo fully. The description restates the same meanings ('undo reverts a mistaken or unwanted change; redo re-applies the most recently undone change') without adding syntax or format detail, matching the baseline for high-coverage schemas.

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

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

States specific verbs (undo/redo) plus the exact resource and scope: 'the most recent state mutation, restoring the prior per-badge snapshot.' This distinguishes it from all entity-management siblings, 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?

Contains explicit 'Use when' conditions mapped to each action value, plus a 'Do NOT use when' exclusion that routes the agent to the correct alternative tools (manage_lore, manage_story, manage_world) when the target change is not the most recent mutation.

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=true, readOnlyHint=false and idempotentHint=false, and the description adds value beyond them: mutations persist the roster and are audited, list/snapshot are read-only, and the most recent mutation is revertible via manage_history (action: undo) with a versioned compiled kernel. It does not spell out precisely what a reject/overwrite destroys, if anything, which is the only remaining gap.

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

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

Front-loaded with the core semantics (what it manages, which actions mutate), then usage routing, then exclusions. Some redundancy in restating the action list twice, but every sentence carries routing or behavioral information.

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

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

For a 9-parameter, multi-action, nested-object tool with an output schema already present, the description covers the safety profile, persistence/audit behavior, undo path, and per-action routing. Nothing an agent needs in order to call it correctly is missing, and return values are appropriately left to 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema doesn't: accept's perspective defaults to the candidate's stored perspective, and it groups parameters by the action that consumes them (stage vs accept/reject). This helps an agent pick the right action-parameter combination.

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

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

The description names a specific verb (manage) and resource (a roster character's durable identity), then enumerates the concrete sub-operations (stage, accept, reject, bootstrap, list, snapshot). It explicitly distinguishes itself from sibling tools manage_belief and manage_character, so an agent can route correctly 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 contains explicit 'Use when' clauses mapping each action to a scenario (importing/authoring, accepting/rejecting, seeding from a card, inspecting, reading the kernel) and explicit 'Do NOT use when' clauses naming the alternative tools (manage_belief for knowledge/beliefs, manage_character action: personality for narrative personality). This is the full when/when-not/alternatives triad.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description reinforces this with the key operational fact that index_build/graph_build overwrite the prior in-memory projection. It adds genuinely non-derivable context: builds are audited, the Novel file remains authoritative, and read-only actions never mutate Novel state. It stops short of describing lifetime/eviction of the in-memory projection or any permission requirements, so it is strong but not exhaustive.

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

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

Purpose is front-loaded, then the when/when-not blocks, with no filler sentences; every clause maps to an action or an alternative. It is dense and readable, though the run-on action list would scan faster as a bulleted or structured breakdown.

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, return values need not be explained, and annotations already carry the safety profile. For an 11-action multiplexed tool the description supplies purpose, per-action intent, mutation semantics, authoritative-source rules and sibling alternatives — nothing an agent needs in order to pick the right action is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description goes beyond the schema's terse 'index_* actions operate the semantic index' by explaining what each action actually does, which is the primary discriminator among the five parameters. It does not add format or constraint detail for limit, query, item_id or node_id beyond the schema, so it earns 4 rather than 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 ('Manage derived, in-memory knowledge over Novel sources') and immediately decomposes it into two concrete subsystems: a semantic index for advisory text ranking and a typed knowledge graph. The per-action enumeration and named sibling redirects make it distinguishable from manage_lore, manage_corpus and manage_ruleset 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?

Contains an explicit 'Use when:' clause mapping each of the 11 actions to its task (build, staleness check, list, rank, read relations/graph/nodes/edges/neighbors) plus a 'Do NOT use when:' clause with three named alternatives and the exact alternate action (manage_ruleset action: search). This is the rare definition that routes rather than merely describes.

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

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

With annotations already declaring destructiveHint=true, readOnlyHint=false, and idempotentHint=false, the description adds useful context: mutating actions persist and are audited, read-only actions do not mutate state, and import defaults to dry-run unless merge or replace is chosen. It also explains that the most recent mutation can be reverted via manage_history. The description could go further by detailing specific destructive consequences or permission requirements, but it meaningfully supplements 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 the core purpose and behavioral traits, then structured with clear 'Use when' and 'Do NOT use when' sections. The list of actions in the usage section is somewhat long but each item aids routing, and there is no redundant restatement of the title or schema. It is appropriately sized for a multi-action tool with many siblings.

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 13 parameters, an output schema, and full annotation coverage, the description provides sufficient context: it explains purpose, distinguishes from siblings, clarifies mutating versus read-only behavior, notes the audit and import defaults, and points to manage_history for undo. No additional return-value or parameter documentation is needed because the schema and output schema handle those details.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by specifying that import defaults to dry-run mode and that merge or replace performs writes, which clarifies the mode parameter's default behavior. It also groups actions into mutating versus read-only categories, helping the agent interpret the action parameter without listing every enum value.

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

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

The description states a specific verb and resource: managing the active Novel's lore entries — shared, durable world facts. It distinguishes itself from siblings by explicitly naming manage_story, manage_belief, and manage_perception as alternatives for related but different tasks. An agent can identify exactly what this tool does without opening the schema.

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

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

The description provides explicit 'Use when' and 'Do NOT use when' sections, listing concrete actions (creating, revising, removing, etc.) and naming the correct alternatives for story beats, beliefs, and perceptions. It also directs the agent to manage_history for undo and notes the import default mode. This leaves no ambiguity about when to select this tool versus 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?

Adds real context beyond the annotations: mutations persist to the Novel and are audited, reads do not mutate state, and the most recent mutation is undoable via manage_history. The destructive/audited/reversible profile is consistent with destructiveHint=true and idempotentHint=false, though it doesn't spell out precisely what a remove destroys or permission requirements.

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

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

Dense but front-loaded: identity and scope first, then mutation/audit semantics, then undo routing, then use/don't-use. Every clause carries information; 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 multi-action mutating tool with an output schema, annotations, and full schema coverage, the description supplies the missing decision layer (scratch vs. lore, undo path, defaults). Nothing an agent needs to call it correctly is absent.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns an extra point by disclosing a behavior the schema does not — that set's badge_scope defaults to game_master — which materially affects correct invocation.

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

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

States a specific verb and resource with scope: Novel-scoped scratch notes, badge-scoped to game_master/player/shared. It explicitly differentiates itself from the closest sibling (manage_lore) by naming the boundary between scratch state and durable world facts.

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

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

Provides explicit 'Use when' and 'Do NOT use when' clauses, names the alternative (manage_lore action: set) for durable facts, and routes the undo path to manage_history (action: undo). An agent has everything needed to choose between this and its alternatives.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotence, so the safety profile is largely covered; the description adds real value on top by stating that mutating actions persist and are audited while read-only actions do not mutate state, and that import defaults to dry-run with strict escalating a reference mismatch to a hard block. It stops short of saying what specifically is destroyed or how branching/clone interact with the source Novel.

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 operation list, then behavior, then the when/when-not routing, in four tight sentences with no filler. Size is justified for a 21-action multiplexed tool, and the action enumeration is compressed to a single clause rather than a bulleted expansion of the schema enum.

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

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

An output schema exists, so return-value explanation is unnecessary, and the description still covers mutation/audit semantics, the undo path, import safety modes, and scope exclusions. It is slightly thin on the checkpoint family, which is collapsed into the single word 'checkpoint' even though the schema exposes four distinct checkpoint actions.

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 per-parameter 'which action uses this' annotations already carry most semantic load and the baseline would be 3. The description earns above baseline by disambiguating two behavioral parameters: import defaults mode to dry-run, and strict converts a reference-validation failure into a hard block.

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 concrete verb and resource ('Manage Novel save files') and then enumerates the concrete lifecycle, interchange, branching, and checkpoint operations, so an agent knows this is the save-file lifecycle tool rather than a content tool. It also explicitly names the sibling entity tools it is not, letting an agent separate it from manage_npc/manage_lore 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?

Contains explicit 'Use when: handling a campaign's lifecycle, interchange, return points, or branching a timeline' and 'Do NOT use when: managing content inside the Novel', naming six concrete alternative tools. It additionally routes undo to manage_history (action: undo), giving a clear when-to-use path for reversal.

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 goes beyond them by disclosing that mutating actions persist to the Novel and are audited while read-only actions do not mutate state, plus the undo path via manage_history. It stops short of saying what 'remove' actually destroys or whether operations require specific permissions, so it adds real value without being fully exhaustive.

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

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

Four short sentences, front-loaded with purpose, then behavior, then recoverability, then the use/don't-use rules. No sentence is redundant and no 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?

The tool has annotations, a 100%-covered schema with a nested mind object, and an output schema, so return values and field semantics are already handled elsewhere. The description supplements that with persistence/audit behavior, an undo route, and sibling routing — enough for correct invocation.

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

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

Schema description coverage is 100% and each of the 9 parameters carries its own description including action-scoping hints (e.g. 'NPC identifier (update/remove/get)'), so the schema does the heavy lifting. The prose adds no parameter-level syntax, defaults, or format details beyond it, making baseline 3 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+resource with scope ('Manage non-player characters in the active Novel') and immediately separates itself from the closest sibling via the explicit 'Do NOT use when: managing player characters — use manage_character'. An agent can pick between manage_npc and manage_character 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?

Enumerates the activating cases ('introducing, revising, removing, listing, or reading NPCs'), names an exclusion with a redirect ('player characters — use manage_character'), and provides the recovery route ('Revert the most recent mutation with manage_history (action: undo)'). Nothing is left to inference.

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

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

Adds meaningful context beyond the annotations: the ledger is append-only, the record action persists to the Novel and is audited, and the read actions are side-effect free. This tells the agent which of the four actions mutate and which are safe. The only gap is a mild tension with destructiveHint=true, which an append-only ledger framing does not explain.

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 core purpose, then separates 'Use when' from 'Do NOT use when' in a scannable structure. The list of alternatives is dense but every clause carries routing information; no filler sentences.

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 annotations covering the safety profile and an output schema present (so return values need no explanation), the description supplies all remaining decision-critical context: scope, per-action read/write behavior, and sibling routing. Complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds semantic meaning by tying the action enum values to outcomes (record persists and is audited; list/for_entity/for_event are read-only) and by characterizing the kind values. This goes beyond restating the schema field docs.

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 set (record/read) applied to a concrete resource (what an entity perceived: messages, scene changes, observations) and explicitly positions it as a ledger distinct from belief. An agent can distinguish it from manage_belief and manage_lore 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?

Provides explicit 'Use when' routing for each action (record/list/for_entity/for_event) and explicit 'Do NOT use when' clauses naming the correct alternatives (manage_belief, manage_lore, manage_session action:event). Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds genuinely new context by explaining that mutating actions persist to the Novel and are audited, that read-only actions do not mutate state, and that the last mutation can be reverted through manage_history.

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

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

Four sentences, none wasted: scope, persistence/audit behavior, revert route, and use/do-not-use routing are all front-loaded and each earns its place.

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

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

Output schema exists so return values need no explanation, annotations cover safety, and the description supplies the missing behavioral and routing context (persistence, audit, undo, sibling disambiguation) needed to call this correctly among 30+ siblings.

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

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

Schema description coverage is 100% and two enums (action, type) are already documented in the schema, so the description adds little beyond restating that it sets or reads relationships. Baseline 3 is appropriate when the schema carries parameter meaning.

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 (manage) and resource (directed relationships between entities, NPCs, factions), plus names the sibling it must not be confused with (manage_faction). An agent can distinguish it from the 30+ other manage_* tools 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?

Explicit when-to-use ('setting or reading how two parties relate') and when-not ('tracking faction progress — use manage_faction (action: update)'), plus an alternate recovery path via manage_history (action: undo). This is the full when/when-not/alternative triad.

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=true globally, which is misleading for a tool that mixes reads and writes; the description usefully corrects this by stating search and roll are read-only, install/remove are reversible via the paired action, and the mutating actions are audited. It stops short of describing failure modes or prerequisites for bind/install beyond the reversible pairing.

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 operation list and kept tight, but the first sentence's action enumeration is largely repeated in the 'Use when' clause, creating mild redundancy across an otherwise efficient 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?

For a 14-parameter, 8-action tool with an output schema and full annotation coverage, the description supplies everything an agent needs to choose the right action: action semantics, read vs write behavior, alternative tools for the excluded case, and the wisdom/source precedence rule. Return values are covered by the output schema, so nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine cross-parameter rule: import_supplementary prefers inline 'wisdom' and only reads 'source' when wisdom is absent. That behavior is not derivable from the per-parameter schema text, though the remaining 13 parameters get no added explanation.

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 resource (ruleset packages) and enumerates the concrete operations: search an index, install/remove a package, list installed packages, bind a Novel, roll a generation table, and import/remove supplementary rulesets. This lets an agent distinguish it from the many manage_* siblings 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?

It provides explicit 'Use when' conditions mapped to specific actions and a 'Do NOT use when' clause naming two concrete alternatives (run_command with action: suggest, manage_session with action: health) for the ruleset-free case. This is textbook when/when-not/alternative routing.

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

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

Annotations already declare destructiveHint=true and non-idempotent mutation, but the description adds real value: mutating actions persist to the Novel and are audited, read-only actions don't mutate, undo routes to manage_history, and 'set' derives description from location only when omitted. It stops short of describing auth/permission needs or what persistence means for overwritten scene 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?

Front-loads the core purpose and the persistence/audit rule before the routing clauses; four sentences with little waste. Slightly dense, but every clause earns its place.

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

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

With an output schema, full parameter descriptions, and annotations present, the description only needs to supply routing and mutation semantics, which it does. Minor gap: the choices/oracle resolution actions are named but their result flow isn't described.

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

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

Schema coverage is 100% across 23 parameters with per-parameter action tags, so the schema carries the load. The description adds only two semantic nuggets (description derivation from location, undo via manage_history); 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+resource ('Manage the active scene and its narrative framing') and enumerates the six action areas (set state, directive, presence, autonomy, choices, oracle). It clearly separates itself from manage_story and manage_history, though the multi-action umbrella means the individual actions are only briefly glossed.

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?

Contains explicit 'Use when:' and 'Do NOT use when:' clauses, naming manage_story (action: record) as the alternative for story beats, plus the undo path via manage_history. An agent can route without inferring anything.

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 flag the tool globally as destructive/non-idempotent, which is conservative for a multi-action tool; the description adds real value by partitioning the actions into mutating ('category reassignment, event append, and audit compaction mutate Novel-scoped state and persist') versus read-only ('recap/verbosity/briefing_order/health/discover/history'). It also calls out that compaction is irreversible and that supersede marks the replaced ordinal. 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?

Given eleven actions, the description is compact and front-loaded, moving from a one-line purpose to the mutation summary to 'Use when:' and 'Do NOT use when:'. The action-to-intent parentheticals keep it scannable. It is dense but each clause earns its place for a tool of this breadth.

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 return values need no explanation, and the description covers usage, mutation semantics, irreversibility, and the sibling exclusion. The remaining gap is minimal: no guidance on permission requirements beyond the schema's GM-only note, but 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 description coverage is 100%, so the schema already documents all 16 parameters with per-action hints. The description maps some actions to their parameters but adds no syntax, format, or constraint detail beyond what the schema provides. Baseline 3 is appropriate when the schema carries the load.

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

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

The description names the resource (session-level surfaces, diagnostics, tool discovery) and enumerates the concrete actions it fronts (recap, verbosity, briefing_order, compress, compact, health, discover, category, event, history). It also distinguishes itself from a sibling by name (manage_story for recording story content). The verb 'Manage' is broad and the scope is sprawling, which keeps it out of 5 territory, but the action enumeration makes the purpose unambiguous.

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

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

It provides an explicit 'Use when:' mapping each action to its intent (recapping activity, setting verbosity, reordering briefing sections, summarizing/compacting the audit log, health, discovery, category reassignment, event/history) and an explicit 'Do NOT use when:' clause naming the alternative (manage_story, action: record). This is textbook when/when-not/alternative 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 declare destructiveHint=true and readOnlyHint=false; the description reinforces this by separating mutating actions ('persist to the Novel and are audited') from read-only ones, and discloses the revert path via manage_history undo. It stops short of saying what remove actually destroys or whether edits are recoverable beyond the last mutation, so it adds context but leaves a gap.

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

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

Front-loaded with purpose, then behavior, then usage rules — a sensible ordering with no filler. It is dense (six stacked clauses) but every clause carries actionable information; only the audit/persist detail is slightly incidental.

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, return values need not be described, and annotations carry the safety profile. The description covers domain, mutation risk, undo routing, and the promote/key interaction; the only unaddressed area is pagination behavior for list, which the schema covers at the parameter level.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds real semantics the schema does not: 'promote uses index and writes lore under key (default derived)', clarifying cross-parameter interaction and the default. Other params (filter, limit, offset, entry) are left to 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 ('Manage the story journal') and immediately qualifies the resource as typed narrative memories with the five enum types, so the agent knows exactly what domain this covers. It also names the sibling it is not (manage_lore) and the adjacent history tool, making it distinguishable from the ~30 sibling manage_* 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?

Explicit when-to-use ('recording, editing, removing, listing, or promoting story beats') and explicit when-not with the correct alternative ('recording a durable world fact — use manage_lore (action: set)'). It also routes the undo path to manage_history, which is a genuine alternative-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 destructiveHint=true and readOnlyHint=false, but the description adds real context beyond them: mutating actions persist to the Novel and are audited, read-only actions leave state untouched, and omitting key on activate/deactivate acts on the whole module. It stops short of mapping each action to its individual destructive/read-only nature, which would be the full picture.

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

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

Front-loaded with purpose, then a compact behavioral clause, then explicit when/when-not guidance. Every sentence carries routing or behavioral information; the parenthetical content-type list is the only mildly expendable element.

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, return values need no explanation. The description covers persistence, audit trail, whole-module semantics, revert path, and sibling exclusions — everything needed to invoke a 10-action, 9-parameter 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 coverage is 100%, so baseline is 3, but the description adds a genuinely non-obvious semantic: activate/deactivate with key omitted operate on the whole module. It also points to manage_history (action: undo) as the revert mechanism, adding meaning beyond the enum listing.

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 (manage) and resource (synthesis content), then enumerates the concrete content types it covers (voice examples, lore templates, action patterns, Ruleset Wisdom). It explicitly routes non-matching cases to siblings (manage_codex, manage_history), so an agent can distinguish it without opening a schema.

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

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

Explicit 'Use when:' list of actions and a 'Do NOT use when: browsing the codex — use manage_codex (action: list)' exclusion. It also names manage_history (action: undo) as the revert path, giving both positive and negative routing.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is partly known. The description adds genuinely new context: mutating actions persist to the Novel and are audited, read-only actions do not mutate state, and the most recent mutation is reversible via manage_history. It stops short of noting irreversibility limits or auth requirements, so a 4 rather than 5.

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

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

Dense but front-loaded: purpose first, then mutation semantics, then undo path, then when/when-not. Every sentence carries operational value, though the compound final clauses are slightly packed and could be split for readability.

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 exists and annotations plus 100% schema coverage are present, the description only needs to supply routing, mutation semantics, and the undo path — all of which it does. Nothing an agent needs to select or 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: 'difficulty' drives the rank track and the linked countdown's ticks, and 'scope' defaults to shared when omitted. That default-value and cross-field linkage information 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 ('Track narrative vows, quests, and obligations with milestones') and enumerates the supported operations. It clearly differentiates itself from siblings by naming manage_countdown and manage_history as the tools for adjacent concerns, so an agent can route 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?

Provides explicit 'Use when:' triggers (setting, advancing, resolving, forsaking, listing) and an explicit 'Do NOT use when:' exclusion that names the alternative tool and action ('use manage_countdown (action: set)'). It also routes the undo case to manage_history with the precise action, leaving nothing to inference.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), it discloses that mutating actions persist to the Novel and are audited while read-only actions do not mutate state, and it names the exact undo route. That is meaningful behavioral context the 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?

Reasonably sized for a 10-action, 30-parameter tool, with purpose and persistence semantics front-loaded. Some clauses are dense run-ons ('create_thing honors location_type only when location is set; kind forces property defaults'), but every sentence carries information.

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

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

An output schema exists so return values need no explanation, and the description covers mutation semantics, undo, and routing. It stops short of clarifying the convert/generate actions, which are the least self-explanatory members of the action enum.

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 real meaning on top by stating that create_thing honors location_type only when location is set and that kind forces property defaults. It does not explain the convert/generate semantics or the mutual exclusion of room_a/room_b/from/to pairs.

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?

Names the specific resource ('the world model — rooms, things, and exits') and the operations (create, update, remove, bulk-convert). It explicitly contrasts itself with run_command for navigation, so an agent can separate it from siblings 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?

Contains an explicit 'Use when' clause (creating, updating, removing, bulk-converting locations and objects) and a 'Do NOT use when' clause routing navigation to run_command (execute/resolve). It also names the recovery path (manage_history action: undo).

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 (destructiveHint=true, idempotent=false) by disclosing that rolls and state writes persist to the Novel, that a roll with no following write is flagged as uncommitted, that stress without track or consequence clears everything, and that operations are not individually reversible. This is exactly the irreversibility/persistence context a mutating tool needs.

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

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

Front-loaded with the core capability and then the when/when-not routing; every sentence carries behavioral or routing information. It is dense and runs long, but there is little waste.

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 14-parameter mutating tool with an output schema present and full schema coverage, the description supplies the missing behavioral context (persistence, irreversibility, uncommitted-roll flagging) that the structured fields cannot convey. Nothing needed to invoke it correctly is absent.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds semantic grouping beyond the schema by tying the op sub-operations to action types and explaining the stress clearing rule (track/consequence omission). It doesn't detail every parameter's format, so a 4 is fair.

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 domain (resolve Fate-style actions with Fudge dice, aspects, Fate points, stress) and enumerates the sub-operations, which cleanly distinguishes it from siblings resolve_ironsworn and resolve_forged. An agent knows exactly which ruleset surface this tool covers.

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 'Use when' list covers rolling 4dF, invoking/compelling aspects, spending/refreshing Fate points, marking stress and consequences. The 'Do NOT use when' clause names the alternative (bound ruleset's roll tools or run_command with action: resolve) for d20 checks, giving a concrete routing decision.

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

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

Annotations already flag destructiveHint=true and non-idempotency, but the description adds substantial context the annotations cannot carry: rolls and state changes persist to the Novel, a roll with no following write is flagged as uncommitted, and rolls/state writes are not individually reversible. It also clarifies the odd dice-0 case and what the stress name label applies to.

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 paragraph is front-loaded with purpose, then behavior, then usage guidance, with no filler sentences. It is dense but every clause carries information; only minor tightening is possible.

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, return values need not be described, and the description still covers persistence, the uncommitted-roll flag, reversibility, and routing to alternatives. For a 10-parameter, destructive, stateful tool this is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the baseline would be 3, but the description adds meaning beyond the schema: 'action_roll with dice 0 rolls the lower of two d6' and 'stress name labels the resist consequence or the trauma mark.' These clarify ambiguous parameters (dice, name) that the schema documents only generically.

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

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

The description names a specific verb (resolve) and resource (Blades in the Dark-style actions) and enumerates the three action families: action rolls with position/effect, stress/trauma with resistance, and downtime recovery. This distinguishes it cleanly from siblings like resolve_fate and resolve_ironsworn 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 provides explicit 'Use when:' conditions (rolling an action against the highest die, marking/resisting stress, recovering during downtime) and an explicit 'Do NOT use when:' routing the agent to manage_countdown for progress clocks. Both the trigger and the exclusion name the alternative, leaving nothing to inference.

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

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

Annotations already declare destructive/non-idempotent, and the description goes further: state changes persist to the Novel, a roll with no following write is flagged as uncommitted, rolls and their writes are not individually reversible, and burn semantics (replaces action die with momentum, ignores adds). That is meaningful behavioral context beyond the structured 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?

Dense but front-loaded: the core purpose leads, then mechanics, then routing. Every sentence carries information, though the mechanics/constraints run together in a way that makes it slightly heavy to parse.

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

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

For a multi-mode tool with 10 parameters, 100% schema coverage, and an output schema, the description supplies what the schema cannot: persistence, irreversibility, uncommitted-roll flagging, and sibling routing. An agent can select and invoke it correctly without further information.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds semantics the schema does not carry: burn 'ignores adds' and progress rank 'defaults to dangerous'. It does not document the op sub-operations (momentum set/gain/lose/reset/list, progress create/mark/test/list), which remain schema-only.

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 (resolve) plus the concrete resources involved: momentum, the action-roll move framework, and progress tracks. It is clearly distinguishable from sibling resolvers like resolve_fate and resolve_forged, and from the manage_* state tools.

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

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

Explicitly gives a 'Use when' list (setting/burning momentum, rolling a move against two challenge dice, marking and testing a progress track) and a 'Do NOT use when' case that routes to the named alternative manage_vow (action: set). Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description earns credit for going beyond that by disclosing the atomic drain-and-persist mechanism, which explains why the operation is one-shot and non-repeatable, and the schema notes that 'cancel' aborts and restores a snapshot.

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

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

Two tight sentences, front-loaded with the core action and mechanism, followed by a compact 'Use when / Do NOT use when' structure. Every clause carries actionable information and there is no filler.

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

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

An output schema exists, so return values need not be described. Given the tool's mutation semantics, the annotations cover reversibility, and the description covers the trigger, the exclusivity condition, and the persistence side effect — everything needed to call it correctly.

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

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

Schema description coverage is 100%, and the schema itself documents both parameters, including the special 'cancel' value with its restore-snapshot behavior. The description adds no additional syntax, format, or constraint detail beyond what the schema provides, 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 (answer/respond) and resource (pending workflow decision) plus the mechanism: 'atomically draining it and persisting the outcome to the Novel.' The second sentence names the sibling tools (set_badge, state tools) that should be used in the alternative case, so an agent can distinguish 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?

Explicitly gives the trigger condition ('the server emitted a [NEED_INPUT] prompt and the caller must choose') and the negative condition ('no decision is pending'), and routes to named alternatives. Nothing about when to call versus not call is left to inference.

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

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

Annotations only say the tool is destructive/non-read-only, which is true for execute but misleading for resolve and suggest. The description corrects that by stating execute mutates world/entity state while resolve and suggest are read-only, and adds the key behavioral fact that execute persists to the Novel and is undoable via manage_history (action: undo). That is exactly the 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 routing clauses are front-loaded and well ordered, but the second sentence is largely redundant: 'resolve and suggest are read-only' is stated twice in adjacent clauses. That repetition costs a point on an otherwise compact definition.

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 tri-mode tool with four params and an output schema, the description covers the decision-relevant facts: what each mode does, which mutate, reversibility and the undo path, and which sibling to use instead for direct inspection. Return values are correctly left to 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%, so the baseline is 3, but the description goes further by tying each action to its parameter (execute consumes a command, resolve/suggest consume intent, entity_id is suggest-scoped). It stops short of documenting formats or the execute default, which 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 names a specific verb (execute/resolve/suggest) and the resources involved (parser command, spatial intent, world/entity state), and explicitly routes away from manage_world/manage_lore. The only friction is the multi-mode nature and the jargon 'parser command', which forces the reader to reconcile the tool name run_command with three distinct behaviors.

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

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

It gives an explicit 'Use when' clause for each of the three modes (physical action → execute, movement outcome without mutation → resolve, intent mapped to tool calls → suggest) and an explicit 'Do NOT use when' clause naming manage_world and manage_lore as alternatives. This is about as complete as routing guidance gets.

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

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

Annotations already declare the safety profile (readOnly false, destructive true, idempotent false), so the bar is lower. The description still adds real context beyond them: the badge gates tool access server-side for the session, and the tool is always callable — useful for reasoning about access loss. It stops short of saying explicitly that switching away can revoke currently available tools mid-task, which is the destructive consequence an agent should weigh.

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

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

Three tightly packed clauses: what it does, when to use, when not to use. Front-loaded with the action and scope, no filler sentences, every clause earns its place.

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

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

An output schema exists, so return values need not be explained. For a single-enum-parameter state-switching tool with full annotation coverage, the description supplies everything needed to select and call it correctly.

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

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

Schema description coverage is 100% and the enum is fully documented in the schema, so the description adds nothing new when it lists the same four values. Baseline 3 applies when the schema carries the parameter semantics.

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 (switch the active badge), enumerates the four allowed values, and names the concrete effect: server-side gating of tool access for the session. An agent can distinguish this from every manage_* sibling 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?

Gives explicit 'Use when' triggers (entering the story, spectating, stepping away to edit) and an explicit 'Do NOT use when' case that names the correct alternative (respond_decision for a pending workflow decision). Routing is unambiguous.

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