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

Discloses important behavior beyond annotations: partial patch semantics ('Only supplied fields change'), optimistic concurrency via baseUpdatedAt, rejection with OUT_OF_SYNC, and atomic failure ('nothing is written'). This complements the idempotentHint and is consistent with 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?

Two dense sentences with no filler. The core purpose is front-loaded, followed immediately by the critical prerequisites and failure mode. Every sentence earns its place.

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

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

While the concurrency semantics are well covered, the tool is not invocable from the description because the parameter shape is undefined: no id field, no field-patch structure, and no formal baseUpdatedAt parameter despite the schema showing zero properties. Given the empty schema, this is a major 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?

The input schema exposes no properties, so the description must carry the full parameter burden. It does explain baseUpdatedAt's meaning and source, but it never names the actual parameter keys for the spell id or the fields being patched, leaving the agent unable to construct a valid request from the description alone.

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 ('Patch'), a clear resource ('existing user-authored spell'), and identifies the operation mode ('by id', 'only supplied fields change'). This is easily distinguished from sibling tools like vault_search_spells and vault_get_spell, and from update tools targeting other resources.

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 instructs the agent to confirm the id first via vault_search_spells / vault_get_spell, and names the exact prerequisite for a successful write: a fresh baseUpdatedAt copied from vault_get_spell. This is strong precondition guidance that leaves little to inference.

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