Update memory

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal key traits: edit preserves state, supersede creates a non-destructive version chain with id winning over other_id, and resolve_conflict records a keep-both judgment. However, it omits any mention of side effects (e.g., whether old versions are hidden, permissions required), return formats, or error behaviors, leaving significant gaps for a mutation 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?

The description is highly concise, using a compact list format to convey each action's semantics. It front-loads the key actions and their distinctions. However, it lacks a leading sentence summarizing the tool's overall purpose (e.g., 'Updates an existing memory using one of several actions'), which would improve readability. It is efficient but slightly abrupt.

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 the tool's complexity (12 parameters, 5 actions, no output schema), the description covers the action semantics well but does not describe the expected return value, error handling, or any prerequisites (e.g., store context, id existence). It also doesn't explain the overall update workflow or interaction with sibling tools. For a tool with this scope, more context is needed to call it correctly in varied scenarios.

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 92%, so the schema documents most parameters. The description adds value by clarifying the meaning of the 'action' parameter and how it relates to other parameters (e.g., 'supersede: id wins over other_id' explains the other_id parameter; 'edit: revise wording/metadata in place' explains content and source). This goes beyond the bare schema enumeration and helps an agent understand parameter usage in context.

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 clearly specifies that this tool updates memories through five distinct actions (edit, supersede, set_state, link, resolve_conflict), each with a concise semantic definition. It explicitly differentiates edit (preserves state) from supersede (non-destructive version chain), which prevents ambiguity in intent. The purpose is unambiguous and tied to the tool's name and title.

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 offers internal guidance (e.g., 'meaning-changing revisions should use supersede instead') but does not state when to use this tool versus its siblings (memory_remember, memory_forget, etc.). It implies it is for modifying existing memories, but the boundary with creation and deletion tools is not explicit. An agent must infer that creating a new memory belongs to memory_remember and that this tool is for updates.

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