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

With no annotations, the description carries the full burden and does well: it discloses that the default path may NOT create a record at all, applies a 90% similarity / substring containment threshold, preserves the original timestamp, and unions tags. These are non-obvious side effects an agent could not infer from the schema. It omits error/failure behavior and file-locking concerns, keeping it below 5.

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

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

The purpose is front-loaded in the first clause, then the non-default behavior follows. Roughly three sentences with no filler; the parenthetical about timestamp and tag union is dense but earns its place.

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

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

For a mutating append tool with no annotations and an output schema available, the description covers the one genuinely surprising behavior (silent consolidation) and the escape hatch. Return values need not be explained since an output schema exists; only edge-case failure modes are unaddressed.

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 0%, so the description must compensate. It genuinely adds value for 'merge' (spelling out what merging does and how to opt out) and restates that tags is an optional label list, but the required 'text' parameter is never characterized in either place. Partial compensation justifies a middling score.

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 (JOURNAL.jsonl 事件记录) with the exact target file, which is concrete and actionable. It does not distinguish itself from the sibling 'memory_update', so an agent must infer the append-vs-update boundary from the name alone.

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 clearly defines the two modes (default consolidation vs merge=False forcing a new entry), which is usable guidance for choosing parameter values. However, it never says when this tool should be chosen over memory_update or memory_search, and no conditions for avoiding the tool are given.

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

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

With no annotations, the description carries the full burden, and it does disclose useful behavior: the default filename, that FACT.archive.md is the archived copy, the precedence rule between tail and offset/limit, and the token-cost trade-off of line-based reads. Gaps remain: it doesn't say what happens when the file doesn't exist or the filename is invalid, and no permissions/rate-limit context.

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 verb and resource, then the mode selection logic; every clause adds information (defaults, allowed values, precedence, token saving). No filler sentences.

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?

An output schema exists, so return-value explanation is not required, and the description plus schema cover invocation completely for a read-only tool. The only real omission is error behavior for missing/invalid filenames, which is minor given the tool's simplicity.

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 0%, so the description must compensate fully, and it does: filename default and allowed values, tail semantics ('last tail lines'), offset's 1-based origin, limit's max-lines meaning, the tail>offset>limit precedence, and the fallback to a full read when none are given. All four parameters get meaning that the bare schema lacks.

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

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

The first sentence states the specific action and resource ('读取记忆文件'), and the description enumerates which files can be read (FACT.md default, plus SOUL.md / USER.md / JOURNAL.jsonl / FACT.archive.md). It also names memory_search as a companion tool, which helps separate it from that sibling. What's missing is a one-line statement of what distinguishes memory_read from memory_search or memory_stats.

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 spells out a priority order for the three retrieval modes: tail vs offset/limit vs full read, and explicitly recommends using line numbers from memory_search to read the archive cheaply. That is concrete when-to-use guidance. It doesn't explicitly state when NOT to use this tool (e.g. 'use memory_search to find content instead of reading whole files').

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

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

With no annotations, the description carries the full burden and does it well: default dual-source search, the nature of archive segments (moved old FACT paragraphs, not fixed-injected), empty-query behavior, case-insensitive substring matching rather than semantic search, and what is returned (recent limit events with timestamps and tags plus matching archive lines).

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

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

Front-loaded with the core action, then layers defaults, filtering semantics, and matching behavior in a tight sequence. Dense but nearly every clause carries distinct information; only the archive parenthetical is slightly explanatory rather than operational.

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

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

For a 6-parameter, zero-schema-coverage, no-annotation tool, the description supplies the missing parameter semantics and matching behavior, and it need not detail return shapes since an output schema exists.

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 0%, so the description must compensate, and it does: tag accepts comma-separated multiples with OR semantics, after/before use YYYY-MM-DD local dates inclusive of the boundary day, limit caps returned events, and include_archive is implied by the default dual-source behavior.

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 clear verb and resource, and the description immediately explains the two search scopes (JOURNAL events and FACT.archive.md). It distinguishes searching from the reading/writing siblings by describing what archive retrieval actually means, though it never names memory_read or memory_stats explicitly.

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 tells the agent that an empty query becomes a pure tag/date listing of JOURNAL, and that archive is included by default but can be excluded. That covers the main use cases, but there is no explicit 'use this instead of X' routing against the sibling 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?

No annotations are present, so the description carries the full safety burden — and it does: 'read-only', 'never touches any files', and 'does not judge content importance'. That discloses the non-destructive profile and the limits of what it measures. It stops short of describing freshness/pagination concerns, so a 4 rather than a 5.

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

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

The description is a single dense sentence that front-loads purpose and return contents, then adds when-to-use and the boundary. Every clause maps to returned fields or usage guidance, though the enumeration of fields is long enough that it could be trimmed had an output schema not existed.

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 zero params, a full output schema, and a read-only measurement tool, the description is nearly complete: it explains what is measured, when to use it, and what it will not do. The minor remaining gap is whether 'today's new entry count' depends on a timezone or clock, which the agent must infer.

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 are zero parameters and schema coverage is 100%, so the baseline of 4 applies. Nothing about invocation is ambiguous; the description correctly enumerates the returned fields instead of wasting space on nonexistent arguments.

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

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

The description gives a specific verb (returns), an explicit resource (memory file sizes, line/entry counts, modification times, JOURNAL timestamps, backup usage), and marks itself read-only. It is clearly distinguishable from the sibling memory_read / memory_append / memory_update tools, since it only measures metadata and never returns or changes content.

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 two concrete situations to call it: before organizing memory, and before answering "do you remember X". It also states the negative scope — it does not judge content importance — which implicitly routes content questions to memory_search. It does not name the alternatives explicitly, so it falls just short of a 5.

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

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

With no annotations, the description carries the full behavioral burden and discharges most of it: it discloses that the old content is destroyed, that an automatic backup happens before the write, and gives the exact guardrail (reject if new content <1KB and less than a third of the old content) plus its rationale (防写坏, corruption prevention). Missing only edge details such as where the backup lives, whether the guard can be overridden, and required permissions.

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?

One dense sentence plus a parenthetical: target and semantics first, then the backup and guardrail details. No filler and no repetition of the tool name.

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?

An output schema exists, so return values need not be explained here, and the destructive-write risk plus the safety guard are well covered for a one-parameter overwrite tool. What is absent is prerequisite/permission context and any indication of what happens on a rejected write (error shape, backup location).

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 'content' parameter has 0% schema description coverage, so the description must compensate. It does convey that content is the complete replacement text for FACT.md and hints at a size floor (<1KB triggers the guard), but it never states format expectations (markdown?), total-replacement vs merge, or encoding.

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 in the first three words: '覆盖写入 FACT.md（长期记忆）' (overwrite FACT.md, long-term memory). The overwrite semantics inherently separate it from the sibling memory_append (incremental add) and the read-only memory_read/memory_search, so an agent can route correctly 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?

The word '覆盖写入' (overwrite) implies this tool replaces the whole file, which indirectly signals that memory_append is the alternative for incremental additions. However, no sibling is named and there is no explicit when-to-use / when-not-to-use statement, so the routing is left to inference.

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