memory_write

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

The description adds substantial behavioral context beyond the annotations: the append-only invariant, idempotency of request_key (consistent with idempotentHint=true), 'Lessons remain proposed until a separate lesson_review', 'A plan preserves scope and next action; it does not prove execution or authorise host tools', and 'receipt_ids attaches mechanical host evidence; it cannot supply missing interpretation'. These are genuine disclosures an agent needs that the annotations do not carry. No contradiction with annotations found.

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 description is a single dense wall of text covering 11 operations with no bullets, headers, or grouping. Every sentence carries information, and the core invariant is front-loaded, but the lack of structure makes it significantly harder to parse than it should be for a tool of this complexity. It is verbose rather than concise.

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 tool with 11 operations, nested payload objects, and no output schema, the description attempts to cover every operation with its key constraints and preconditions. It is reasonably complete — an agent has enough to call each operation correctly. The completeness is limited only by the readability problems noted above, not by missing information.

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 0% schema description coverage, the description must compensate for parameter meaning, and it does so substantially through operation prose: it explains expected_version (optimistic concurrency), the subject-omission rule for document refresh, absolute path requirement, that session_id binds the decision to subsequent tools, and the role of request_key. The main weakness is that this meaning is embedded in a dense prose block rather than mapped parameter-by-parameter, making it harder for an agent to retrieve.

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 opening sentence 'Append explicit records; never overwrite history' states a specific verb, resource, and invariant with total clarity. The tool is implicitly differentiated from the read-oriented siblings memory_get and memory_context, and the enumerated operations (sync, start, document, source, record, reconcile, etc.) leave no doubt about what the tool does.

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?

The description provides explicit when-to-use guidance throughout: 'read direction first' for approve_requirements, 'read their schema first' for plan/sprint, 'read schema id checkpoint' for checkpoint, and advice to bundle checkpoint as data.checkpoint to avoid an extra call. It also tells the agent to wait using 'project-memory review --wait CHECK_ID' rather than polling. It lacks an explicit statement of when NOT to use this tool in favor of a sibling, though the read/write split with memory_get is strongly implied.

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