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

Annotations only declare destructiveHint=true / readOnlyHint=false / idempotent=false; the description goes further, clarifying that close seals but does not archive or export the Novel, that recap and context persist and are audited, and giving an explicit undo path via manage_history (action: undo). That is exactly the extra behavioral context annotations cannot convey.

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

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

Front-loaded with what the tool does, followed by effect boundaries, then structured Use when / Do NOT use when clauses. Every sentence carries distinct information with no 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?

Covers side effects, persistence semantics, reversibility, and sibling routing, which is everything an agent needs for a zero-parameter mutation; the existing output schema handles return-shape concerns.

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

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

The tool takes zero parameters, so there is nothing parameter-level to document; baseline 4 applies. The only parameter-like reference is the sibling call manage_history (action: undo), which is clearly specified.

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

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

Specific verb (close) plus resource (play session) and both effects (returning a recap, saving context). It explicitly distinguishes itself from open_session for resumption and manage_archive for archiving/exporting.

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' (ending a session, checkpointing narrative context) and 'Do NOT use when' (archiving/exporting a Novel — use manage_archive) clauses, plus names open_session as the resume path. Alternatives and exclusions are stated outright.

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 the tool as non-read-only and destructive, but the description adds important context beyond them: generate writes scaffolds into a target store, generate_encounter writes one encounter, writes persist and appear in the audit log, and the most recent write is undoable via manage_history. It also clarifies that load and list are read-only, which materially distinguishes action behavior.

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

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

The definition is dense but front-loaded: it starts with the action modes, then side effects, then usage boundaries. Most sentences earn their place, though the parenthetical about the guard and the phrase 'both persist to the Novel' make some parts tighter and less immediately clear than they could be.

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 four-action tool with six parameters, the description explains the main action modes, write side effects, audit/undo behavior, and when to use an alternative. Output values need not be explained because an output schema exists, but the target/codex/both semantics are slightly muddied by the statement that 'both persist to the Novel'.

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 action-level meaning: target defaults to novel, a !force prefix bypasses the guard, list accepts an optional genre filter, and slug is for load. It does not fully restate premise/context semantics, but those are covered by the schema.

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

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

The description states specific verbs and resources: generate, load, and list adventure content, with generate_encounter explicitly called out as a distinct action. It also distinguishes the tool from manage_story for recording story beats, 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 explicit positive usage guidance ('Use when: the GM wants...') and an explicit exclusion ('Do NOT use when: recording a story beat — use manage_story'). This is exactly the when/when-not/alternative structure that helps tool selection.

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

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

Annotations already declare destructive and non-idempotent behavior, but the description adds that mutating actions persist to the Novel and are audited, that terminal tasks are immutable, and that list/get are read-only. It also gives the revert path via manage_history. It stops short of detailing permissions or the exact effects of cancel/fail on stored data, so 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; every clause carries routing, lifecycle, or persistence information with no filler. It could be split for readability, but nothing is wasted.

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

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

With an output schema present, return values need not be explained. For a complex 8-action mutation tool, the description covers lifecycle, defaults, persistence, audit, usage, and alternatives completely enough to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter's associated action. The description adds a useful 'advance appends description' semantic and reiterates the autonomy default, but most of its create/source_goal mapping duplicates schema parentheticals.

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 a specific verb (manage) and resource (durable NPC/agent tasks) and scopes it to the action lifecycle, making it clearly distinct from siblings like manage_npc and manage_scene. An agent can identify the tool's domain 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 'Use when' and 'Do NOT use when' clauses with named alternatives and action paths (manage_scene action: oracle, manage_npc, manage_history undo). This is exactly the routing guidance needed to choose this tool over its siblings.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds real substance: export writes a file, import writes Novel state, 'replace' discards current Novel state, strict aborts on unresolved references, archive is reversible via unarchive, and checkpoint_restore is undoable. It stops short of stating permission/auth requirements or what validate-only dry-run returns.

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 is front-loaded with operation semantics first, then the Use/Do-NOT-Use routing, and every clause carries new information. The middle sentence is long and packs four mode behaviors plus strict into one run-on, which costs some scannability.

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 10-action, 13-parameter tool with an output schema and safety annotations, the description covers the risky paths (import modes, replace, checkpoint_restore) and the sibling routing well. Gaps are minor: clone/branch semantics (what actually gets copied, how trim_audit_sessions interacts with a full copy) and export scope/format options live only in the 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; the description earns above that by explaining the semantics of 'mode' beyond the enum labels (dry-run = validate only, merge = keep existing entries, replace = discard current state) and by clarifying what 'strict' aborts on. Clone/branch parameters such as trim_audit_sessions and from_event are left entirely 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?

The description enumerates the concrete operations (export, import, archive/unarchive, clone/branch, checkpoint_*) it covers on Novel state, and explicitly separates itself from manage_novel. The opening verb 'Manage ... surfaces' is an umbrella phrase, but the following clauses supply the specific verbs the name alone would obscure.

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' list (export/import, archive/unarchive, cloning/branching, checkpoints) and a 'Do NOT use when' clause routing Novel CRUD to manage_novel. It also names two further alternatives with their roles: manage_history (action: undo) for reverting mutations and checkpoint_list as the read-only counterpart.

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

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

Goes well beyond the annotations by disclosing the evidence-then-reconcile dependency (admit does not change a stance until reconcile runs), that retract removes evidence and reconciles, that the perception ledger is append-only so corrections require a new record, and that mutations persist to the Novel while reads are read-only. No contradiction with destructiveHint=true / readOnlyHint=false.

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 resource scope, then behavioral rules, then use/don't-use routing — a logical order. Dense but nearly every clause carries information; the opening sentence is a slightly long noun pile-up that could be trimmed.

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 12 actions and 23 parameters, the description covers the mutating flow, the append-only constraint, persistence, and alternative tools, and an output schema exists so return values need not be described. Missing only a mapping of which parameters belong to which of the less-mentioned actions (list/get/conflicts), which the schema partially supplies.

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

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

Schema coverage is 100% with per-parameter descriptions bound to specific actions, so the schema carries the parameter burden. The description adds a little semantic context (weight being a 0..1 support value, the reconcile gating) but does not explain the 23 parameters or which are required per action, so baseline 3 applies.

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

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

The description names the resources clearly — evidence, reconciled belief stances, perception ledger, and knowledge query — and enumerates the key verbs (admit, retract, reconcile, knowledge_query). It omits the read verbs (list, get, evidence, conflicts, perception_list) that appear in the schema enum, so an agent must open the schema to see the full action set.

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

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

Explicit 'Use when: inspecting or recording what an entity learned or believes' plus a 'Do NOT use when' clause that routes to manage_causality for objective truth and manage_lore for shared lore. This is exactly the sibling-disambiguation an agent needs for a crowded toolset.

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 important context: proposals persist and are audited, causal_propose records without applying, causal_admit applies, causal_reject discards, and list/state are read-only. It stops short of describing audit retention or rejection consequences in depth, but the key behavioral traits are disclosed.

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

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

The description is dense but front-loaded: purpose, action semantics, usage conditions, exclusions, and revert path all appear in sequence. It is slightly run-on with multiple clauses packed into single sentences, but every sentence carries actionable 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?

Given 11 parameters, an output schema, and annotations covering safety, the description fills the remaining gaps: action semantics, proposal lifecycle, optimistic concurrency, read-only operations, sibling exclusions, and revert guidance. An agent has enough to select and 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 coverage is 100%, so the baseline is 3, but the description adds role-level meaning beyond field descriptions: causal_expected_version guards optimistic concurrency, causal_from records the expected prior value, and causal_ingress admits an external event without a proposal. This helps an agent understand how parameters relate to the action workflow.

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 objective causal state and transition proposals') and then enumerates every action and its effect. An agent can distinguish this tool from manage_world and manage_history without consulting 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 explicitly names when to use ('proposing, admitting, rejecting, listing, or inspecting causal transitions, or ingressing an external event') and when not to use ('changing rooms, things, or exits — use manage_world'), and it routes reverts to manage_history with the exact action. 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?

Goes well beyond the annotations: it identifies which actions are read-only (sheet, roster_list), states that mutations persist, are audited, and are undoable via manage_history (action: undo), explains that update shallow-merges stats and preserves omitted fields, and notes that stage and roster_remove are exact inverses. This is exactly the mutation/undo/reversibility context that destructiveHint=true alone does not convey.

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

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

Four sentences, front-loaded with the action inventory, then mutation/undo semantics, then alias precedence, then when/when-not. Dense but no filler; the aliasing sentence is packed tightly and could be slightly more scannable given 27 params.

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 12-action, 27-param tool with an output schema (so return shapes needn't be explained), the description covers persistence, audit, undo, roster inverses, aliasing, and sibling exclusion. It does not clarify the distinction between stage and set_active, or what import expects from roster_id — minor residual gaps.

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

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

Schema coverage is 100%, so baseline is 3; the description earns extra credit by explaining the personality{} and details{} alias groups and the precedence rule (top-level value overrides the grouped alias) plus stats shallow-merge behavior, none of which the schema states. Several params (seed, stat_method, format, pov, examples) are left entirely to the schema, so it stops short of a 5.

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

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

Names a specific resource (player characters) and enumerates the concrete operations: create, stage, import, render sheet, set active, personality/voice, patch stats, signal, remove, roster_list. It also explicitly distinguishes itself from 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?

Contains an explicit 'Use when:' list (creating/importing a PC, staging or activating one, editing sheet or voice, handling player feedback) and an explicit 'Do NOT use when:' with the named alternative manage_npc. Both selection conditions are stated, not inferred.

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

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

Annotations cover the mutation/destructive profile, and the description adds substantial context beyond them: persistence to .holonovel-state/codex.json, audit of mutations, the Editor/Game Master badge requirement, the [FORBIDDEN] outcome for an in-play Player, and the fact that reads are not badge-filtered. It also clarifies the default-store behavior when no Novel is active and the merge=true shallow-merge semantics.

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

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

The description is dense but front-loads the resource and scope before the badge/behavioral details and the use/don't-use routing. Every sentence carries load for a 12-parameter, multi-action tool; it is longer than ideal but not padded.

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

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

Given the tool's complexity, an output schema is present (so return values need not be described), and the description supplies the missing scope, auth, persistence, and action-specific preconditions an agent needs to call it correctly. Nothing material is left out.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value the schema lacks: that `set` requires `kind` + `name` and the id derives from them, plus how merge=true shallow-merges content. It does not attempt to explain the remaining 12 parameters, but the schema already documents those adequately.

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 the exact resource (the server-level codex library of reusable, cross-Novel content) and enumerates the entry kinds it holds. It explicitly distinguishes itself from siblings by naming manage_lore and manage_note as the tools 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 'Use when' (storing reusable content for later import, or enumerating/reading/deleting it) and 'Do NOT use when' (Novel-scoped content — use manage_lore or manage_note). It also preconditions import/capture on an active Novel and routes undo to manage_history.

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

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

Beyond annotations (destructive=true, non-idempotent), it discloses that mutating actions persist and are audited, that read-only actions do not mutate state, that the last mutation can be reverted with manage_history undo, and the subtle seed rule (seed only reorders the danger set; participants keep their given order). That is exactly the behavioral context a destructive-but-revertible 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?

Four tightly packed sentences, front-loaded with purpose and scope, then mutation/audit semantics, then seed nuance, then explicit use/do-not-use directives. No filler and no repetition of the enum list already in the schema.

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

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

For a 6-parameter mutation tool with an output schema, the description supplies everything the schema cannot: scope, mutation/audit behavior, undo path, a non-obvious seed semantic, and a sibling routing rule. Nothing an agent needs before calling it appears 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 adds semantics the schema cannot: the deterministic seed's actual effect on ordering and the fact that participants retain their supplied order on init. It doesn't touch outcome/dangers, but those are adequately documented inline.

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 ("Manage combat encounters in the active Novel") and immediately bounds the scope as encounter-level turn order, participants, and lifecycle "not per-entity conditions." This scope boundary lets an agent separate it from manage_condition 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, ending a fight, or changing its participants" and "Do NOT use when: applying a status effect — use manage_condition (action: apply)." It also names the recovery path via manage_history (action: undo), so both the trigger and the alternatives are covered.

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

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

Beyond the annotations, the description discloses important behavior: re-applying an active condition warns instead of duplicating it, remove deletes the condition and its round counter, apply/remove require GM or Editor badge, changes persist to the Novel, and they are undoable via manage_history. It also clarifies that list is read-only. These details are consistent with the destructive mutation annotations.

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

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

The description is compact and front-loaded: it starts with the tool's purpose, then operation details, permissions, persistence, undo behavior, and finally explicit use/exclusion guidance. Every sentence contributes information needed to select and invoke the tool correctly.

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 mutable condition-management tool with an output schema and annotations already present, the description covers the critical operational context: permissions, persistence, undo path, re-application warning, round-expiry behavior, read-only listing, and the main sibling alternative. Nothing essential for correct invocation appears to be missing.

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

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

Schema description coverage is 100%, so the schema already defines the four parameters at a baseline level. The description meaningfully supplements that by explaining that rounds is a positive round count and that omitting it or passing 0 leaves the condition without expiry, which is behavioral semantics not fully captured by the schema.

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

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

The description states a specific verb and resource ('Manage mechanical or narrative conditions on entities') and enumerates the supported operations: apply, remove, and list. It also distinguishes the tool from manage_combat, which handles damage or combat state, so an agent can identify its scope 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 explicit when-to-use guidance ('Use when: applying, removing, or listing conditions') and an explicit exclusion with an alternative ('Do NOT use when: recording damage or combat state — use manage_combat'). This directly routes the agent between sibling tools.

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

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

The annotations only say destructiveHint=true and readOnlyHint=false for the whole tool, so the description adds real value by partitioning the nine actions: list, get, access, and acquisitions are read-only while the rest persist state and are audited. It also discloses the conflict rule ('latest decision winning') and points to undo. It stops short of saying what a deny or unregister actually removes or whether access decisions are reversible outside 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?

The opening purpose line is front-loaded and the use-when / do-not-use-when structure is easy to scan. The middle action-gloss sentence is dense but each clause carries distinct information; no filler or restated title.

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

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

For a 13-parameter, nine-action tool with full schema coverage, annotations, and an output schema, the description supplies the action semantics, the mutating/read-only split, and the sibling routing an agent needs. The remaining gap is the access-model detail (how per-entity grants, domains, and access_public combine), which the description only gestures at.

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, and the description genuinely adds meaning beyond the enum names: 'route derives its domain from a trusted source profile', 'consume records a read', 'access checks an entity against the recorded grants'. That clarifies the intent of corpus_route and corpus_access, which the schema only labels. It does not explain the grants/denies vs access_domains vs access_public interplay explicitly.

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 resource ('cold-reference knowledge corpus') and then enumerates what each of the nine actions does, so an agent can tell corpus operations apart from other 'manage_*' siblings without opening the schema. It explicitly contrasts itself with manage_lore for Novel lore/secrets, which pins down the boundary.

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 an explicit 'Use when:' list covering all intended actions, an explicit 'Do NOT use when:' routing to manage_lore, and a third pointer to manage_history (action: undo) for reversals. Both the positive cases and the exclusion are stated, 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 at tool level, so the bar is lower; the description adds valuable per-action nuance that annotations cannot — 'Mutating actions persist to the Novel and are audited; list is read-only' — and clarifies that advance fires world_effect and on_scene_transition auto-advances. It stops short of describing what 'remove' discards or any auth/permission requirements, 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-loads the core purpose, then uses labeled 'Use when / Do NOT use / Revert' segments that scan well. The middle behavioral clause is densely packed but every sentence carries distinct information, so 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?

For a 10-parameter tool with a nested world_effect object and an output schema (so return values needn't be explained), the description covers actions, per-action mutations, dependency rules, and routing to alternatives. It is essentially complete, with only the destructive 'remove' semantics left unstated.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter semantics the schema lacks: 'intention' advances on scene transition, and 'direction shifts NPC dispositions only when scope is also set' — a real dependency rule. The set/advance/remove action-per-parameter mapping (name, ticks, total) is also clarified.

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 then enumerates every action (set/advance/remove/list) with its distinct behavior, so an agent knows exactly what the tool does and how each action differs. It also explicitly names the sibling it is not (manage_vow).

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?

Uses explicit 'Use when: starting, advancing, removing, or listing clocks' and 'Do NOT use when: tracking a vow's progress — use manage_vow (action: milestone)', plus a revert path via manage_history (action: undo). Alternatives and exclusions are both spelled out, nothing 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 flag the whole tool as destructive and non-idempotent, which alone would be alarming and uninformative; the description disambiguates per action — compact's pruning is 'irreversible' and GM-only, verify and replay are read-only, visibility_check writes to the audit log while visibility_audit does not, and health/subscribe/category do not change Novel content. It also discloses the authorization constraint (GM-only) that no annotation carries.

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 per-action semantics, then the use/don't-use routing — the right order for a dispatcher tool. The per-action clauses are chained into long run-on sentences ('...and both are read-only; ...while visibility_audit reads...'), which costs some scannability, but for a 12-action tool the length is earned rather than padded.

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

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

Output schema and rich annotations are present, so return values need no explanation. The description covers 11 of the 12 actions with at least a behavioral note — `context_report` is the one action never described, and it is also one of the more obscure ones. Otherwise an agent has enough to call any of these actions safely.

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

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

With 100% schema description coverage across 22 parameters, the schema already documents each field's meaning and the action it belongs to, so the baseline is 3. The description adds marginal value by tying actions to behaviors (e.g. compact retaining `sessions`, verify comparing hashes), but it gives no syntax, defaults, or interaction detail beyond what the schema states.

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

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

The description opens with a specific framing — 'session diagnostics and maintenance surfaces separate from play-facing session controls' — and then enumerates what nearly every action does (compress summarizes, compact prunes, verify compares hashes, replay reads, visibility_check records, visibility_audit reads). It also names the sibling it is not (manage_session), so an agent can route without opening the schema. The only slight weakness is that a 12-action grab-bag (health, subscribe, category reassignment, visibility audit) doesn't map cleanly onto a single 'diagnostics' noun, so the boundary is a little fuzzy.

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 structured as 'Use when:' with a full enumeration of triggering tasks, plus a 'Do NOT use when:' clause that names recapping, setting verbosity, and reordering the briefing and redirects to manage_session. This is exactly the when/when-not/alternative pattern that lets an agent choose correctly without 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?

Goes well beyond annotations: states the GM/Editor badge requirement, that changes persist to the Novel, that they're undoable via manage_history (action: undo), that remove is permanent unless undone, that list is read-only, and that the progress clock is Novel-internal and not settable. Annotations confirm destructiveHint=true and this adds the recovery path.

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 operation set, then permissions/undo behavior, then usage routing. Dense but nearly every clause carries information; the only mild waste is restating 'create, update, remove, or list' inside the 'Use when' clause.

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?

Multi-action mutation tool with an output schema and rich annotations, yet the description still covers authorization, persistence, undo, and destructive semantics. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds action-parameter pairing ('name is required to create', 'faction_id targets an existing faction') and an explicit exclusion (progress clock not set directly) that the per-field schema strings do not convey.

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

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

States specific verbs (create, update, remove, list) against a specific resource (factions in the active Novel) and enumerates the fields carried. An agent can distinguish it from manage_world/manage_novel based on the description alone.

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' clause enumerates the four triggering actions, and a 'Do NOT use when' clause names the alternative (manage_world action: create_room) for territory-room tracking. Both positive and negative routing are 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 declare readOnlyHint=false, destructiveHint=true, and non-idempotence, so the safety profile is covered. The description earns credit for adding genuinely non-obvious behavior: immediate persistence, per-badge stack scope, a cap via TTRPG_MAX_SNAPSHOT_DEPTH, redo-stack clearing on a new mutation, and blocking by a pending workflow decision. It does not, however, describe what a restored snapshot affects or what the response reports.

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 action and scope, then behavior, then use/do-not-use routing — a sensible order with no filler. The opening sentence is long and packs several constraints together, which costs a little readability but nothing is redundant.

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 are covered, and annotations cover the mutation safety profile. The description supplies the remaining gaps an agent needs (stack scope, depth cap, decision blocking, alternative for older changes) for a two-direction, destructive undo tool.

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

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

Schema coverage is 100% and the single enum parameter's description already defines both values and the undo default. The description adds the conceptual constraint that only the most recent mutation is in play, which sharpens interpretation of the 'undo' value but does not add syntax or format detail beyond the schema.

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

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

States a specific verb pair (undo/redo) plus the exact resource scope: the most recent state mutation for the active badge. The scope ('most recent', 'per-badge') is what distinguishes it from sibling tools like manage_story that also mutate Novel state.

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' (reverting the last mutation, restoring an undone one) and 'Do NOT use when' (an older change is the target), naming the correct alternative behavior: re-run the owning tool such as manage_story. It also names respond_decision as the unblocking prerequisite.

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: it discloses that accept retains the displaced value in internal history and bumps the identity version, that reject leaves accepted facets untouched, that revert restores the most recently displaced facet, that mutation persists the roster and is audited, and that list/snapshot are read-only despite the tool-level readOnlyHint=false. This resolves the annotation ambiguity for a destructive-flagged multi-action tool.

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

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

Front-loaded with the resource, then per-action semantics, then the use-when/do-not-use routing; nearly every clause supplies decision-relevant information. It is dense and somewhat run-on, but the only mild redundancy is restating the action list twice.

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 9 parameters, enums, a nested card object, and an output schema that covers return values, the description supplies exactly what the structured fields cannot: per-action behavior, side effects, audit persistence, and sibling routing. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by mapping parameters to actions (stage imports/authors, accept/reject use candidate_id, bootstrap seeds from a card) and by clarifying that accept's perspective defaults to the candidate's stored perspective rather than the schema's stated 'self' default. It does not explain the stability tiers (structural/core/developmental) or what a provenance source label is used for.

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

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

States a specific verb and resource — managing a roster character's durable identity (staged candidates, accepted facets, versioned kernel) — and enumerates every action in the enum. It also explicitly names the sibling tools it is not, so an agent can separate it from manage_belief and manage_character 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?

Has an explicit 'Use when' clause enumerating staging, accepting, rejecting, reverting, and reading, plus a 'Do NOT use when' clause that names the correct alternatives (manage_belief for knowledge/beliefs, manage_character with action: personality). 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 declare destructiveHint=true and readOnlyHint=false, which alone would make an agent wary; the description resolves that by explaining exactly what is replaced (the prior projection), what is not created (no persisted copy), and that the authoritative Novel file is never modified — so the 'destructive' act is a safe rebuild. It also segregates read actions as non-mutating, which the annotations' tool-level flags cannot express since they are a single set for eleven actions.

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, then behavioral guarantees, then positive and negative routing — a sensible order with no filler. The second sentence is long and compound ('audited, replace the prior projection in one step, and do not persist a separate copy'), which costs a little scannability.

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 eleven-action tool with a rich enum and an existing output schema, the description covers the things the schema cannot: which action families mutate, that rebuilds are safe and reversible from source, and where to go for the three neighboring intents. Return shapes 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% and each parameter already names its owning action (index_search, index_relations, graph_neighbors), so the schema carries the load. The description adds no format, default, or constraint detail beyond what is structured, which is the baseline-3 case.

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 — derived, in-memory knowledge over Novel sources — and immediately decomposes it into the two concrete artifacts it manages: a semantic index and a typed knowledge graph. The action families (index_*/graph_*) are named in prose, so an agent knows the tool's 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' list covers all four legitimate intents (build/rebuild, staleness check, ranking, relation/graph reads), and the 'Do NOT use when' block routes three distinct wrong turns to manage_ruleset, manage_corpus, and manage_relationship by name. 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?

Beyond the destructiveHint=true annotation, the description discloses the GM/Editor badge requirement for mutations, that mutations persist to the Novel, the undo path via manage_history (action: undo), that import defaults to a non-mutating dry-run while merge/replace write, and that game_master badge_scope hides entries from the Player badge. It also enumerates the read-only subset (list, get, export, secret_list, knowledge), which matters because the tool's aggregate annotation is destructive. Idempotency is unaddressed but the disclosure burden is otherwise well covered.

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 first, then action families, then behavior, then use/avoid routing — a sensible order for a 14-action mega-tool. It is dense but nearly every clause carries information; the only mild redundancy is restating the read-only action list after already naming them in the action walkthrough.

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, multi-mode tool with an output schema and destructive annotation, the description covers scope, permissions, dry-run defaults, and undo. Gaps are minor: idempotency of set vs. update, and what happens when import merge collides with an existing key.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: badge_scope's game_master value hides the entry from the Player badge (a visibility rule not present in the enum description), and it names the recall triggers/priority/sticky weight fields as write-time concepts. It doesn't explain how triggers actually fire or what sticky weight governs.

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

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

The opening sentence names a specific verb and resource ("Manage the active Novel's lore entries — shared, durable world facts") and immediately enumerates the action families it covers. It explicitly names the siblings it is not (manage_belief, manage_corpus), so an agent can separate it from adjacent tools without opening either schema.

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

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

The description provides an explicit "Use when:" list and an explicit "Do NOT use when:" clause that routes to named alternatives (manage_belief for entity beliefs, manage_corpus for cold-reference documents). The condition that selects each alternative is stated, not inferred.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false; the description adds real context on top: mutations persist to the Novel, are audited, 'set replaces the note content', and badge_scope governs which badge can read the note. It stops short of explaining the remove/remove_server destructive paths, which is the main gap given destructiveHint=true.

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 resource and scope, then action semantics, then use/don't-use rules. Dense but every sentence carries information; the middle sentence is somewhat packed with several action behaviors at once.

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 and annotations covering safety, the description only needs to carry usage, scoping, and mutation semantics, which it does. The remove and list actions of a six-action tool are never mentioned, leaving a small completeness gap.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds genuine semantics beyond the schema: badge_scope defaults to game_master and controls read access, set_server takes an optional narrative_tag, and list_server returns summaries unless detail is set. Only remove/list action behavior is 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?

Names a concrete resource ('Novel-scoped scratch notes') plus its scoping dimension (badge-scoped to game_master/player/shared), so the agent knows exactly what this tool owns. It also distinguishes itself from manage_lore and manage_history, which is more than most siblings do.

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: storing scratch state the caller will reuse' and 'Do NOT use when: recording durable world facts — use manage_lore (action: set)', plus a revert path via manage_history (action: undo). Both the inclusion and exclusion conditions plus named alternatives are 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 readOnlyHint=false, and the description goes beyond them by stating which actions persist (create, save_context) versus read-only (list, info, get_context) and that lifecycle changes are not reversible via manage_history, with the mitigation of cloning first. The remaining gap is that it never clarifies whether the destructive enum actions (import, clone, checkpoint_restore) are actually callable here or hard-routed to manage_archive.

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 action scope, then behavior (read-only vs persisting), then a risk warning, then use/do-not-use. It is dense but every sentence carries routing or safety information. The opening enumeration of twelve action names partially duplicates the action enum, which is the main 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, and the description covers routing, mutation semantics, and irreversibility for a 27-parameter tool. However, with the action enum listing export/import/clone/branch/checkpoint actions that the prose delegates to manage_archive, an agent cannot fully resolve whether those are callable here — a meaningful ambiguity for a destructive tool.

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

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

Schema coverage is 100% and each of the 27 parameters is annotated with its owning action, so the schema carries most of the load. The description adds real meaning for `detail` ('list returns one line per Novel unless detail is set') and `filter` (active/archived/all), but says nothing about the remaining parameters beyond the action-level split. 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 names the resource (Novel save files) and enumerates the concrete actions (create, resume, switch, end, rename, info, save_context, get_context, list), so an agent can tell it handles campaign lifecycle rather than content. It explicitly separates itself from the entity tools and manage_archive. The only blur is that the schema's action enum still lists export/import/clone/branch/checkpoint_* actions the description tells the agent to route elsewhere.

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: handling a campaign's lifecycle or returning to saved context' and 'Do NOT use when: managing content inside the Novel — use the entity tools', plus a named alternative (manage_archive) for export/import/archive/clone/checkpoints. Both the positive trigger and the exclusion are stated, 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?

Goes well beyond the annotations: states that create requires a name, that ruleset_reference links a stat block without copying it, that mind is GM-only and never returned to the Player badge, that remove is permanent deletion, and that writes require GM/Editor badge, persist, are audited, and are undoable via manage_history. The destructiveHint=true annotation is corroborated rather than contradicted.

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 semicolon-delimited clauses with zero filler; purpose comes first, per-action semantics next, then when/when-not routing. Everything stated is decision-relevant for a 16-parameter tool.

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

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

Covers permissions, persistence, audit/undo, visibility, and destructive behavior for the core actions, and an output schema exists so return values need no explanation. Minor gaps: import_plan/import/export operations (card, source, license, detail) get no behavioral framing such as where card data lands or what confirm_lore does.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real value on top by explaining the semantics of name (required on create), ruleset_reference (reference, not copy), and mind (GM-only, hidden from players), which the schema only labels. It does not add meaning for import_card parameters like license/source or confirm_lore.

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+resource ("Manage non-player characters in the active Novel") and then enumerates the action surface (create/update/remove/list/get plus card import/export). It explicitly distinguishes itself from the nearest sibling, manage_relationship-style confusion avoided by calling out 'use manage_relationship' equivalent for NPCs.

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:" list and a "Do NOT use when:" exclusion that names the alternative (manage_character with its create/import/sheet actions). An agent can route between NPC and PC management without opening either schema.

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: discloses that set requires the GM or Editor badge, persists to the Novel, is undoable via manage_history (action: undo), and that get is read-only. It also explains the in-place (non-duplicating) update semantics, which reconciles with destructiveHint=true rather than contradicting it.

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

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

Dense and front-loaded, with the use/do-not-use routing at the end serving a clear purpose. Minor redundancy in restating the enum list that the schema already provides keeps it from a top score.

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 and full annotation coverage present, the description still covers permissions, persistence, undo path, and get's return shape. An agent has everything needed to invoke it correctly and unsafely-avoid mistakes.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds genuine meaning: the relationship key is the ordered (entity_a, entity_b) pair, value is an optional numeric strength, and get returns outgoing and incoming edges separately. It slightly repeats the enum values already in the schema, which keeps it from a 5.

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

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

States specific verbs (set/get) against a specific resource (directed relationships between entities/NPCs/factions) and explicitly differentiates from the sibling manage_faction. An agent can select this 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: setting or reading how two parties relate' and a 'Do NOT use when: tracking faction standing or progress — use manage_faction (action: update)', naming the alternative and its action. 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?

Beyond the annotations it discloses per-action safety: search is read-only and needs no active Novel; mutating actions are audited and reversible via the paired action; install of an existing slug conflicts; remove refuses while a Novel is bound; binding scopes only Novel-dependent features. These are exactly the behavioral traits annotations cannot express per-action, and they do not contradict the tool-level destructiveHint.

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?

Despite covering seven actions and fourteen params, it is tightly organized: purpose first, then per-action behavior and constraints, then Use-when/Do-not-use routing. Every sentence carries actionable information with no filler.

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

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

With an output schema handling return values and annotations covering the safety profile, the description fills the remaining gaps: per-action semantics, mutation/audit/reversibility, conflict and refusal conditions, and routing to siblings. An agent has everything needed to pick the right action 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 schema already documents each parameter and its target action, warranting a baseline 3. The description adds genuine value beyond that by noting that search accepts an optional slug (info not present in the schema's slug description), though it does not clarify the remaining install-specific params.

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 enumerates the concrete actions verb+resource (search, install, remove, list, bind, import/remove supplementary Wisdom) in one front-loaded sentence, so an agent can map the tool to its tasks precisely. It also distinguishes itself from resolve_mechanic (rolls) and manage_session (discovery).

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:' list and a 'Do NOT use when:' exclusion that names the alternative ('the ruleset name is unknown — use manage_session (action: discover)'). It further routes table rolls to resolve_mechanic, 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?

Adds substantial context beyond the annotations: set and directive require the GM or Editor badge, persist to the Novel, are audited, and are reversible via manage_history (action: undo). It also discloses that set overwrites existing description/metadata, which corroborates destructiveHint=true. It stops short of noting non-idempotency or the additive side effects of oracle rolls, so it is strong but not complete.

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 purpose leads, per-action semantics follow, then permissions, then explicit use/do-not-use routing. Every sentence carries distinct information, and the 'Use when' / 'Do NOT use when' scaffolding makes it scannable despite the length.

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 18-parameter destructive tool, it covers the four actions, the permission model, persistence/audit behavior, and undo path, and the output schema means return values need not be described. The gap is fast_forward and its nested changes/skip_countdowns semantics, which an agent must infer entirely from the 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 a genuine rule not in the schema: description is derived from location only when description is omitted. It also maps parameters to actions (directive replaces the active directive, choices replaces the offered options). The notable omission is fast_forward, a nested object controlling time skips and NPC changes, which is never explained.

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 a specific verb+resource ('Manage the active scene and its narrative framing') and enumerates the four sub-operations it covers: description, directive, choices, and oracle rolls. It explicitly separates the tool from the world model's 'rooms and things' and from the staging siblings, so an agent can discriminate it without opening the schema.

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

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

Provides an explicit 'Use when:' list (setting scene state, issuing a directive, offering choices, consulting the oracle) and a 'Do NOT use when:' list that routes to named alternatives — manage_story for recording a beat and manage_staging for presence/autonomy. This is exactly the when/when-not/alternative structure a routing agent needs.

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

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

Annotations already signal that the overall tool is mutating and destructive, and the description adds useful behavioral detail: GM-only gm_notes visibility, session-scoped verbosity, briefing_order persistence to the Novel, badge requirements, read-only recap/discover subactions, and the absence of an undo snapshot. It still does not reconcile the destructive 'compact' action that appears in the schema with the instruction to avoid audit compaction, leaving some per-action side effects unclear.

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 appropriately structured for a multi-action tool: it front-loads the purpose, then gives use and do-not-use routing. Some clauses are run-on and the long action list creates slight redundancy, but most sentences carry useful 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 complex tool with nine parameters and an output schema, the description covers the main play-facing actions and the most important exclusions, so it is minimally viable. However, it leaves several actions present in the schema, such as compress, context_report, subscribe, verify, replay, and the visibility actions, effectively unexplained, which creates a completeness gap.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters. The description adds meaningful semantics beyond the schema, especially that gm_notes are GM-only and never returned to a non-GM badge, that detail schema requires query, and that briefing_order persists while verbosity is session-scoped.

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 and enumerates four play-facing actions (recap, verbosity, briefing_order, discover), and it distinguishes this tool from story content, Novel lifecycle, and manage_diagnostics. However, the action schema includes many additional actions not covered by the description, so the stated purpose is clearer for a subset than for the full tool.

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

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

It gives explicit 'Use when' and 'Do NOT use when' guidance, naming alternatives such as manage_diagnostics for health/audit/event-log/category operations and manage_story for recording story content. The routing conditions are concrete enough that an agent can choose between this tool and its siblings without 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?

The description adds substantial behavioral context beyond the annotations: presence replaces the present set, cast adjusts the speaker pool via mute/unmute, next_speaker supports manual/forced/pooled selection, force overrides select, and autonomy changes apply only to the current scene. It also discloses that presence, autonomy, and cast state persist to the Novel and are audited, which is key for a destructive, non-idempotent mutation tool.

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

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

The description is dense but well organized: purpose first, action semantics next, then explicit use/avoid guidance and undo routing. Every sentence contributes operational information, and the semicolon structure keeps it front-loaded despite the 12-parameter surface area.

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, 12 parameters, destructive annotations, and an existing output schema, the description covers the important missing context: action behavior, current-scene scope, persistence/auditing, sibling routing, and undo. Nothing essential for correct invocation appears to be omitted.

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. The description adds meaningful action-to-parameter semantics, such as presence replacing the present set, cast using mute/unmute, next_speaker with force overriding select, and autonomy being scene-local, which goes beyond the field descriptions even though not every autonomy sub-parameter is elaborated.

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 resources: 'Manage scene presence, autonomy, and social-cast staging,' then clarifies each action's role. It explicitly distinguishes itself from manage_scene with a 'Do NOT use when' clause, so an agent can select it confidently.

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

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

It gives explicit positive triggers ('Use when: setting who is present, adjusting scene autonomy, choosing a speaker strategy, or selecting the next speaker') and explicit exclusions that route to manage_scene. It also names manage_history (action: undo) for reverting 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 only declare the crude profile (destructiveHint=true, non-idempotent). The description adds far more: decision and consequence entries are immutable and refuse update/promotion, mutations require the GM or Editor badge, changes persist to the Novel, and they are undoable via manage_history (action: undo), while list is read-only. It also discloses that record consumes the turn_handle minted by take_turn — a hidden side effect no annotation conveys.

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 front-loaded on the resource, then the per-action inventory, then the when/when-not routing — a sensible order with no filler sentences. The single dense paragraph is slightly run-on for nine parameters, but every clause carries information.

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

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

For a nine-parameter, five-action mutation tool the description covers action semantics, immutability constraints, permissions, side effects, undo path, and sibling exclusion; return values are covered by the existing output schema, so nothing an agent needs 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 goes further by binding parameters to actions: turn_handle is consumed on record, index applies to update/remove/promote, and list uses filter with offset/limit returning previews unless detail is set. It doesn't cover formatting expectations for entry text, so it stops short of a 5.

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

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

The description names a specific resource (the story journal) and then defines each of the five actions — record, update, remove, list, promote — with concrete semantics. It distinguishes itself from siblings by naming manage_lore for durable world facts, 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?

Explicit "Use when: recording, editing, removing, listing, or promoting story beats" and "Do NOT use when: recording a durable world fact — use manage_lore (action: set)." That is a named alternative plus the condition that selects it, 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 flag a destructive, non-idempotent, non-read-only tool, and the description goes well beyond that by splitting the action enum into mutating vs read-only sets, stating mutations are audited and persist to the Novel, clarifying that verify is purely local and never fetches, and describing the GM-only ruling ledger lifecycle (record/revert/list newest-first). It even discloses the edge case that activate/deactivate with key omitted act on the whole module.

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 the mutation/read-only split, then per-action clarifications, then the when/when-not block — a good information hierarchy. It is dense and slightly sprawling for a single sentence-chain, but nearly every clause carries distinct operational information, so waste is minimal.

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, 14-action multiplexed tool with an output schema already present, the description supplies everything an agent needs to pick the right action, understand side effects, and know where to go for undo or adjacent resources. Return-value detail is correctly omitted since the output schema covers it.

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

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

Schema coverage is 100% and each parameter already names its owning action, so the schema does the bulk of the work. The description still adds value the schema lacks: the whole-module behavior when key is omitted, ruling_list ordering (newest-first), and the verify pass/weak/unsupported outcome vocabulary.

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+resource ('Manage synthesis content') and names the concrete content types (voice examples, lore templates, action patterns, Ruleset Wisdom). It routes away from the nearest lookalike sibling twice (manage_history for undo, manage_codex for browsing), so an agent can distinguish it without opening any schema.

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

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

Explicit 'Use when:' enumeration covers every intent the tool serves, and 'Do NOT use when: browsing the codex — use manage_codex (action: list)' names the alternative and the condition selecting it. Undo routing to manage_history is also 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?

Goes well beyond the destructiveHint=true annotation: it states the auth requirement (GM or Editor badge), persistence target (the Novel), the recovery path (undoable via manage_history action: undo), and the asymmetry that resolve/forsake are terminal forward-only. The one gap is that 'destructiveHint' is not reconciled — the description never says what milestone/forsake destroy or whether they overwrite prior state, which matters for a destructive tool.

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

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

Front-loaded with purpose, then action semantics, then auth/undo, then use/don't-use routing — a logical order with no filler sentences. The action-semantics clause is dense enough that a skimming agent could miss the resolve/forsake distinction, keeping it just under a 5.

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

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

For a 10-parameter, 5-action mutation tool with an output schema, the description covers everything an agent needs to call it correctly: permissions, terminality, undo route, action-level effects, and the sibling it must not be confused with. 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 coverage is 100%, so baseline 3 applies, and the description earns a bump by tying parameters to actions (name/difficulty/scope/parties for set; outcome/consequences for resolve; reason for forsake) and by disclosing the undocumented default that scope defaults to 'shared'. It still doesn't explain the difficulty→countdown-tick mapping concretely or why both 'name' and 'vow_name' exist.

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

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

Opens with a specific verb+resource ('Track narrative vows, quests, and obligations with milestones') and then enumerates what each action value does — set creates and links a countdown, milestone advances, resolve/forsake close with distinct outcomes. An agent can distinguish this from the many sibling '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 'Use when:' list covers all five actions, and 'Do NOT use when:' names the confusable sibling and the exact alternative call (manage_countdown, action: set) for the timer case. This is the highest tier of 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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial context: mutations are audited and persisted, remove requires re-creation, convert replaces the described subtree, generate is bounded by TTRPG_WORLD_GEN_MAX_ROOMS, create_exit links both directions, and create_thing honors location_type only when location is set. These are non-obvious behavioral traits beyond the annotation flags.

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

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

Front-loaded with purpose, then behavior, then routing. Dense but every clause carries decision-relevant information (audit, permanence, env bound, conditional param rules). Semicolon-separated clauses make it slightly harder to scan than ideal, but the length is justified by 10 sub-actions and 33 parameters.

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 and annotations cover the safety profile, so the description does not need to explain return values. Combined with 100% schema coverage and the explicit use/when-not routing, an agent has everything needed to pick this tool and the correct action.

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

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

Schema coverage is 100%, so baseline is 3. The description adds cross-parameter semantics the schema does not: location_type is only honored when location is provided, and kind forces property defaults. It does not clarify most of the 33 parameters, but it adds real conditional meaning for a few high-value ones.

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?

Explicit verb-plus-resource: 'Manage the world model — rooms, things, exits', and it enumerates the semantics of each sub-action (create/update mutate in place, remove is permanent, convert replaces subtree, generate pulls from table pools). It also names the exact sibling tools it is not (run_command, manage_causality, manage_belief), so an agent can distinguish it without opening schemas.

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

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

Contains explicit 'Use when:' and 'Do NOT use when:' blocks with alternatives for each exclusion. Navigation goes to run_command (action: execute), objective-state transitions to manage_causality, entity beliefs to manage_belief. This is the strongest kind of 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?

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, and the description adds real context beyond that: changes persist, are audited, and both parameters silently fall back to active defaults. It does not explain what the destructive behavior actually overwrites (e.g., whether an existing badge or session state is clobbered), which is the one thing an agent calling a destructive tool most 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 action, then defaults, then use/don't-use routing and the revert path – every clause carries information. Slightly dense in places (the long compound first sentence, jargon like 'badge the seat'), but no wasted 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?

Strong coverage for a mutation tool: output schema handles the recap return value and annotations carry the safety profile, so the description only needs routing and default behavior, which it supplies. The remaining gap is the unexplained destructive consequence, which would matter more if annotations were 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?

With 100% schema coverage the baseline is 3, and the description earns a step up by explaining that both parameters are optional and default to the active Novel and current badge. That fallback semantics is behavior the schema's per-field descriptions do not convey.

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

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

States a specific verb and resource with its composite effects: opening a session by resuming a Novel, activating a badge, and returning a recap. This is clearly distinguishable from siblings like take_turn, manage_novel, and close_session 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?

Explicit 'Use when' (starting/resuming a session, especially after a restart) and 'Do NOT use when' clauses route to named alternatives: manage_novel (action: create) for creating, take_turn for running a turn, and manage_history (action: undo) as the revert path. 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?

Despite the annotations only giving a generic destructive/non-idempotent profile, the description discloses the concrete behavioral contract: rolls and state changes persist to the Novel, are audited, and a roll with no following write is flagged as an uncommitted roll. It also supplies the recovery path (revert the most recent mutation via manage_history with action: undo), which is exactly the context an agent needs before making an irreversible 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?

Purpose, persistence/audit behavior, undo path, dice mechanics, and use/exclusion guidance are all front-loaded with no filler sentences. The paragraph is dense — a single block packing four distinct concerns — but every sentence carries information an agent needs.

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-action, 23-parameter mutation tool the description covers the family taxonomy, the audit/undo contract, and the notable roll mechanics; an output schema exists so return values need no explanation. It stops short of explaining the 'op' sub-operation axis or what each of the state-mutating actions (fate_aspect, ironsworn_momentum, forged_downtime) does, leaving that to the 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 real meaning at the dispatch level: it explains that fate_roll uses dF, ironsworn_move compares an action die against two challenge dice, and forged_action_roll takes the highest of a d6 pool. It does not add per-parameter guidance (e.g., how 'op' sub-operations interact with 'action'), which caps this below 5.

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

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

The opening sentence names a specific verb ('Resolve') and enumerates the exact resources covered: Fate Fudge dice/aspects/Fate points/stress, Ironsworn momentum/moves/progress, Forged action rolls/stress/trauma/downtime, and generic table rolls. It explicitly distinguishes itself from the sibling ruleset roll tools and manage_vow, 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 an explicit 'Use when' clause (resolving a Fate, Ironsworn, or Forged mechanic, or rolling on a ruleset generation table) and an explicit 'Do NOT use when' clause naming two alternatives with the sibling and action to use instead (ruleset roll tools; 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, but the description adds substantial context beyond them: the drain is atomic and audited, 'cancel' restores the pre-workflow snapshot, an applied outcome is not reversible, and a second call returns STATE_CONFLICT. These are the exact behavioral facts an agent needs before committing.

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?

Effect-first opening sentence, then constraints, then explicit Use/Do-NOT-use blocks — all front-loaded with no filler. Every clause carries either a selection rule or a behavioral consequence.

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

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

For a destructive, non-idempotent mutation with two required params, the description covers prerequisites (pending decision), irreversibility, snapshot restore, and the STATE_CONFLICT failure mode; an output schema exists so return values need no explanation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint the schema lacks: option must match one of the emitted choices, and the cancel path's snapshot-restore semantics. It stops short of describing the 'decision' parameter's matching rules, so it is not a 5.

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

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

States a specific verb and resource ('Answer a pending workflow decision'), plus the effects (atomic drain, persist to Novel). It clearly distinguishes itself from siblings by naming set_badge and a state tool as the alternative when nothing is pending.

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: the server emitted a [NEED_INPUT] prompt' and 'Do NOT use when: no decision is pending', and names the concrete alternatives. There is no inference required to select this tool.

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

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

Goes well beyond the annotations: it discloses that execute mutates world and entity state, persists, and is audited; that no undo snapshot is taken so a mistaken move must be reversed with the inverse command; and that resolve/suggest are non-mutating. It also states an authorization rule (GM-only navigation/mutation on a ruleset-bound Novel, Player badge limited to read-only perception) that no annotation conveys. This is consistent with destructiveHint=true and readOnlyHint=false.

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 mode breakdown before the operational caveats, and every sentence carries content (mutation/persistence, no undo, permission model, use/don't-use). It is dense and long for a description, but the density is justified by five distinct modes; splitting the permission sentence out would improve scannability.

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; the description instead covers the dimensions that matter for a destructive, multi-mode, permission-gated tool: which action mutates, how to recover from a bad mutation, and who is allowed to call it. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds cross-parameter meaning the schema does not: which modes consume free-form text ('execute accepts free-form text') and the scoping rule that 'source and target apply only to perception queries'. That conditional applicability is genuinely useful for avoiding wasted arguments on resolve/suggest.

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

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

Opens with a specific verb and resource ('Run the spatial parser') and then enumerates the three primary modes - execute, resolve, suggest - plus the perception modes visibility/audibility. It explicitly separates itself from manage_world and manage_lore, so an agent can pick it out of a crowded 34-tool sibling list 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 explicit 'Use when:' triggers (a player or narrator takes a physical action, needs a movement outcome without mutating, wants intent mapped to tools) and explicit 'Do NOT use when:' exclusions that name the correct alternatives (manage_world for model creation/editing, manage_lore for durable world facts). This is the when/when-not/alternatives pattern at full strength.

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: discloses that access is gated server-side for the active Novel, that tools/list is re-filtered immediately, that a narrower badge can revoke tools mid-task, and that changes are audited and reversible. This meaningfully expands on destructiveHint=true, which alone would not tell an agent that the 'destruction' is revocable tool-access loss.

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 action and the value list, then layers usage and exclusion in tight labeled clauses; the density is high but nearly every clause carries operational information, though the single opening sentence is long.

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

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

Covers scope, side effects, reversibility, auditability, timing of the tools/list re-filter, and an explicit exclusion; with an output schema present, no return-value explanation is needed. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100% and the enum is fully documented, so the baseline is 3; the description's only added nuance is the per-Novel scoping of the badge, which is about behavior rather than the parameter itself.

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

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

States a precise verb+resource ("Switch the active badge") and enumerates the exact target values plus per-Novel scope, so it is unmistakable against siblings like manage_session or respond_decision.

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: entering the story, spectating, or stepping away to edit" and an explicit exclusion routing pending workflow decisions to respond_decision -- a named alternative with the condition that selects it.

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

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

Adds real value beyond the annotations: non-persistent, no Novel state mutated, handle is session-scoped and single-use, consumed by manage_story (action: record), and recording works even without it. Slight tension with idempotentHint=true, since each call mints a fresh single-use handle; the description does not reconcile repeated-call behavior, which keeps it from 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 action, then lifecycle, then use/don't-use routing — every clause carries distinct information. Slightly dense, with the handle-consumption detail packed mid-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 2-parameter tool with full schema coverage, an output schema, and complete annotations, the description supplies the missing pieces: persistence semantics, handle lifecycle, the downstream consumer, and graceful degradation if the handle is skipped. 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 'intent' and 'entity_id' are already documented; the description only adds the notion that intent is fed to the parser. Baseline 3 applies since the schema carries the parameter burden.

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

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

States a specific verb chain and resource: resolve a player intent through the parser and mint a turn handle for the story record. It also explicitly distinguishes itself from manage_combat and resolve_mechanic, so an agent can route between them without opening any schema.

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

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

Gives an explicit 'Use when: taking a turn before recording its outcome' plus two named 'Do NOT use when' cases with the exact alternative tool and action (manage_combat advance, resolve_mechanic roll). This is the strongest form of routing guidance.

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