NPC Management

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false; the description goes beyond them by disclosing that mutating actions persist to the Novel and are audited while read-only actions do not mutate state, plus the undo path via manage_history. It stops short of saying what 'remove' actually destroys or whether operations require specific permissions, so it adds real value without being fully exhaustive.

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

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

Four short sentences, front-loaded with purpose, then behavior, then recoverability, then the use/don't-use rules. No sentence is redundant and no filler is present.

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

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

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

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

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

Schema description coverage is 100% and each of the 9 parameters carries its own description including action-scoping hints (e.g. 'NPC identifier (update/remove/get)'), so the schema does the heavy lifting. The prose adds no parameter-level syntax, defaults, or format details beyond it, making baseline 3 appropriate.

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

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

States a specific verb+resource with scope ('Manage non-player characters in the active Novel') and immediately separates itself from the closest sibling via the explicit 'Do NOT use when: managing player characters — use manage_character'. An agent can pick between manage_npc and manage_character without opening either schema.

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

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

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

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