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

Goes well past the annotations: it discloses partial idempotency per operation (set_* and tags safe, add_links duplicates on retry), the soft-delete revival side effect of any non-forget operation, the automatic supersession cleanup triggered by setting canon_status to 'accepted', and the restoredCount field. These are exactly the non-obvious mutation semantics an agent needs before calling a destructive batch tool.

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?

Front-loaded with the core batch purpose and cap, then dense operation and edge-case notes. A few clauses restate structured facts ('Mutates' echoes destructiveHint; 'max 100' echoes maxItems), but the density of genuinely new caveats justifies the length.

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?

Annotations cover the safety profile and an output schema exists, so the description's job is the gotchas — and it delivers: retry duplication, implicit revival of soft-deleted rows, automatic supersession cleanup, and a pointer to the explicit alternative. Nothing material for correct invocation appears 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 beyond the schema: it groups operations mentally, flags add_links retry duplication, explains the interaction between set_canon_status and superseded_by pointers, and notes remove_links also removes the inverse. It does not, however, elaborate on merge_metadata merge depth or precedence, which remains schema-only.

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?

Names a specific verb and resource ('Batch update multiple memories'), states the batch cap, enumerates the exact operation families supported, and explicitly states the one thing it does not do ('Does NOT support headline/body replacement'). An agent can immediately tell this apart from memory_update (single record) and memory_forget (soft-delete only).

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?

Gives clear operative guidance: use it for batches up to 100, use clear_superseded_by when you want to break supersession without touching canon_status, and note that forget is available here as an operation. It does not, however, explicitly say when to prefer this over memory_update for a single memory or over memory_forget, leaving that routing to inference.

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