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

Beyond the annotations, it discloses the most consequential behaviors: the write replaces existing content wholesale, size is checked against a plan budget (12,000 chars on Free), over-budget writes are refused, and no approval step is needed. The one tension is that 'it replaces what is stored' reads as an overwrite while destructiveHint is false; the description is disclosing real behavior rather than misleading, but the mismatch is worth noting.

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?

Three tight sentences, front-loaded with the core action and replacement semantics, then budget/refusal rules, then the compact shortcut. Dense but every clause carries information; no filler.

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 mutation tool with no output schema and a nested required body object, the description covers the important operational constraints (budget, refusal, replacement, no approval) but leaves the body structure and idempotency/confirmation parameters unexplained. An agent could call it, but would be guessing at the body payload and retry semantics.

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 description coverage is only 14% across 7 parameters, so the description must carry the load, and it only explains compact and, indirectly, path. The nested body object (title/content/reason), idempotency_key, confirmation_id, and confirmation_via are left entirely to the schema, which barely documents them.

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 specific verb and resource ('Write a project's memory file, PROJECT_GUIDE.md') and states the write is a full replacement, which is far more precise than the title alone. It does not explicitly distinguish itself from siblings like save_project or delete_memory, so it stops short of a 5.

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 gives useful operating context — over-budget writes are refused, compact:true stores a shorter version in the same call, and no approval is required — which implies when to reach for the compact path. However, it never states when to use this tool versus save_project or when a memory write is appropriate at all.

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