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

Beyond annotations, it discloses that nothing is physically deleted, that the entry remains restorable, that the action is audited in memory_events, and that it is unavailable on read-only connections. It also details idempotent behavior explicitly ('also when it already was') and describes the return shape including error conditions, all consistent with 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?

The description is front-loaded with the core action and scope, then adds only necessary constraints, alternatives, return behavior, and availability. Every sentence earns its place, and there is no redundancy or 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?

Given a three-required-parameter mutation tool with no output schema, the description is complete: it explains what happens, what is preserved, how to restore it, when to prefer a sibling, what the return values mean, and connection limitations. Nothing an agent needs 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 description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds only marginal parameter meaning, mostly confirming that reason must not be empty and is stored in the audit log, which the schema also states. Baseline 3 is appropriate when 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?

The description states a specific verb and resource: 'Archive (soft-delete) one entry'. It immediately distinguishes this from siblings by explaining the soft-delete semantics ('hide it from normal reads and search while keeping it, restorable with memory_restore'). An agent can tell this is not memory_write, memory_restore, or memory_get.

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-to-use guidance: 'Use it for a fact that became wrong or obsolete'. It also names the preferred alternative and condition: 'to correct a fact, prefer memory_write on the same scope + name'. It additionally states an availability constraint: 'Not available on read-only connections.'

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/idempotentHint/destructiveHint=false, so safety is covered. The description goes beyond them by disclosing the operational state model: entries without a current embedding are lexical-only until the next embed-backfill run, which is a CLI command rather than an MCP tool. That is genuinely useful context an agent cannot get from 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?

Front-loaded with the core readout, then the diagnostic rationale, then routing to siblings. All three sentences carry information, though the rationale sentence is somewhat long and could be tightened without losing meaning.

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

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

There is no output schema, yet the description enumerates exactly what the tool reports (active flag, model name, embedded-entry count), which effectively covers the return values. Combined with the routing guidance and the lexical-only caveat, an agent has everything needed to call and interpret it.

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?

Zero parameters, so the schema baseline is 4. The description reinforces this with 'takes no arguments', correctly signalling that invocation requires no input.

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 (report) and three concrete resources of the readout: whether semantic search is active, the embedding model, and the count of entries with current embeddings. This scope is distinct from the sibling tools it names, so an agent can tell it apart from memory_stats or memory_healthcheck 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 frames the diagnostic scenario ('understand why memory_search finds or misses entries that share no keywords') and names two alternatives with their own conditions: memory_stats for general counts and memory_healthcheck to test that the store works. When-to-use and when-to-use-something-else are both 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description still adds real context: the log is append-only, results are newest-first, and scope-locked connections only see their own scope's events — none of which 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, front-loaded with the core verb and content, then routing guidance, then execution constraints. No filler and each 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?

An output schema exists so return shape needn't be explained, and the annotations carry the safety profile. The description still covers ordering, scope-visibility edge cases, and sibling routing, leaving nothing an agent needs 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 name, limit (with clamping to 1-200), and scope are already fully documented in the schema. The description adds no parameter-level detail, so this sits at the baseline for high-coverage schemas.

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 (read) and resource (append-only audit log), then enumerates exactly what the log records: who wrote/updated/archived/restored what, when, from which client, plus conflicts and secret redactions. It explicitly distinguishes itself from the sibling tools it could be confused with (memory_history, memory_recent).

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 concrete triggering question ("who changed this, and why?") and names two alternatives with the condition that selects each: memory_history for previous CONTENT, memory_recent for the latest entries themselves. This is explicit when/when-not/alternative guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: it returns null for unknown scope/name and hides archived entries unless include_archived is true. It stops short of describing other edge behavior (e.g. scope-locked connections), but this is solid added value beyond 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?

Two short sentences, front-loaded with the core action, followed immediately by the selection condition. Every clause 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?

With an output schema present and annotations covering the safety profile, the description only needs to supply the ambiguous edge cases — and it does: the null return for missing entries and the archive-hiding default. 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 all three parameters are already documented at the field level (including the kebab-case name convention and the --scope override). The description only echoes 'exact scope and name' and the archived gating, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one memory entry, complete, by its exact scope and name'), which cleanly distinguishes a keyed single-item get from list/search/recent siblings. The 'complete' qualifier signals it returns full content rather than a summary.

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 the precondition ('when you already know both keys'), names where those keys come from (memory_search, memory_list, memory_recent), and gives the motivating purpose ('need the full, current content before relying on it'). 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 annotations: it discloses runtime (~1 s), that writes are confined to a throwaway scope (`_healthcheck` or `_healthcheck_<scope>`), that cleanup always occurs, that real entries are never touched, and the return shape {ok, checks[], db_path}. It also flags the read-only-connection restriction, which the annotations alone 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?

Front-loaded with the operation and its cost, then usage guidance, then the side-effect guarantee, then the return shape and the availability caveat. Every clause carries information an agent needs; nothing is 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?

Despite having no output schema, the description supplies the return structure ({ok, checks[], db_path}), the side-effect envelope, and the availability constraint. For a zero-parameter diagnostic, nothing material 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter syntax the description needs to compensate for. The description instead spends its budget on return shape and side effects, which 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 ('self-test') and resource (MemCore end to end) and enumerates exactly what it exercises: write, read, search (strict AND and OR-fallback), history, delete. This is clearly distinguishable from sibling tools like memory_write or memory_search, which perform one of these operations rather than verifying all of them.

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 ('instead of assuming a connection is healthy just because it is listed') and gives the failure mode it guards against ('a connection can look fine while search silently misbehaves'). It also names the when-not condition and alternative: 'Not available on read-only connections; use memory_stats there.'

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 readOnlyHint/idempotentHint annotations by disclosing the automatic version-retention model, that an empty list is returned when there is no history, and that the tool works even on a read-only connection. These are non-obvious traits 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?

Front-loads the core action and keeps the routing hints in a compact clause. The sentence about write behavior is slightly explanatory overhead, but it earns its place as rationale for trusting the history.

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 an output schema present, the description needn't explain return shape, yet it still notes the empty-list case. Combined with sibling routing and read-only availability, 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 coverage is 100% and all three parameters are already documented in the schema, including clamping for limit and scope-locked connection behavior. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Show the prior versions of one entry that were overwritten or deleted, newest first'), including the ordering. An agent can distinguish it from memory_get and memory_events 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 names both alternatives and the condition that selects them: memory_events for authorship, memory_get for the current version. It also names the triggering task ('recover or compare earlier content').

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, idempotentHint and destructiveHint=false, so the safety profile is covered; the description redundantly restates 'Read-only' but adds a genuinely useful behavioral detail, the invalid-type error shape ([{"error": ...}]). It stops short of describing pagination or result volume behavior for a listing 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?

Front-loaded with the core scoping constraint 'WITHOUT a search query' and tightly ordered: what it does, when to use it, alternatives, then an edge-case note. Slightly bloated by the 'Read-only' line, which only repeats the readOnlyHint annotation.

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 is present, so return-value documentation is unnecessary, and the description covers purpose, alternatives, edge-case error behavior and read semantics. Nothing an agent needs to select or call this listing tool 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 meaning beyond the schema by framing the archived flag as 'candidates for memory_restore' and the scope filter as 'everything in a project scope'. The remaining parameters (type, limit) are left to the schema, which documents them 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?

States a specific verb (browse) plus the resource (entries) and the exact filters it operates on (scope, type, archived state), and explicitly contrasts itself with search-based retrieval. An agent can distinguish this from memory_search 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 three concrete when-to-use scenarios (project onboarding, single-type listing, archived entries for memory_restore) and explicitly routes content-based lookup to memory_search and latest-change lookup to memory_recent. Exclusions and alternatives are both named.

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, idempotentHint, and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the newest-first ordering, the optional single-scope restriction, and the 'Read-only' confirmation. It does not add anything about pagination or result size behavior, so not a 5.

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

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

Front-loads the core action and ordering in the first sentence, then the usage guidance, then the alternative routing. Efficient overall, though the trailing 'Read-only' sentence is redundant given the readOnlyHint annotation.

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, all three parameters are documented, and the description covers purpose, timing, scoping, and alternative selection. Nothing an agent needs in order 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 description coverage is 100%, so limit, scope, and include_archived are already fully documented in the schema, including the clamping range and the scope-locked override. The description's 'optionally within one scope' adds nothing beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the most recently created or updated memory entries') plus the ordering guarantee ('newest first'). An agent can distinguish it from memory_search, memory_list, and memory_events 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 an explicit trigger scenario ('catch up on what changed lately, start of a session, after another agent worked') and routes to three named alternatives with the exact condition that selects each (content lookup, unordered browse, change attribution). Nothing 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.

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), yet the description goes further by disclosing audit logging into memory_events with the supplied reason, the read-only-connection restriction, and all three response shapes with their trigger conditions. It clarifies idempotency in practice ("also when it was not archived"), which the annotation only signals abstractly.

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 effect is front-loaded in the first sentence, the relationship to memory_archive comes second, and follow-up sentences are short and single-purpose. Dense with information but free of filler or repeated annotation 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 no output schema, the description takes responsibility for return values and does so fully (success, not-archived, missing entry, empty reason). Combined with the discovery workflow and connection restriction, nothing an agent needs to call this correctly is absent.

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; however, the description adds consequences the schema does not, namely that an empty reason yields {"ok": false, "error": ...} and that scope/name misses yield {"ok": false}. It does not restate the kebab-case or scope-locked-connection details, so the gain is modest but real.

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 ("Restore one archived entry") plus the observable effect ("appears again in normal reads and search"), and explicitly frames itself as "The inverse of memory_archive." An agent can distinguish it from memory_archive and memory_list 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?

Names the prerequisite discovery path ("Find archived entries with memory_list(archived=true)") and the environment precondition ("Not available on read-only connections"), which is exactly the context an agent needs before attempting the call. It also covers the no-op case so the agent does not misread a successful restore of a non-archived entry as failure.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds a genuine behavioral constraint beyond structured data: a scope-locked connection only sees its own scope, which affects what results an agent should expect.

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 routing guidance, then the visibility caveat — each sentence earns its place. Minor redundancy: 'Read-only' restates the readOnlyHint annotation.

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 no explanation. Combined with explicit routing to siblings and the scope-lock caveat, 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?

The tool takes zero parameters, so the schema-description baseline is 4. The description correctly reinforces this ('takes no arguments') without needing to explain any argument semantics.

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

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

States a specific verb and resource ('List every known project/topic scope') plus the returned payload ('with its number of entries'). It is immediately distinguishable from its siblings like memory_stats and memory_list, which it names.

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 to use it first to discover valid `scope` values for other tools, and names the alternatives with their selecting conditions: memory_stats for totals/location, memory_list for browsing one scope's entries. Both when-to-use and when-not-to-use 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?

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantial behavior: the two-layer FTS5 + semantic blend, the ALL-terms-then-ANY-term fallback, that embeddings are optional, that archived entries are never returned, and that an empty list is returned on no match or invalid query.

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 purpose and the routing guidance, then the two-layer mechanics. Slightly long, but every sentence (fallback logic, archived exclusion, return shape) adds distinct value rather than restating structured fields.

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 specifying the return shape (list of entries, best match first, empty list on no match/invalid query). Combined with the annotations and full schema coverage, 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the two search layers that drive the `semantic` default and notes that searching every scope is the norm, reinforcing the `scope` omission behavior beyond the schema text.

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 (search) and resource (remembered facts) with explicit scope ('across every project scope'). It explicitly differentiates itself from siblings by naming memory_get, memory_list, and memory_recent with their distinct conditions.

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?

Declares itself 'the default entry point' and instructs the agent to use it before assuming something is unknown. It then routes to three named alternatives with the exact condition that selects each (known scope/name, browse without query, recent changes).

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, idempotentHint=true, and destructiveHint=false, and the trailing "Read-only, takes no arguments" largely restates them plus the empty schema. The only added value is disclosing that the result includes the backing database file path, which is useful but thin against an already-complete safety profile.

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 returned fields, then usage and alternatives, then the read-only/no-arg note. Compact and free of filler, though the trailing restatement of annotations is mildly redundant.

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

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

There is no output schema, so the description carries the burden of describing return values and does so by enumerating all four reported items. Combined with the sibling routing, an agent has everything needed to select and call it.

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

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

The tool takes no parameters, so the baseline is 4, and the description correctly confirms "takes no arguments," consistent with the empty schema. There is nothing further to disambiguate.

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 ("Report") and enumerates exactly what is reported: total entries, archived entries, database file location, and scope list. It is clearly distinguishable from siblings like memory_scopes and memory_healthcheck, which are named 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?

Gives explicit use conditions ("quick overview", "check which database file this connection uses") and routes to three alternatives with the condition that selects each: memory_scopes for per-scope counts, memory_embed_status for search coverage, memory_healthcheck to verify the store works.

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 non-readOnly, non-idempotent, non-destructive, but the description goes well beyond them: versioning via memory_history, event logging, undoability, archived-entry refusal, secret redaction with the `redacted` codes in the result, error classes (conflict, busy DB retry), and unavailability on read-only connections. This is exactly the behavioral layering the annotations do not provide.

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?

Dense but front-loaded: purpose first, then the duplicate-avoidance rule, then update side-effects, then redaction, then return/error contract. Line-broken and skimmable; slightly long, but nearly 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?

For a mutation tool with no output schema, the description supplies the success envelope ({"ok": true, "id": ...}), the failure envelope and its causes, and the read-only-connection limitation. 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 baseline is 3, but the description adds real meaning: the scope+name update-in-place contract and the redaction behavior affecting `content`. It does not re-explain expected_updated_at, which the schema already covers well, so it stops short of a 5.

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

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

States a specific verb+resource ('Record a new fact, or update an existing one') and clarifies the update mechanic (same scope + name updates in place). An agent can distinguish this from memory_get or memory_search 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?

Explicitly instructs to search first via memory_search to avoid duplicate names, and states the exclusion path for archived entries ('refused: restore it first with memory_restore'). Names alternatives and the conditions selecting them.

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