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

With no annotations present, the description carries the full burden and does disclose substantial behavior: proactive capture, approval gating for inferred facts, single-idea-per-memory constraint, alias attachment, current-project default scope, and a duplicate-suppression rule for reworded retries. It does not describe the return value or how conflicts/errors surface, which keeps it short of a 5.

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 definition is long but front-loaded: purpose first, then save/skip criteria, then edge cases (inference approval, dedup, scope). Most sentences carry operational guidance rather than filler. It is dense enough that a small amount of tightening is possible, but nothing is padding.

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 6-parameter, annotation-free write tool with no output schema, the description covers purpose, usage policy, dedup mechanics, and scope semantics thoroughly. The remaining gap is return/confirmation behavior and what a saved memory looks like, which is only partially inferable from the mention of a 'given id'.

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 genuine meaning beyond the schema: it explains the scope decision ('Default scope is the current project; use the personal scope for facts about the user that apply across all projects') and the intent of aliases ('alternate phrasings... so differently-worded questions still match'). It does not clarify the 'when the parameter is available' gating or the source flag beyond what the schema states.

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 gives a specific verb (Save) and resource (a fact, preference, decision, or note to persistent local memory), so the agent knows exactly what this tool writes. It also names a sibling, memory_supersede, giving negative differentiation against the update path. This is far beyond a restatement of the name.

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 explicit when-to-use ('Call this PROACTIVELY whenever the user shares something worth remembering'), what to save vs. skip, when to propose rather than save ('For facts you infer yourself... propose them first and save only on approval'), and a dedup rule with the alternative tool ('use memory_supersede on the given id'). All of the routing conditions an agent needs are stated, not implied.

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

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

Annotations supply only destructiveHint=true; the description carries the rest and does so well: deletion is permanent, the agent must restate the memory's content and obtain confirmation first, and soft=true is a one-way retraction that keeps the file while removing it from lists and search. These are exactly the behavioral traits an agent needs before firing an irreversible call.

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 action, then the usage trigger, then the safety-critical permanence/confirmation constraint and the soft alternative. Every sentence changes agent behavior; none is 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?

No output schema exists, so the description must stand alone, and it covers the decision that matters most (permanent delete vs. one-way soft retraction) plus the confirmation protocol. Gaps remain around id provenance and failure behavior when the id is unknown, but nothing essential to invoking it safely 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?

Schema coverage is 50%: `soft` is well documented in the schema itself, while `id` has no description anywhere. The description restates soft's effect and adds the one-way/file-kept detail, but gives no guidance on the `id` parameter (format, or that it comes from memory_search/memory_list), so it only partially compensates for the coverage gap.

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?

States a specific verb+resource ("Delete a memory by id") and immediately clarifies the two modes of removal, so the agent knows this is the removal tool rather than a search or write tool. However, it never differentiates itself from the overlapping sibling memory_supersede, which also changes memory state, so the sibling-routing clause of a 5 is absent.

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?

"Use when the user asks to forget something" gives an explicit trigger, and the description adds the hard-vs-soft selection condition (soft is for when the user is unsure, per the parameter description). It stops short of naming when not to use it or pointing at memory_supersede as the alternative for superseded facts.

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

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

Annotations only declare readOnlyHint=true, but the description adds real behavioral context: numbering is only valid for the listing just produced, deletion downstream is permanent and requires re-reading plus confirmation, and include=all exposes superseded/retracted/archived rows. It also prescribes how results should be surfaced to the user, which is well beyond annotation coverage.

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?

Purpose and output format are front-loaded in the first sentence, and every subsequent sentence carries actionable guidance. It is dense and runs long for a list tool, but there is little outright padding.

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?

With no output schema, the description usefully defines the return shape (numbered inventory with [type] id= created= source=) and how to render it, which is the main gap it needs to fill. The remaining gap is the undocumented type and limit parameters.

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 50%: scope and include carry detailed schema descriptions (including the D68 default change), while type and limit have no schema description at all. The description explains scope=both and include=all usage but never clarifies what type filters on or what limit does, so it only partially compensates for the gap.

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 first clause states a specific verb, resource, ordering, and output shape: 'List memories in a scope, newest first, as a numbered inventory.' It also implicitly separates itself from memory_search (retrieval by query) and memory_forget (deletion), which it names explicitly later.

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 explicit triggering conditions ('When the user asks what do you remember about me?, use scope=both'), a named alternative for deletion (memory_forget), and the precondition for using include=all (audit view). Nothing about when to choose this over siblings is left to inference.

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

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

With no annotations, the description carries the full load and does disclose meaningful behavior: only one step of progression at a time, rejection requires a note, rejected memories are never deleted and can be revised and resubmitted. It also usefully notes the tool is exposed by the MCP server/CLI but not the opencode native plugin. It omits permission/auth requirements and what happens when a memory is already at the top of the ladder.

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 sentences, front-loaded with the primary action and the ladder states, then the reject/undelete semantics. The trailing parenthetical about CLI and plugin exposure is environment metadata that is slightly tangential but still relevant to availability, so it isn't pure waste.

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 five-parameter mutation tool with no annotations and no output schema, the description covers the core transition and rejection behavior but says nothing about success results, error cases (already published, unknown id), or who may approve. It is adequate but leaves real gaps for an agent invoking it blind.

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 100%, so 3 is the baseline. The prose adds meaning beyond the schema by explaining the reject-with-note flow and the revise/resubmit cycle, which contextualizes the reject, note, and resubmit parameters. The by (reviewer override) parameter is never explained in the description.

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 gives a specific verb and resource — advance a project memory up a named review ladder (proposed → approved → published) — and covers the alternate action of rejecting with a note. It doesn't name or distinguish itself from the many close siblings (memory_submit, memory_propose, memory_resolve, memory_supersede), so an agent must still infer which of those handles other lifecycle transitions.

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?

Usage is implied rather than stated: you call it when a memory needs to move one ladder step or be rejected. There is no explicit when-not guidance and no named alternative (e.g. 'use memory_submit for a new memory'), which matters given ten sibling tools with overlapping review semantics.

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

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

With no annotations, the description carries the full burden. It usefully discloses that operation is a copy (originals preserved) and that the output is a pending review draft rather than an approved record. However, it omits permissions/auth requirements, whether drafts can be re-proposed or deduplicated, and any failure behavior.

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 short sentences, front-loaded with the action and the key behavioral guarantee. The trailing environment parenthetical is compact but is tangential to invoking the tool, slightly diluting focus.

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 two-parameter, no-output-schema tool with no annotations, the description adequately covers what is produced and where it lands. It does not need to describe return values, and remaining gaps (permissions, outbox location, idempotency) are minor for this scope.

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 100%, so both parameters (ids, localApprove) are already documented in the schema. The description adds no format or constraint detail beyond what the schema provides, so the baseline 3 applies; 'review drafts' loosely complements localApprove but does not explain it.

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?

States a precise verb and resource: copy personal memories into the project outbox as review drafts, and immediately clarifies the non-destructive nature ('originals stay put'). This distinguishes it from sibling mutations like memory_promote or memory_submit, which move/publish rather than copy.

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 never says when to choose this over memory_promote, memory_submit, or memory_supersede. The parenthetical only covers which surfaces expose the tool (MCP server, CLI, not the opencode plugin), which is availability, not usage guidance.

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

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

The description states that apply=true 'performs the mapped transitions locally', i.e. it mutates local memory state, while the annotation declares readOnlyHint=true. That is a direct conflict: the tool does modify its environment when apply is set. The otherwise-excellent disclosure of mapping semantics and no-push behavior cannot overcome a flat contradiction with the structured hint.

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-loads the core read-and-map behavior, then the apply semantics, with no redundant sentences. The trailing parenthetical about which surfaces expose the tool is slightly extraneous but plausibly useful for routing.

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 one optional parameter, no output schema, and the need to explain a non-obvious state mapping, the description is largely sufficient: it covers the mapping rules, default vs apply mode, and the no-push constraint. It omits what the report format looks like and any GitHub auth/permission requirements, which leaves minor gaps.

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% for the single parameter, so the schema already documents apply. The description restates the same semantics ('Report by default; apply=true performs the mapped transitions locally (no push)') and only adds the useful 'no push' qualifier, which is marginal beyond the schema baseline.

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?

States a specific verb+resource: reads the current branch's GitHub PR and maps its review state onto in-repo memories, with explicit mapping rules (merged→published, approval→approved, changes-requested→suggestion). This is clearly distinguishable from siblings like memory_status or memory_submit, which deal with memory state rather than PR review state.

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?

Clearly splits behavior: report by default, apply=true to perform transitions, and notes no push occurs. It gives the condition that selects the mutating path but does not name a sibling or point to an alternative when the agent only wants raw PR data, so it stops short of full when/when-not routing.

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

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

With no annotations, the description carries the full burden. It usefully discloses a key behavioral policy — semantic conflicts are reported, never auto-resolved — and notes the environments where the tool is exposed (MCP server/CLI but not the opencode plugin). It does not cover mutability/reversibility of the merge output, permissions, or error behavior.

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 short sentences, front-loaded with the operation and its safety guarantee. The trailing parenthetical about plugin availability is slightly tangential but earns its place by telling the agent where the tool exists.

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 single-parameter tool with no output schema and no annotations, the description covers the operation modes, the conflict-handling policy, and availability constraints. It could say more about what the merge returns or writes, but it is largely sufficient for correct invocation.

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% and the single parameter's purpose ('Memory id or file path to resolve. Omit to list conflicts.') is fully documented in the schema. The description's dual list/merge framing matches the schema but adds no syntax or format detail beyond it, so the baseline of 3 applies.

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 resource (git-conflicted memory files) and states two distinct operations: listing them or performing a field-level 3-way merge on one. It is clear enough that an agent understands what the tool does, but it does not explicitly contrast itself with any sibling (e.g., memory_status or memory_pr_status).

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 two modes (list vs. resolve one) imply when to use each, and the schema note 'Omit to list conflicts' reinforces it. However, no alternatives or exclusions are named, and there is no explicit statement of prerequisites (e.g., that a git conflict must already exist). Usage is inferable but not spelled out.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest. It adds real behavioral context: keyword/BM25 matching (not semantic), results span project and personal scope, and the implicit warning that recall is phrasing-sensitive (hence the multi-phrasing advice). It stops short of describing ranking, scores, or result limits.

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 purpose and return behavior, then the usage trigger, then the search strategy. Every sentence earns its place, though the strategy sentence is long and could be tightened.

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?

No output schema, so the description must cover returns — and it does state that matching memories from project/personal scope come back. With 4 params and 75% schema coverage, the remaining gaps (type and limit behavior) are minor and mostly covered by the schema itself.

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 75%, so the schema documents most fields. The description still adds value on query semantics ('break the question into concepts... synonyms, shorter keyword forms') and on scope ('current project and/or personal scope', 'check the other scope too'), which maps to the scope enum's project/personal/both values. It does not mention the type or limit parameters.

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?

States a specific verb (search), resource (persistent memory), and mechanism (BM25 full-text keyword matching), plus the return scope (current project and/or personal scope). This clearly distinguishes it from siblings like memory_list, memory_add, and memory_forget.

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?

Explicitly tells the agent when to call it ('before asking the user about past decisions, conventions, or preferences') and gives concrete strategy: break the question into concepts, try 2-3 phrasings, check the other scope before concluding nothing is stored. That is actionable when-to-use guidance rare in tool descriptions.

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

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

readOnlyHint=true already covers the safety profile, so the description's added value is the workflow obligation it creates (the agent must ask the user which drafts to sync afterward) and the availability caveat that the opencode native plugin does not expose this tool while the MCP server and CLI do. It does not describe pagination or output shape, but the annotation carries the safety burden.

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 what the tool returns, then the when-to-call triggers, with the CLI/plugin caveat confined to a trailing parenthetical. Dense but every clause carries information; the only cost is a long opening 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?

With no output schema, the description must convey the return content, and it does so precisely by naming the three state categories the pipeline reports. For a zero-parameter, read-only status tool, nothing needed to call 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?

The tool takes zero parameters, which sets the baseline at 4. There is nothing for the description to clarify about inputs, and it correctly offers no parameter prose.

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 ('Show the project memory sync pipeline') and enumerates exactly what is shown: outbox drafts, repo memories awaiting review or published, and uncommitted repo files. That scope is clearly distinct from siblings like memory_list or memory_pr_status, though it never explicitly contrasts itself with them.

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 explicit invocation triggers — at session start, when the server reports drafts waiting for review, or when the user says 'sync memory' / '同步记忆' — and even states the required follow-up ('ask the user which drafts to sync'). This is as prescriptive as usage guidance gets.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses the local commit on the current branch, that outbox originals are moved out (a destructive/relocating side effect), that branches are never created, and that push/PR commands are only printed and require explicit approval. It also notes environment availability (MCP server and CLI, but not the opencode native plugin), which prevents a class of false invocations.

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 action is front-loaded and the side-effect/approval constraints follow in logical order; almost every clause earns its place. The trailing parenthetical about CLI/plugin support is useful but slightly tangles the structure, and the block is denser than it needs to be for a single sentence per idea.

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 3-parameter mutation tool with no annotations and no output schema, the description covers side effects, approval gates, and even what gets printed to the user. It is nearly complete; it omits failure/conflict behavior (e.g., what happens if an id is unknown or the working tree is dirty), which is the remaining gap.

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 100%, so the schema already documents ids, base, and branch, including the approval constraint on branch. The description mostly restates the branch constraint rather than adding syntax, ordering, or format detail. Baseline 3 is appropriate when structured fields do the heavy lifting.

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 states a specific verb and resource ("Move outbox drafts into the repo memory dir for review") and enumerates the exact steps of the chain: copy in as proposed, commit locally, move outbox originals out. It is clearly a submit/publish operation. It does not, however, explicitly contrast itself with close siblings like memory_propose or memory_promote, so an agent must infer which tool owns a given draft lifecycle stage.

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 concrete conditions for the risky parameter ("pass branch= only with the user's explicit approval for the full chain") and states what is never done automatically (branch creation, push, PR). This is strong conditional guidance. It stops short of naming an alternative tool to use when the user has not yet drafted or approved, so no explicit sibling routing.

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

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

With no annotations, the description carries the full burden and does disclose the key non-obvious behavior: the old memory is retained with status 'superseded' and retrieval returns the new one. That non-destructive, history-preserving semantic is genuinely valuable. It does not cover error handling for invalid IDs or permission requirements, so it stops short of a 5.

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, zero filler, with the core action front-loaded and the behavioral/routing detail layered after. Every sentence earns its place.

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?

No output schema or annotations exist, but the description compensates by explaining what happens to the superseded memory and what retrieval returns. It omits edge cases such as a nonexistent id and whether tags/type merge or fully override, keeping it just under fully complete.

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 100%, so the schema already documents all five parameters including enum values and defaults. The description adds no per-parameter syntax, merge behavior, or tag semantics beyond what the schema provides, so the baseline of 3 applies.

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?

States a specific verb+resource ('Replace an existing memory with a newer version') and immediately distinguishes the intent from adding, via 'replaced rather than duplicated.' An agent can tell it apart from memory_add and memory_forget without opening a schema.

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?

Explicitly states when to use it ('when a saved fact becomes outdated') and implies the alternative (duplicating via memory_add). It does not name sibling tools outright nor state when NOT to use it, but the triggering condition is clear.

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