Write a deliberate note to the project brain (decision / question / milestone / skill / resolve / update)

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

The description discloses lifecycle behavior beyond what annotations provide (which is none, since no annotations are supplied): new decisions supersede overlapping older ones, ✓ resolves/archives a matching card, ~ updates in place, and skills 'resurface every session and never age out.' It also exposes the potential side effect of SUPERSEDING/dedup and the guard card's PreToolUse behavior for blocking/warning. It does not fully inventory every side effect (e.g., evidence fingerprinting) but for an 8-parameter tool with no annotations, this is still strong disclosure.

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 every sentence earns its place: it defines the tool's niche, differentiates from a sibling, lists the marker meanings, explains guard cards, and notes the default canvas. It is a long paragraph rather than a scannable list, but for a complex 8-parameter tool covering multiple card types, the length is mostly justified.

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 tool with nested objects, 8 parameters, multiple marker modes, guard behavior, and no annotations or output schema, the description covers the necessary context: what the card lifecycle does, when to use guard/block, how markers change behavior, what the default canvas is, and how this relates to siblings. Even though the schema already covers each parameter, the description supplies the cross-cutting semantics that make the tool safely usable.

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, the schema already documents every parameter. The description adds meaning by mapping markers to lifecycle behavior (+, ✓, ~, etc.), clarifying the difference between a skill and a decision, and adding the nuance that guard-card severity 'block' should never be authored without explicit user instruction. It doesn't add exact formatting for every field beyond the schema, but it goes beyond merely repeating schema text.

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 highly specific verb+resource ('Record something in the project brain ON DEMAND') and covers every marker type and lifecycle behavior (decision, question, milestone, skill, resolve, update, guard). It explicitly distinguishes itself from add_to_canvas, so an agent can tell them apart 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?

It states a clear when-to-use ('record a decision, ask an open question, mark a milestone, log a skill, resolve a finished item, or correct a card'), explains what the tool does not do (not a flat append like add_to_canvas), gives concrete examples ('always dedup zKeys before REORDER'), and clarifies defaults ('Defaults to the project brain ("brain")'). It also explains guard-card usage and the block severity constraint, which is strong context that would otherwise be missing.

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