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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: entries are impressions rather than verified facts, and rolled-up dates silently fall back to weekly_log, which is a non-obvious behavioral trait. It stops short of describing output shape or pagination.

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?

Five short clauses, none of which waste words, and the core semantics (recent default, weekly label) are front-loaded. The telegraphic style is dense but readable and earns its length.

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 read-only tool with no output schema and a fully documented 3-param schema, the description supplies the missing domain framing (what a diary entry is, its reliability) and the date/week fallback rule. Return format is undescribed, but no output schema exists, so the remaining gap is minor.

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 meaning beyond the schema by explaining how date and week interact (the weekly_log fallback for rolled-up dates) and when to omit each. That is genuine semantics the schema does not carry.

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 ('Read daily_log diary entries') and characterises the content ('impressions, not verified facts'), which separates it from the memory_* siblings that return authoritative memories. It does not explicitly name a sibling alternative, so it stops short of a 5.

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 concrete selection guidance: omit date for today+yesterday, use week for weekly_log, and dates rolled up into weekly_log fall back there. 'Fetch explicitly when needed; do not treat diary as ground truth' sets a usage posture. It lacks explicit when-not/alternative routing to the memory_* tools.

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 annotations declare destructiveHint=true and idempotentHint=true, and the description explains exactly why: upsert-by-term semantics, plus the non-obvious fact that aliases/examples are replaced by what you pass and omitting them clears them. It also discloses literal (non-vector) matching and returns '{ data: glossary row }', adding real behavioral context beyond the annotations.

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 dense sentences with no filler: purpose first, then matching/usage context, then mutation semantics and return shape. Each sentence earns its place and the key constraint (clearing aliases) is stated in the same breath as the upsert behavior.

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 no output schema, the description gives the return shape, covers matching behavior, mutation/upsert semantics, and namespace handling is covered by the schema. 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 description coverage is 100%, so every parameter is already documented, including the 'Replaces any existing aliases/examples' semantics. The description's upsert sentence mostly restates what the schema says, 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?

The description states a precise verb+resource ('Add or update a glossary term') and immediately scopes the resource ('private vocabulary such as nicknames, in-jokes or project names'), which clearly separates it from the memory_* siblings. An agent can identify the tool's job 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 explains where glossary terms surface ('matched literally during memory_recall', 'all included in memory_boot'), which gives useful context on why to set one. However, it never explicitly states when to prefer glossary_set over a sibling like memory_upsert, nor any exclusions or prerequisites, so it stops short of full 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 only declare destructiveHint=true/idempotentHint=true; the description goes well beyond by specifying exactly what is and isn't affected (removed from search/recall, retained in storage and visible via memory_list with status='archived', supersede chain untouched), that un-archiving is impossible, and the exact success and error return shapes. This is unusually rich behavioral disclosure.

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 its effect, then consequence, then alternative-tool guidance, then return shape. Every sentence carries distinct, decision-relevant information with no 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?

For a 2-param mutation tool with no output schema, the description covers effect, irreversibility, persistence behavior, alternative selection, and return/error values. 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% and both parameters (id, namespace) are already documented with examples and defaults in the schema, so the description adds no parameter-level meaning. Baseline 3 applies since the schema does 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?

States a specific verb+resource ('Soft-archive a memory') and immediately defines the semantics: status becomes 'archived', it disappears from search/recall, but the record persists. It also explicitly contrasts itself with the sibling memory_delete, so an agent can differentiate 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 explicit routing guidance: 'Prefer this over memory_delete when the memory might be needed later,' and notes there is no MCP tool to un-archive, which is a decisive constraint for choosing this tool. Both the when-to-use and the irreversible consequence are stated.

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 mark this readOnlyHint=false and idempotentHint=false, and the description correctly explains why: it 'never changes memory content' but 'records that the returned precious entries were shown.' That reconciles the non-read-only flag with a content-preserving side effect, and adds useful caching context ('stable and deterministically ordered so the client can cache it'). It stops short of describing cost, latency, or 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?

Front-loaded with the payload contents, then usage rules, then the side-effect caveat — a logical order with no filler. The first sentence is a long enumeration, but each item listed is genuinely informative rather than 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 carries the return contract itself (the { data: {...} } shape, its constituent sections, and its deterministic ordering). Combined with the usage rule and side-effect disclosure, an agent has everything needed to invoke this correctly once per session.

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?

There is a single optional parameter (namespace) and schema description coverage is 100%, including the default and the fixed-namespace override case. The description adds nothing about it, which is the expected baseline when the schema fully documents the parameter.

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 operation (cold-start context package) and enumerates exactly what it bundles: yesterday's diary log, weekly/monthly summaries, 20 most recent precious entries, glossary terms, and perception items. It is clearly distinguishable from siblings like memory_recall and memory_search, which it explicitly routes around.

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 the when ('call once at session start, not every turn') and names the alternative for the opposite case ('for per-question lookups use memory_recall'). Both the trigger and the explicit exclusion are present, so routing is unambiguous.

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 and idempotentHint=true, but the description adds real context beyond them: irreversibility ('cannot be undone'), the dual removal from storage AND the search index, and failure semantics where an index-removal failure keeps the record. That is the exact behavioral detail an agent needs before a destructive 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 destructive action and its irreversibility, followed by routing alternatives and return shape. No 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?

There is no output schema, so the description supplies the return shape ({ data: { id, deleted: true } }) plus the error case, and covers the destructive semantics, alternatives, and parameters. 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% and both parameters are documented there, including the namespace fallback rule. The description adds essentially no parameter detail beyond 'by id', so the schema carries the full load and 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?

The description states a precise verb+resource+scope: 'Permanently delete one memory by id, removing it from storage and from the search index.' It also names the two adjacent siblings (memory_archive, memory_supersede), letting an agent distinguish it without opening any 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 gives explicit when-not alternatives with the selecting condition for each: use memory_archive to hide while keeping the record, use memory_supersede to replace an outdated fact while keeping history. No inference is required.

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, and the description reinforces this with 'Read-only' while adding real behavioral context: archived/superseded memories are filtered out and the payload can be large. It goes beyond the annotations, though it says nothing about size limits, auth requirements, or truncation risk.

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 core action and scope, then the exclusion rule, then the alternative routing. Every sentence carries distinct information with no repetition.

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 ('one JSON payload' of content plus metadata) and does so, while also covering filtering behavior and where to go for smaller/paged reads. Nothing essential for correct invocation 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%, with the type enum, format enum, and namespace fallback behavior all documented in the schema. The description adds no parameter-level detail beyond what the schema already provides, 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 precise verb+resource ('Export the namespace's active memories ... as one JSON payload') and immediately bounds scope by excluding archived and superseded memories. An agent can distinguish this bulk dump from memory_list/memory_get 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 use context ('for backup or migration') and names alternatives with an explicit condition: 'The result can be large; use memory_list to page or memory_search to look things up.' It lacks an explicit when-not clause (e.g., don't use for single-record retrieval), but the routing intent is clear.

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 'Read-only.' trailer is largely redundant. The description still adds real behavioral context beyond annotations: the exact return shape { data: record } and the 'Memory not found' error outcome for a missing id in the namespace.

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, front-loaded sentences: return value first, then error case, then usage guidance. 'Read-only.' duplicates the readOnlyHint annotation and is the one sentence that does not fully earn 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?

With no output schema, the description correctly compensates by naming the return envelope and the not-found error. Usage ordering and read-only status are also covered, leaving only minor things (e.g. behavior when the namespace is fixed by the API key) to the schema.

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 id and namespace are already documented in the schema (including the fixed-namespace behavior). The description adds meaning for 'id' only indirectly ('in this namespace'), so 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?

States a specific verb and resource ('Fetch one memory by id') plus the payload it returns (full record with lifecycle fields fact_key, version status, superseded_by). The singular 'one memory' contrasts cleanly with the list/search siblings, so an agent can distinguish it 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 specifies when to call it: 'after memory_search, memory_recall or memory_list when you need the complete record before editing.' It names the sibling alternatives and the condition that selects this tool, leaving no inference required.

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 mark this as a non-read-only, non-idempotent write but say nothing about timing. The description discloses the crucial asynchronous behavior (nightly 'dream' pipeline distills messages later) and the return shape, which is well beyond what the annotations convey.

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: purpose first, deferred-processing caveat second, alternative and return value last. Every sentence earns its place with no 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?

Though there is no output schema, the description supplies the return shape ({ conversation_id, message_ids }) and how to use message_ids downstream. The deferred-processing model is explained, so an agent has everything needed to call and reason about the result.

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 parameters (source, messages, namespace, auto_extract, conversation_id) are fully documented by the schema. The description adds no per-parameter meaning, so the baseline 3 applies; the schema does 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?

States a specific verb and resource: 'Store raw chat messages as conversation history.' It also clarifies the deferred nature of the operation and explicitly names memory_upsert as the immediate-save alternative, letting an agent distinguish it from siblings like memory_upsert or memory_search 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?

Explicitly routes the agent: 'To save a fact right away, use memory_upsert,' which gives both the when-to-use and the alternative. It also points to memory_pin as the downstream consumer of message_ids, so the usage flow is fully specified.

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 the 'Read-only' clause adds little. The real added value is behavioral: the deterministic ordering (pinned, then importance, then most recently updated) and the paging contract including next_offset round-tripping, neither of which is derivable from annotations.

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 behavior and ordering, then paging mechanics, then the alternative-tool pointer. Dense but every clause carries information; the only near-redundancy is the trailing 'Read-only', already implied by annotations.

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 disclosing the return shape ({ data, paging: { limit, has_more, next_offset } }) and the offset round-trip, which is what an agent needs to page. Ordering and alternative routing are covered; minor gaps like default page size or namespace binding effects are left to the schema.

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 type, status, offset, cursor, namespace, limit and include_ids in detail. The description only restates type/status filtering and the offset-for-next-page pattern, adding no format or edge-case detail beyond the schema, so baseline 3 is correct.

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 ('Page through stored memories') and adds the exact ordering semantics (pinned, importance, recency) plus optional type/status filtering. It also names sibling tools (memory_search, memory_recall) as the meaning-based alternatives, so an agent can route correctly without opening another 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 tells the agent to use memory_search or memory_recall to find memories by meaning, which cleanly carves out this tool's niche as unfiltered enumeration. It stops short of covering the other read siblings (memory_get, memory_export) or stating when-not to use this tool, so it is clear but not 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?

Goes well beyond the annotations: pinned, surfaced through memory_boot (20 most recent), never deduplicated/decayed/deleted by the automatic pipeline, and each call creates a new entry. This discloses durability and lifecycle behavior that annotations (which only say not read-only, not idempotent) do not convey.

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 dense sentences, front-loaded with the core behavior, then usage guidance, then the alternative tool, then return shape. Every clause carries information; no 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?

For a 3-parameter write tool with no output schema, it covers lifecycle (durable, pinned), discoverability (memory_boot), non-idempotency (new entry each call), and return shape. Nothing essential 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%, so baseline is 3. The description adds meaning beyond the schema by explaining the purpose of context_message_ids (attach surrounding messages) and the self-contained writing requirement for content, though it doesn't expand namespace semantics beyond the schema.

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 (Save/pin) and resource (a moment/precious entry) and distinguishes itself from siblings by naming memory_upsert as the tool for ordinary facts. An agent can tell this apart from memory_upsert or memory_ingest 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?

Explicitly says when to use it vs the alternative: 'For ordinary facts use memory_upsert.' It also gives a usage instruction for the content ('write so it still makes sense on its own later') and the routing via context_message_ids.

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=false and non-idempotent, which is surprising for a 'recall' tool; the description resolves this by explaining it 'marks the returned memories as recently injected, which briefly lowers their rank in later automatic recall' — a genuine side effect beyond structured data. It also states the return shape and that precious entries aren't searched. It does not mention auth namespace binding edge cases, but the side-effect disclosure is the key non-obvious 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?

Four dense sentences front-load the core mechanism and return shape, then handle routing and side effects. No wasted words, though the return-shape enumeration and side-effect clause make it slightly long; every sentence carries distinct 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?

Covers mechanism, return structure, sibling routing, exclusion of precious entries, and the rank-injection side effect — comprehensive for a 6-param tool with no output schema. Minor gap: it doesn't explain namespace versus API-key binding interplay, but that is adequately handled by the schema description.

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 every parameter including k, types, min_score, namespace, and include_history is already documented in the schema with defaults and constraints. The description adds the pipeline context (min_score applied after reranking) but no syntax or format details the schema lacks. Baseline 3 is correct.

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?

Names a specific verb+resource ('recall memories') and details the exact pipeline: literal glossary matching, hybrid search over active memories, reranking, and min_score filtering. This is far more specific than siblings like memory_search, and the explicit 'Prefer this over memory_search when...' clause makes the distinction operational.

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 you want only the relevant memories for the current question') and names the alternative (memory_search). It also carves out the precious-entry exclusion and notes memory_boot as their source, so the agent knows not to expect them here.

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=false, which could mislead an agent into thinking this is a pure read; the description reconciles this by stating 'Never changes memory content; it only updates recall counters.' It also discloses that results are filtered but not reranked and are returned as { data: [...] }. It does not cover pagination, error behavior, or auth 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?

Four tight sentences, zero filler. The core operation is front-loaded, the return shape follows, and the sibling routing plus the mutation caveat come last as qualifications.

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 still specifies the return shape and fields (id, content, type, status, scores) and the { data: [...] } envelope. Between that and the 100%-covered input schema, an agent has everything needed 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 description coverage is 100%, so every parameter (query, top_k, types, namespace) is already documented in the schema. The description restates top_k and the returned fields but adds no syntax, default, or format detail beyond the schema, which is the expected 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 mechanism and resource: 'Hybrid search (vector + keyword) over the user's active long-term memories.' It explicitly scopes the corpus to active memories and distinguishes itself from memory_recall and memory_list, so an agent can route 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 the use case ('find memories you want to inspect or edit by id') and names the concrete alternative with its selecting condition: 'To answer a question with the most relevant, reranked memories plus glossary hits, use memory_recall instead.' Explicit when/when-not/alternative.

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 destructiveHint annotation by disclosing the exact mutation mechanics: the old entry is kept and remains visible via memory_recall with include_history, a new active memory is linked to it, and the fact_key is inherited unless overridden. It also documents the edge case that a missing old_id still creates the new memory with oldStatus 'missing'.

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 behavior and return shape in a compact sequence of sentences with no filler. Slightly dense at five sentences, but each one carries distinct information (mechanism, edge case, alternatives, return).

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 9-parameter destructive mutation tool, the description covers the operation, its side effects on history, the edge case, sibling routing, and the return shape. Nothing an agent needs to invoke it correctly is missing, even without an output schema.

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 baseline is 3, but the description adds genuine meaning: new_fact_key defaults to the old entry's fact_key, and old_id's non-existence yields a 'missing' status rather than failure. These behavioral notes exceed what the schema documents.

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 outdated memory while keeping history') and immediately contrasts it with the sibling tools memory_upsert, memory_archive, and memory_delete. An agent can distinguish it from all siblings 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 fact changed over time') and names the alternatives for adjacent scenarios ('to fix a mistake in place use memory_upsert, and to remove a memory use memory_archive or memory_delete'). No inference required.

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 destructiveHint annotation by stating exactly what is lost ('the old text is not kept'), that matching fact_key overwrites fields in place, and that hand-authored memories outrank distilled ones and resist pipeline overwrites. It even discloses the return shape.

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 the key consequence, and each subsequent sentence carries distinct information (supersede alternative, authored_by behavior, return value). The '(no waiting for the nightly dream)' aside is slightly informal but still informative.

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 an 11-parameter mutation tool with no output schema, the description covers the destructive semantics, the key alternative, the special-parameter behavior, and the response shape. Nothing essential for correct invocation 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 already 100%, so baseline is 3, but the description adds real meaning for authored_by (ranking behavior, pipeline protection) and clarifies the fact_key overwrite contract that the schema only hints at.

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 ('Write a refined memory'), its keying mechanism (fact_key), and its timing semantics versus the nightly distillation pipeline. It is clearly distinguishable from siblings like memory_supersede and memory_ingest.

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 routes the agent: 'To keep the old version as history, use memory_supersede,' and explains the authored_by path for hand-authored memories. It gives a clear context and one named alternative, though it doesn't contrast against memory_ingest or spell out when not to write at all.

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