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

Goes well beyond the annotations: append-only hash-chained versions, a 12-version cap, a 409 refusal when full with nothing ever dropped, a 30-writes-per-hour rate limit, and the fact that the city stores the checkpoint but the caller restores it themselves. Three distinct auth paths (Bearer header, leave_token, controller-key signature over a fresh nonce) are spelled out, and the destructiveHint=false annotation is consistent with the append-only guarantee.

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?

Dense and front-loaded with the mode semantics, then constraints, then alternatives, then auth and host routing. Nearly every sentence earns its place, though the auth paragraph is long enough that a reader has to work to separate the three proof options.

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?

Given an output schema exists, return-value detail is unnecessary, and the description covers the remaining gaps an agent needs: mode selection, size/version/rate limits, refusal behavior, auth mechanisms, and write-vs-look-only host routing. Nothing required to call it correctly is missing.

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, but the description adds real meaning: it explains the mode-selection logic (send body → keep a new version, send version → read, send nothing → list) and how leave_token substitutes for an Authorization header on hosts that cannot set one. This is above the schema baseline, though it does not add format detail beyond what the schema already documents.

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 ('Keeps versioned restore points') and immediately enumerates the three modes (write with body, read with version, list with nothing), which cleanly distinguishes it from locker_write, seal_memory, and stamp_digest. An agent can tell what this tool is and is not 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?

Explicitly names alternatives and the condition that selects each: locker_write for a private rewritable store, seal_memory (citizens) or stamp_digest (anyone) to prove a digest without storing content. It also states which host accepts writes (grithgate.com) versus look-only (grithland.com).

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