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 clearly states that archive is recoverable, deprecate preserves the memory for opt-in reads, and purge is the only irreversible deletion (subject to git history as a backstop). It also emphasizes 'never silent deletion,' setting expectations that all state changes are explicit. It does not cover error handling or idempotency, but the key behaviors are disclosed well.

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 sentence organized by mode with colons and semicolons. Each mode's effect and prerequisites are front-loaded, with no filler. The nuclear phrase 'never silent deletion' in the title signals non-obviousness, and every clause earns its place. It is concise yet fully informative, ideal for quick agent parsing.

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 5 parameters, an enum, and no output schema, the description covers the mode semantics, prerequisites, and recovery guarantees. It does not detail the return format (irrelevant without an output schema) or mention error conditions, but it fully equips an agent to invoke the tool correctly per the described behavior. Minor gaps like id format or store path patterns are not critical to judging correctness of the call.

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 60% (store, reason, and confirm have descriptions, id and mode do not descriptively). The description adds substantial meaning: it explains what each mode means and the conditional requirements (reason required for deprecate, confirm must be true for purge). This goes beyond the schema, which merely provides enum values and defaults. The id parameter's meaning is left implicit, but since it's the only required field and the tool's purpose centers on existing memories, the omission is minor.

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 title 'Forget (state transition, never silent deletion)' prefaces the tool as a state transition rather than a deletion, and the description enumerates three distinct modes (archive, deprecate, purge) with clear effects. This precisely distinguishes it from siblings like memory_update (which would modify content) and memory_recall (which reads), so an agent can immediately understand what this tool does and how it differs from other memory operations.

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 usage scenarios for each mode: archive for recoverable removal from default recall, deprecate for judged-wrong memories with a required reason, and purge as the only true deletion, restricted to archived/deprecated states with confirm=true. It does not explicitly name sibling tools as alternatives, but the mode-specific guidance makes the when-to-use decision clear. Missing an explicit 'do not use for simple edits' pointer, but the context is implicit.

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 bears full responsibility for disclosing behavior. It does specify what is returned (full content and provenance), which is useful. However, it does not state that the operation is non-destructive or read-only, nor does it note any permission requirements or error conditions. The description adds some behavioral context but omits explicit safety or side-effect disclosures.

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 succinct: one clause listing key provenance elements. It is front-loaded with 'Full content plus provenance' and avoids redundancy. Though terse, it conveys the essential information efficiently and earns a high score.

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 simple read tool with three optional parameters and no output schema, the description adequately explains the return value (full content and provenance details). It does not include usage guidance or alternatives, but that is covered under usage guidelines. The tool's functionality is sufficiently described for an agent to call it 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 descriptions cover all three parameters (id, path, store) with clear meanings, so baseline is 3. The description does not add parameter-specific semantics beyond what the schema already provides, so it remains at 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?

The description 'Full content plus provenance: frontmatter, supersede chain in both directions, conflicts, usage' clearly indicates the tool returns the full content and metadata of a memory, implying a read operation. It distinguishes from memory_recall by emphasizing provenance details, though it lacks an explicit verb like 'read' or 'retrieve'. This is more than a tautology and conveys the core function.

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?

No guidance is provided on when to use this tool versus siblings like memory_recall or memory_status. The description does not state 'use this to read a specific memory by id/path' or mention alternatives for searching. The agent must infer usage from the name and schema alone.

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. It discloses the ranking formula (text * trust * state * (1 + freshness + heat)) and notes that old unused memories sink but never vanish, revealing decay behavior. It also states 'nothing is auto-injected,' implying no side effects on memory content, which adds transparency about its read-only nature.

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 concise and front-loaded, opening with the core search functionality before explaining the ranking details. The two sentences are dense but purposeful, though the ranking formula might be clearer if separated, and no unnecessary words are present.

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 7 parameters, no output schema, and no annotations, the description is insufficient for an agent to fully understand how to use all parameters. It explains the return type and ranking but omits details on filters like types, include_archived, and include_deprecated, and does not describe output fields or pagination. This is a notable gap for a complex search tool.

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 only 43%, leaving limit, types, include_archived, and include_deprecated undocumented in the schema. The tool description does not clarify these parameters, nor does it explain how the ranking formula maps to specific inputs like entities or types. It adds some context about ranking but fails to compensate for the low coverage.

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 states the tool performs a hybrid lexical search (word/trigram FTS + CJK-aware fallbacks) and explicitly mentions it returns paths, excerpts, and score components. It differentiates itself from memory_read by noting that full content must be read via that tool, and from other siblings by focusing on search rather than writing or management.

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 provides clear guidance to use memory_read for full content, implying this tool returns only excerpts and paths, and that nothing is auto-injected. It does not explicitly mention when not to use it versus other siblings like memory_reindex or memory_status, but the contrast with memory_read is a useful usage signal.

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 thoroughly. It explicitly reveals that rebuild drops all derivatives (destructive) and reconstructs from originals, clarifying that only usage heat is lost. Verify is disclosed as a non-destructive full re-hash audit that ignores the stat gate and reports drift—clear about side effects and 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?

The description is compact and front-loaded: it opens with the default mode, then succinctly explains the alternative. Each clause earns its place with no filler, and the structure (rebuild vs. verify) aids quick parsing.

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-param tool with no output schema, the description covers all essential aspects: both modes, their side effects, the source of truth (originals), and what verify reports. It is sufficient for an agent to call the tool correctly without additional external knowledge.

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% (store is described, verify is not), but the description compensates by explaining the verify mode and its behavior. It adds meaning to the verify boolean beyond the schema, while store's description is already provided. The description effectively fills the schema 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 description clearly specifies two distinct operations (rebuild and verify) with specific resources (memory files, index/derivatives) and explicit outcomes. It distinguishes itself from siblings by focusing on reindexing and auditing rather than memory operations like remember/recall, making its purpose unambiguous.

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 contextual usage guidance (rebuild for disaster recovery, verify for drift detection) but does not explicitly state when to avoid or prefer other tools. The 'disaster recovery' phrase implies appropriate timing, yet no explicit exclusions or alternative tool mentions exist.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure — and it excels. It reveals three critical behaviors: no automatic overwriting, a conflict-return contract requiring caller judgment, and idempotent behavior for identical content. These are exactly the traits an agent needs to know before calling.

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 sentence that is informative and front-loaded with the core purpose, but it packs several concepts (conflict material, judgment options, idempotency, no-overwrite guarantee) into em-dash clauses. A structured list would improve scanability without lengthening content.

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 8 parameters, 88% schema coverage, and no output schema, the description compensates well by explaining the return value (possible_conflicts with judgment material) and the caller-decision workflow. It also covers idempotency and the no-overwrite guarantee, leaving an agent fully equipped to call it 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 88%, so parameters like type, trust, source, and supersedes are already well-documented in the schema. The description adds the 'first heading becomes the title' nuance for content and implies the conflict semantics for supersedes/superseded_by, but doesn't systematically enrich each parameter. Baseline 3 is appropriate given the high schema coverage.

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 (create), resource (memory as markdown original + derived index), and the distinctive mechanism (returns possible_conflicts for judgment). Among siblings like memory_read, memory_update, and memory_forget, the creation purpose is unmistakable without opening the 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 clarifies that nothing is overwritten automatically and that the caller must judge conflicts (supersede, keep both, or correct). Idempotency for identical content is also stated. It doesn't explicitly say when not to use it vs siblings, but the creation role plus the judgment-caller contract provides clear context.

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 burden of behavioral disclosure. It lists the contents of the status, which implies it is a read-only operation, but does not explicitly state side effects, performance implications, or whether it affects any state. It adds useful information about what the tool reports, but omits details like whether it reads from cached data or performs live aggregation.

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 but dense sentence, using a colon to separate the metaphor from the list. It is concise, but the metaphor 'honesty surface' is not immediately intuitive and could mislead. The list is long and runs together, making parsing slightly harder. Overall it is compact but not optimally structured.

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 status tool with no output schema, the description provides a useful enumeration of the kinds of information returned. However, it does not clarify the format of the output (e.g., JSON, text) or any specific caveats (e.g., whether counts are live or cached). Given the complexity of the underlying memory system, more detail on how to interpret the status would improve completeness.

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 single optional parameter 'store' is fully described in the schema (100% coverage), so the description does not need to add anything. It correctly does not repeat schema information. The baseline of 3 is appropriate because the schema already documents the parameter adequately.

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 indicates this is a status/overview tool by listing the specific categories of information it exposes (counts by state/type/trust, pending conflict judgments, etc.). The metaphor 'honesty surface' is unusual but the enumerated list makes the purpose evident. It is distinguishable from sibling tools like memory_update or memory_forget, which are clearly mutations.

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?

No guidance is given on when to use this tool versus alternatives. There is no mention of typical use cases (e.g., checking system health, troubleshooting) or when not to use it. The description simply states what it shows, leaving the agent to infer usage from the name and siblings.

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 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.