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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description isn't carrying the safety profile alone. It still adds genuinely new context: default behavior archives rather than deletes, archived memories disappear from recall but remain visible on the admin page, and permanent deletion is irreversible. It does not say whether forgetting a nonexistent id errors or is silently idempotent, which is the one behavioral gap left.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the trigger, then the reversible default, then the irreversible exception, then the return shape. The default-behavior clarification is placed before the dangerous option, which is the right ordering. 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?

No output schema exists, but the description inlines the two possible return shapes (archived vs deleted), so the agent knows what to expect. Combined with annotations covering destructiveness and idempotency, nothing material is missing for a 3-parameter 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 coverage is 100%, so the baseline is 3 and the schema already documents all three parameters. The description goes beyond it by explaining the archive-vs-erase tradeoff behind `permanent` and by stating where the `id` comes from, which is the practical failure mode for this tool.

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 (forget a memory) and immediately scopes it against the sibling family by pointing to recall/list_memories as the id source. An agent can distinguish this from remember, recall, and keep_moment 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?

Gives explicit trigger conditions, including user phrasings in two languages, and a second condition ("when it turns out to be wrong"). It also draws the when-not line for the destructive path: pass permanent: true only when they clearly want it erased.

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=false, destructiveHint=false, and idempotentHint=false, and the description adds context beyond them: kept moments are never merged, faded, or deleted automatically, the 20 most recent surface on every `wake_up`, and each call creates a new entry (reinforcing non-idempotency). It also states the return shape, `{ data: moment }`, which no output schema provides.

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 sentences with distinct jobs: what it is, durability guarantees and wake_up surfacing, sibling routing, non-idempotency, return shape. The purpose is front-loaded and nothing is repeated from structured fields verbatim.

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 three-parameter, single-required-field write tool with no output schema, the description covers purpose, retention semantics, wake_up interaction, idempotency, sibling routing, and the return object. An agent can call it correctly and predict the consequences without further inference.

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 three parameters — content, namespace, context_message_ids — are already documented in the schema. The description reinforces the spirit of `content` ('in the person's own words') but adds no new syntax, defaults, or constraints for `namespace` or `context_message_ids`. Baseline 3 applies when the schema carries the parameter burden.

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 concrete verb and resource — keeping a moment in the person's own words — and illustrates the category with examples (a first time, a promise, a confession). It explicitly contrasts with the sibling `remember` for ordinary facts, so an agent can distinguish 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 routing rule: 'Use remember for ordinary facts and this for the moments themselves.' That is a named alternative plus the condition that selects it, which is exactly what the sibling tools (`remember`, `recall`, `list_memories`) make necessary.

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 destructiveHint=true and idempotentHint=true, and the description earns credit by explaining exactly what is destructive: re-calling with the same term updates meaning, and aliases/examples are replaced by what you pass, with omission clearing them. It also discloses the return shape ('Returns { data: word }'), which is needed since no output schema exists.

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 identity of the tool, then scope, then update semantics, then return value. Four sentences, no filler, and the parenthetical clarifications are load-bearing rather than decorative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter mutation tool with no output schema, the description covers what the tool is, how re-invocation behaves, what gets overwritten, how the data is later retrieved, and what comes back. Nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine nuance beyond the schema: that leaving aliases/examples out clears them, which turns an optional field into a destructive default. It adds nothing extra about namespace scoping, which is left entirely to 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 and resource ('Learn a private word') and immediately disambiguates with concrete examples (nickname, pet name, in-joke, project name) that distinguish it from generic memory tools like remember. It also names the siblings it interacts with (recall, wake_up), so the agent can place it in the toolset 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?

Gives clear operational context: learned words are matched literally in recall and surfaced at wake_up, which tells the agent where this tool fits in the workflow. It does not explicitly contrast against remember or list_memories (e.g. 'use this instead of remember for private vocabulary'), so the routing guidance is strong 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description stays consistent with that ('Read-only'). It adds real value beyond the annotations: the result ordering ('most important first'), the exact return envelope ({ data, paging: { limit, has_more, next_offset } }), and the pagination contract for continuing. It stops short of disclosing which statuses are included by default or what happens to archived/superseded entries, which is left entirely to the schema.

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 and trigger first, the disambiguation second, the return/pagination contract last. Nothing is repeated except the 'Read-only' phrase, which is a single word.

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 compensates by naming the exact return shape and paging fields, and explains how to continue paging. Combined with a fully documented 5-parameter schema and read-only annotations, an agent has everything needed to call this 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 including type, limit, offset, status and namespace is already documented in the schema, establishing a baseline of 3. The description's only parameter-adjacent guidance ('pass next_offset back as offset') duplicates what the offset schema field already says, so it adds no new semantic detail.

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 everything you remember') plus the ordering guarantee ('most important first'), and explicitly names the sibling it is not ('To find something specific, use recall'). An agent can distinguish it from recall/notebook/read_diary 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?

Gives concrete triggering situations ('when the person asks what you know about them (你都记得我什么)' or 'wants to look through or tidy their memories') and names the alternative tool with the condition that selects it. Both when-to-use and when-not-to-use are present.

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 by explaining why the call is needed (direct-to-model clients record nothing), that already-sent lines are skipped, and that the returned conversation_id must be passed back to enable that dedup. It also states the return shape, which no output schema provides. This is behavioral context the readOnly/idempotent hints cannot 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?

Front-loads the purpose and keeps the operational rules (timing, trimming, dedup, skip condition) tight and scannable. The opening framing about diaries and memories is slightly conversational, but no sentence is genuinely wasted.

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 everything an agent needs: motivation, timing, exclusion, alternative tool, payload hygiene, dedup protocol, and the exact return fields, compensating for the absent output schema. Nothing material is missing for a 3-parameter write 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 coverage is 100%, so baseline is 3, but the description adds real semantics: messages must be ordered oldest-first, trimmed of code and pasted documents, and conversation_id must be carried forward from the first call. Only `namespace` is left entirely to 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 concrete action (hand the conversation to the nightly memory pass so it becomes diary memories) rather than restating the name. It also distinguishes itself from the sibling `remember` by contrasting deferred logging with immediate recall, so an agent can pick between them 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 explicit timing (when the conversation winds down, every ~20 exchanges in a long one), an explicit exclusion (skip it when the Aelios gateway auto-adds memories each turn), and an explicit alternative (`remember` for anything that matters right now). Both when and when-not are covered.

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: write replaces and creates-if-needed, append adds at the end, delete is permanent-by-implication but pages never expire or change on their own, plus hard limits (50 pages, 20000 chars). The read-before-rewrite warning mitigates the destructiveHint=true profile rather than contradicting it.

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, then a compact action glossary, then guardrails and limits — dense and useful throughout. Minor waste: the action list largely duplicates the action enum description verbatim, and 'Returns { data }' is thin.

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 4-parameter mutation tool with no output schema, the description covers lifecycle, capacity, and safety guidance well. The return value is only gestured at as '{ data }', leaving the agent to infer the response shape after list/read.

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 already 100%, so the baseline is 3; the description earns above that by spelling out action semantics that go beyond the enum labels — 'write replaces a whole page, creating it if needed' and 'append adds a line at the end.' It does not address the namespace parameter, which is left entirely to 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 resource ('named pages you read and rewrite yourself') and its intended content ('running notes such as progress on a long task'), then enumerates every action in one sentence. This is clearly a self-managed notebook, distinguishable from sibling memory tools like remember/recall/keep_moment.

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 operating discipline: 'Read a page before you rewrite it' and 'delete one when it is done.' The line 'Pages are never recalled automatically' implicitly positions it against auto-surfacing memory tools, but no sibling is named as an explicit alternative, so this stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description goes beyond by warning that entries are overnight impressions, not verified facts, and by stating the return shape ({ data }, null when absent). The only shortfall is that the memory_id fallback chain (original messages vs. day diary vs. week diary) is described loosely enough to leave the exact resolution order slightly ambiguous.

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 usage trigger is front-loaded and each sentence carries information (scope, defaults, reliability caveat, alternate mode, return shape). The memory_id sentence is a long triple-branch clause that costs some readability, keeping it just below top marks.

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 discloses the return envelope and the null case, plus the reliability caveat an agent needs before quoting entries as fact. For a 4-parameter, all-optional read tool this covers 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 coverage is 100%, so baseline is 3, but the description adds real semantics the schema does not: omitting both date and week defaults to today plus yesterday, and memory_id switches the tool from diary retrieval to provenance lookup. The namespace parameter is left entirely to the schema, which is acceptable given its self-explanatory description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Read your diary") and immediately bounds the scope: a single day, a week, or the default today/yesterday. It distinguishes itself from siblings by naming recall as the tool for verifying details and explaining that memory_id redirects to provenance lookup rather than a day's entry.

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?

Explicit trigger is given ("when the person asks what happened on a certain day or during a stretch of time"), with multilingual cues. It also prescribes parameter selection: date for one day, week for a week, neither for today and yesterday, and memory_id as the alternate mode — that is when-to-use plus alternatives in one pass.

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 readOnlyHint annotation, the description discloses the exact return shape ({ data: { hits, glossary_hits, week_blocks, meta } }) and an important non-obvious side effect: it changes no memory but notes which ones were recalled, preventing expiration. That is precisely the behavioral context an agent needs.

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 front-loaded with the trigger conditions, then the return shape, then the behavioral note. Despite being dense, every sentence earns its place by covering usage, output, and side effects without 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?

For a retrieval tool with no output schema, the description fully covers what it returns, when to call it, and its non-mutating but recency-affecting behavior. Nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all six parameters thoroughly. The description adds context about output ids and their downstream use with remember/forget, but it does not add parameter-level meaning beyond what the schema provides, making the baseline 3 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 description states a specific retrieval action ('Look things up') over a specific resource ('memories') and clarifies the output is the most relevant memories with ids. It also distinguishes its role from mutating siblings by explaining ids are passed to remember's replaces or forget.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives unusually clear triggering conditions: when the person references anything from before, with concrete examples and multilingual cues, plus when the agent is about to guess or ask something it may already know. It adds a strong 'Never say you don't remember before calling it' rule, but does not explicitly distinguish when to use this versus list_memories or state exclusions.

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 the write profile (readOnly=false, destructive=false, idempotent=false); the description adds the important non-obvious behavior — superseded memories are kept as history rather than overwritten — and predicts the response shape. It does not address duplicate handling, which matters given idempotentHint=false.

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 primary imperative ('Save something the moment it comes up'), then qualification list, then mechanics. Slightly dense — the middle list of worth-saving categories is long — but every clause carries instruction the agent needs.

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, yet the description supplies the return shape ({ data: { id, created, replaced } }), which closes the main completeness gap. Combined with usage rules and the replacement semantics, an agent has everything needed to invoke this correctly on the first try.

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 still adds value by explaining the replaces workflow end-to-end (take the id from recall, new version takes over, old kept as history) and by giving durability guidance for content ('still make sense months from now'). It says nothing about confidence, importance, tags, or fact_key, which the schema alone must 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 concrete verb and output ('save something', 'write one self-contained sentence') and immediately scopes it to durable personal facts rather than chatter. Clearly separable from siblings like log_conversation and recall, which it names by implication ('the nightly pass', 'id from recall').

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?

Explicit timing guidance ('the moment it comes up; don't wait to be asked'), an enumerated list of what qualifies, an explicit exclusion ('Skip small talk; the nightly pass picks that up from logged conversations'), and the exact condition for choosing replaces over a plain save.

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 'Read-only' while adding real value: the exact contents loaded and a once-per-conversation constraint. It does not describe size/verbosity of the payload (e.g., whether summaries are truncated), so it stops short of full 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 imperative call-order instruction and frequency cap, then the payload contents. The final return-shape sentence is long but functional; only minor trimming would be possible without losing 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 enumerating the returned data keys (how_to_use, core, impressions, precious, glossary, notebook) and conditionally describing notebook. Combined with annotations and full schema coverage, 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% and the single namespace parameter is fully documented in the schema, so the baseline of 3 applies. The description never mentions namespace or the fixed-namespace override, adding nothing 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 concrete verb (call first) and resource (the memory context: core memories, diary, summaries, notebook pages) so an agent knows exactly what it retrieves. It also distinguishes itself from siblings by promising a note on when to use the other memory tools, a role no sibling name implies.

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?

Explicit ordering guidance: 'Call this first in every new conversation, before your first reply, even if the person only says hi,' plus the frequency constraint 'Once per conversation is enough.' That removes the main ambiguity (whether to call when the user's message looks trivial) and names the alternative path via the how_to_use note.

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