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

Annotations only declare readOnly=false, destructive=false, openWorld=false. The description goes well beyond that: idempotent dedup behavior (an identical fact returns the existing id), the return value, default scope semantics, alias indexing behavior (max 4, silently dropped extras), and a no-retry rule for verbatim-stored content. Rich behavioral context the annotations cannot carry.

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 is front-loaded and most sentences earn their place, but the definition is dense and the clause about content 'already stored verbatim this turn' is convoluted enough to slow an agent down. Slightly long, though not padded.

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?

Despite having no output schema, the description states what is returned (the new memory's id, or the existing id on a duplicate), covers scope selection, the propose-on-approval rule for inferences, and alias handling. Nothing an agent needs to call this 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?

Schema description coverage is 100%, so all six parameters are already documented, including the scope and aliases semantics. The description reinforces the scope default and alias attachment but adds little syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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 sentence states a specific verb and resource ('Save a fact, preference, decision, or note to persistent local memory') and even enumerates the kinds of content it stores. It also differentiates from a sibling by naming memory_supersede for the verbatim-duplicate case.

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 says when to use it ('PROACTIVELY whenever the user shares something worth remembering'), when not to ('one-off task details or anything re-derivable from the code'), the propose-first condition for inferred facts, and routes the duplicate case to memory_supersede. This is about as complete 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?

Annotations already declare destructiveHint=true, but the description adds materially more: deletion is permanent, the agent must restate content and obtain confirmation first, and soft=true produces a one-way retraction (out of lists/search, file retained, not reversible without re-saving). These are workflow and irreversibility details annotations cannot express.

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?

Four sentences, front-loaded with the core action, then the sibling routing, then the safety workflow, then the soft-mode variant. Every sentence carries distinct, non-redundant information.

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 2-parameter destructive tool with no output schema, the description covers action, alternative, irreversibility, a required confirmation step, and the soft-retraction variant. Nothing an agent needs in order to call 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% (the `id` param has no schema description), so the description carries part of the burden; it does explain `soft` semantics in prose (hidden, retracted, file kept, one-way). The `id` parameter itself gets no format or sourcing detail, so it doesn't fully compensate 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 and resource ("Delete a memory by id") and explicitly distinguishes itself from the nearest sibling, memory_supersede, which handles the replace-not-delete case. An agent can route between the two without opening either 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?

Gives an explicit trigger ("Use when the user asks to forget something") plus the alternative and the condition that selects it ("To replace an outdated fact with a corrected one instead of deleting it, use memory_supersede"). It also advises offering soft mode when the user is unsure, which is real routing 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?

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description does not contradict them. It adds genuinely non-obvious behavioral context beyond the annotations: entry numbers are ephemeral to the last listing, and the default now hides superseded versions. It stops short of describing volume/performance characteristics, but with annotations covering the safety profile this is a solid contribution.

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 action and output format, then moves to presentation and deletion-safety rules. The quoted phrasing guidance ('source=user → "you told me this"') is chatty and slightly crowds out tool behavior, but each sentence carries actionable instruction rather than 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?

With no output schema, the description carries the burden of describing the return value, and it does: a numbered inventory with per-line raw fields and an explanation of what each source value means. Combined with the include=all audit behavior and the deletion safety loop, an agent has everything needed to call and interpret this tool correctly.

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 usage-conditional meaning the schema lacks: scope=both is the right setting for recall-style questions, and include=all is framed as 'the audit view'. The type and limit mentions largely restate the schema, so the gain is real but partial.

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 and resource ('List memories in a scope, newest first, as a numbered inventory') and even specifies the output shape, so an agent knows exactly what it gets. It does not explicitly distinguish itself from memory_search or memory_status, so sibling differentiation is only implied by 'inventory' vs. a search tool.

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 explicit triggering conditions ('When the user asks "what do you remember about me?", use scope=both'), names the audit-view condition for include=all, and routes to memory_forget with a required re-list-and-confirm precondition. It also warns that numbers are only valid for the most recent listing, which is exactly the kind of usage constraint an agent would otherwise get wrong.

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?

Beyond the annotations (which only declare this is a non-read-only, non-destructive mutation), the description discloses meaningful behavior: exactly one step per call, error on unknown id or already-published memory, and the key non-obvious guarantee that rejected memories are never deleted and can be revised/resubmitted. It also explains the reviewer-override semantics of `by`.

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 action and state ladder, then supporting constraints. Every sentence carries information, though the trailing parenthetical about MCP server / CLI / plugin surfaces is meta-info that slightly dilutes 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 5-parameter mutation tool with no output schema, the description covers the transition, reject path, error conditions, and resubmission well. It omits what a successful call returns (e.g. the memory at its new state) and any permission/authorization requirements, which would round it out.

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 intent beyond the terse schema strings: it explains why `by` exists (recording a reviewer that differs from the default, e.g. approving on another's review) and ties reject+note and resubmission behavior to the relevant flags.

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 (advance/promote) and resource (project memory) plus the exact state transition (proposed → approved → published). It also names the sibling that handles the adjacent case (memory_submit for brand-new drafts), so an agent can distinguish it from siblings without opening schemas.

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 when-to-use context (advancing a memory one rung, or rejecting with a note) and explicitly routes the new-draft case to memory_submit. It does not, however, address relationships to other review-lifecycle siblings like memory_propose or memory_resolve, so the alternative coverage is partial rather than exhaustive.

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 already declare destructiveHint=false and readOnlyHint=false, so the write-but-safe profile is covered. The description adds real value on top: it clarifies that this is a copy (originals remain) rather than a move, and discloses surface availability (MCP server and CLI, not the opencode native plugin). It does not describe the resulting draft state in detail, keeping 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?

Front-loaded with the core action, then the usage rule, then the alternative routing, all in three compact sentences. The trailing parenthetical on server/CLI availability is useful but slightly tangential; nothing is redundant.

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 non-destructive write tool with full schema coverage and no output schema, the description covers action, safety semantics, lifecycle position, and environment availability. Minor gaps remain about what a draft looks like and where the outbox lives, but nothing needed to invoke 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?

Schema coverage is 100%, including a description for localApprove, so the schema carries both parameters fully. The description adds no syntax or format detail beyond what the schema provides (the word 'copy' loosely implies ids), so the baseline 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?

Specific verb and resource: 'Copy personal memories into the project outbox as review drafts,' plus the clarifying clause that originals stay put. It explicitly distinguishes itself from memory_submit (moves drafts into the repo) and memory_promote (advances drafts already there), so an agent can route between the three without opening schemas.

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?

States the selecting condition explicitly ('Use this when personal knowledge should enter a project's review flow') and names the two adjacent alternatives with their distinct roles. This is a complete when/when-not map for the promote/submit/propose cluster.

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?

Goes well beyond the annotations: it discloses that the default report mode is a no-op, that apply=true writes only to local files, and that even then no push occurs — an important blast-radius limit that openWorldHint=false/destructiveHint=false cannot express. readOnlyHint=false is consistent with the documented apply=true write path, so there is no contradiction; the only gap is upstream behavior such as missing-PR or auth handling.

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 purpose and then the mode semantics before the parenthetical deployment note. It is dense but largely earns its length; the trailing note about the MCP server/CLI/native plugin is tangential to invoking the tool and is the one part that dilutes 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 single-param tool with no output schema, it covers the essential invocation semantics: what is read, how state maps, and when writes happen. The only shortfall is that the shape of the 'report' output is never sketched, leaving the agent to infer what the default mode returns.

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?

Only one parameter and schema coverage is 100%, so the schema already documents 'apply' fully. The description reinforces the default and adds the 'still no push' nuance, but adds little syntax or meaning beyond the schema, so the baseline 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 and resource ('read the current branch's GitHub PR and map its review state onto each in-repo memory') and then spells out the exact mapping rules (merged → published, approval → approved, changes-requested → suggestion). The mapping semantics make it immediately distinguishable from the plain memory_* siblings, which none of them do.

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 clarifies the two modes ('report by default; apply=true writes'), which is genuine usage guidance for the one parameter. However, it never names when to prefer this over siblings like memory_promote or memory_status, which also touch memory state, so the agent must infer the routing itself.

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?

Adds substantial context beyond the annotations: the merge is field-level 3-way, semantic conflicts are reported and never auto-resolved, the merged file is written in place, and recovery is via git. The write-in-place behavior is consistent with readOnlyHint=false and destructiveHint=false (reversible, undoable). It also discloses environment availability (MCP server and CLI, not the opencode native plugin), which annotations cannot express.

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 two modes, then trigger, then alternative, then availability. Nearly every sentence earns its place, though the trailing parenthetical about server/CLI/plugin exposure reads as a footnote and slightly dilutes the core instruction.

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?

There is no output schema, but the description covers both operational modes, the non-auto-resolution policy for semantic conflicts, the in-place write and its undo path, the sibling alternative, and runtime availability. Nothing an agent needs to invoke this 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?

Schema coverage is 100% and the schema already states "Omit to list conflicts," so the baseline is 3. The description adds the mode semantics behind each branch — omitting lists conflicted files, supplying a target attempts a merge — which clarifies the parameter's effect rather than just its type.

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 two specific verbs on one resource (list git-conflicted memory files; attempt a field-level 3-way merge of one), and the branch condition is tied to the single `target` parameter. It explicitly names memory_pr_status as the sibling for a different conflict domain, so an agent can route without opening either 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?

Gives an explicit trigger ("Run it when a git pull or merge leaves memory files conflicted") plus an explicit exclusion and alternative ("For PR review state rather than file conflicts, use memory_pr_status"). Both when-to-use and when-not-to-use are stated outright.

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 already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: results are ranked by BM25 within review tiers and reviewed (approved/published) project memories come first, plus the default result cap of 8. It does not discuss latency or result volume beyond the limit.

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 purpose and return behavior, then usage and search strategy. Every sentence is functional, though the search-strategy sentence is dense and could be tightened slightly without losing meaning.

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?

Covers scope of results, absence of output schema is compensated by 'Returns matching memories,' and ranking/default behavior is explained. An agent has everything needed to decide to call it and to call it well.

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. The description adds meaning beyond the schema by explaining how to phrase the `query` effectively (concepts, synonyms, shorter keyword forms) and reiterating the `limit` default and `type` restriction 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?

States a specific verb and resource (search persistent memory) and the retrieval method (BM25 full-text). It also scopes results to 'current project and/or personal scope,' which lets an agent separate it from memory_list or 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?

Gives a clear trigger condition: call before asking the user about past decisions, conventions, or preferences. Adds concrete search strategy (break into concepts, try 2-3 phrasings, check the other scope). It does not name which sibling to use instead when memory is absent, so it stops short of the top tier.

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 declare readOnlyHint=true and openWorldHint=false, so the safe-read profile is already covered; the description adds genuinely useful context beyond that — next-step workflow and deployment scope (MCP server and CLI expose it, the opencode native plugin does not). It stops short of describing output shape or any rate/limit behavior, but for a zero-param status read that is a minor gap.

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 shows, then triggers, then alternatives. Dense but every sentence carries routing or behavioral value; the trailing parenthetical about which surfaces expose the tool is the only slightly expendable part, though it does prevent an agent from hallucinating availability.

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 parameters and no output schema, the description carries the burden of explaining what comes back, and it does by enumerating the three pipeline categories and the required follow-up (ask which drafts to sync). Complete enough to call correctly, though it could note whether the result is grouped or how to interpret an empty pipeline.

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 no parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. No misleading or missing parameter guidance.

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 ('Show the project memory sync pipeline') and enumerates exactly what it surfaces: outbox drafts, repo memories awaiting review or published, and uncommitted repo files. This is clearly distinguishable from the siblings that manage memories rather than report pipeline 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?

Gives explicit trigger conditions (session start, when the server reports drafts awaiting review, when the user says 'sync memory'/'同步记忆') and names the alternatives for adjacent needs: memory_list for the memories themselves and memory_pr_status for PR review state. It even specifies the follow-up action (ask the user which drafts to sync).

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 the flat safety flags; the description adds substantive behavior: local commit on the current branch, moving outbox originals out, aborting with a reason on unknown ids or failed commit, and no automatic publishing. This is rich disclosure well beyond structured fields.

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 action and tightly packed, though the parenthetical about MCP/CLI/opencode scope and the approval caveats make it longer than strictly necessary. Every sentence still carries useful information.

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 compensates by explaining what gets printed (push and PR commands) and the failure modes. For a multi-step mutation tool it covers everything an agent needs to call it safely.

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 schema already documents ids, base, and branch (including the branch-approval caveat), making 3 the baseline. The description reinforces the approval semantics but adds no syntax or format detail the schema lacks.

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 opens with a specific verb+resource — moving outbox drafts into the repo memory dir — and enumerates the exact chain (copy in, commit locally, move originals out). An agent can distinguish this submit operation from sibling tools like memory_propose or memory_promote 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?

It states explicit when/when-not conditions: pass branch= only with the user's explicit approval for the full chain, never auto-create branches, and push/PR commands require explicit approval and are never run automatically. It even notes the tool is exposed via MCP/CLI but not the opencode plugin.

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?

Goes well beyond the annotations: it discloses the non-destructive history model (status: superseded), retrieval precedence, the active-only precondition, field inheritance for type/tags/aliases with override behavior, and failure semantics (unknown id reported as failure, nothing written). The destructiveHint=false annotation is corroborated rather than merely repeated.

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?

Four short sentences, each carrying distinct information: purpose, when-to-use, precondition plus inheritance, and failure behavior. Nothing is redundant and the primary purpose is front-loaded.

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, and the description covers failure behavior and history retention but does not state what a successful call returns (e.g., the new memory's id or status). For a mutation tool that is a small but real gap rather than a serious omission.

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 inheritance semantics the schema does not spell out: the new memory inherits type, tags, and aliases unless replacements are passed. It doesn't clarify the aliases cap or indexing behavior beyond the schema text, so it stops short of a 5.

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 and resource (replace an existing memory) plus a distinct scope: the old memory is retained as history while retrieval returns the new one. It explicitly contrasts with the duplication route (memory_add) via 'replaced rather than duplicated', letting an agent separate it from siblings without opening schemas.

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 a clear condition for use ('when a saved fact becomes outdated and should be replaced rather than duplicated') and a precondition ('only active memories can be superseded'). It implies memory_add is the alternative but never names it or states when replacement should be avoided, so no explicit when-not rule.

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