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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: the 100 KB size cap, 100 writes/day rate limit, retention of one previous version for rollback_memory, and the required token scope. The only minor gap is it doesn't say what the response looks like, though no output schema exists to cover that.

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 core constraint (whole-file replacement) is front-loaded and the alternative is offered immediately after. It is dense but every clause carries information; the bracketed scope note at the end slightly duplicates the earlier 'Needs token scope memory' sentence.

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 destructive single-parameter write tool, the definition covers limits, rollback availability, authentication requirements, privacy expectations, and the safer alternative. Nothing an agent needs to invoke 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?

With a single parameter at 100% schema coverage, the baseline is 3, but the description goes further by explaining that body is the full replacement content, giving a concrete markdown example including the next_since convention. This meaningfully clarifies what to put in body beyond 'full new content'.

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 uses a specific verb+resource framing — it replaces the entire memory file with markdown notes — and distinguishes itself from read_memory (read it back) and append_memory (append without re-uploading). An agent can tell exactly what this tool does and what it is not.

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 explicitly routes the agent: read_memory first, then write once, or use append_memory {text, section} for incremental additions. It also gives an exclusion — not for secrets or the human's private data — which is precisely the when-not guidance most definitions lack.

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