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

Goes well past the annotations with details they cannot express: the old entry is retained and marked superseded, wording is saved verbatim and flagged in the response, the write is verified before VERIFIED is returned, and there is no edit or delete path. This confirms the non-destructive hint and explains the response signal, which matters since there is no output schema.

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 and the append-only constraint are front-loaded, and most sentences carry distinct information (retention, verification, length budget, pointer convention). Some phrasing is dense and repetitive, e.g. the 'Doubt wording and telling words' sentence, which could be tighter.

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 no output schema, the description supplies the response signal (VERIFIED, marked lines) and the mutation semantics an agent needs for a write tool. Minor gaps remain, such as what happens on verification failure or what a partial/duplicate correction looks like, but the essentials are present.

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 earns above that by stating that all four content fields are required and each should be one or two sentences, ~80 words total, with detail pushed to a dated note and referenced by pointer. It also explains that quoted doubt wording must be preserved verbatim, which the schema does not say.

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 ('Append one entry to this home's CORRECTIONS list') and defines what an entry is ('one saved fact replaced by another'), which separates it from save_note, capture_decision, and supersede. An agent can tell what artifact this creates 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?

'Append-only — there is no edit and no delete' implies that corrections elsewhere belong to a different tool, and the note-versus-field guidance implies when to use a dated note instead. However, no sibling tool is named (notably supersede, which sounds adjacent), so the routing decision 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.