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

Beyond the annotations' destructiveHint, the description reveals the key leg-selection rule (removal targets the leg matching the spell's own ruleset), the specific failure mode (400 on ruleset mismatch), and the auth requirement. These are non-obvious behaviors that materially affect how an agent should call and interpret the 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?

Three compact sentences front-load the core action and then efficiently add the non-obvious ruleset behavior and permission requirement. Every sentence earns its place, and the code-formatted parameter names make the reference unambiguous.

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

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

The description covers the destructive action, leg-selection semantics, mismatch response, and caller permission. An output schema exists, so return-value details need not be repeated. An agent has everything needed to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so campaignId, spellId, and the ruleset enum/behavior are already documented in the schema. The description restates the important ruleset nuance but does not add parameter semantics beyond what the schema provides. A baseline of 3 is appropriate when the schema does the heavy lifting.

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 an explicit verb ('Remove') and a precise target ('a vault spell from a campaign's allowlist'), clearly distinguishing this from deleting the vault spell itself (vault_delete_spell) and from removing other campaign resources (play_remove_campaign_item/rule/player). The title reinforces the same action, leaving no ambiguity about the resource affected.

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

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

The description clearly states the caller permission prerequisite ('Caller must have contribute') and explains when the optional ruleset parameter should be used: only as confirmation, never as a retargeting mechanism. It does not explicitly name alternative tools such as play_list_campaign_spells for inspecting the allowlist, but the context is sufficient to guide correct use.

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