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

No annotations exist, so the description carries the full burden and does so: content is scanned for secrets before any filesystem write, a match rejects the write, bypasses are audited as 'bypassed' and never apply to project_shared because git history cannot be retracted from clones. It also discloses idempotency semantics (24h, only successful writes recorded, at-least-once without a key) and a near-duplicate warning on return.

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 summary and return behavior are front-loaded before the Args block, and nearly every clause carries operational information. It is long, and a few parenthetical asides (e.g., the example credential schema) could be trimmed, but nothing is 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 an 11-parameter mutation tool with zero annotation coverage, the description covers safety guards, escape hatches, consent requirements, idempotency, namespace conflict handling, and the confirmation-plus-duplicate-warning return, so an agent needs nothing else 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 0%, so the description must compensate and does: every one of the 11 params gets meaning beyond its title, including file defaulting to a timestamped file in the first memory_dir, namespace defaulting to config, the five built-in templates, the 256-char/24h idempotency contract, and allow_namespace_mix overriding a default refusal.

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 pairs a specific verb with a specific resource and outcome: 'Add a new memory entry to a markdown file and immediately index it.' That distinguishes it in spirit from mem_read/mem_search/mem_index, but it never names a sibling or explicitly says when a caller should prefer mem_add over mem_do or mem_index, so it falls 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?

It gives concrete decision guidance inside the parameters: use force_unsafe only for known false positives, that force_unsafe is hard-refused with scope=project_shared, and that confirm_project_shared is required for Git-tracked writes. It doesn't route between this tool and its siblings, so it is clear context without explicit exclusions at the tool-selection level.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: it never says whether actions mutate data, which are destructive (e.g. "cleanup_orphans" is mentioned only as an alias example), what permissions or preconditions apply, or how failures are reported. The alias-resolution note and help behavior are genuinely useful, but for a catch-all gateway spanning many unknown operations this leaves the agent guessing at 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?

Front-loaded with the purpose, then the scoping statement, then the discovery mechanism — a sensible order with no filler. The Args block largely restates the schema and the example aliases, so it is slightly padded but still short.

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 described, and the help/discovery path covers the missing action catalog by design. Still, for a two-parameter gateway with zero schema coverage and no annotations, the description should say more about mutation risk and about what params keys look like per category rather than deferring everything to a runtime call.

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

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

Schema description coverage is 0%, so the description must compensate; it explains that action is an action name with examples and that params is an optional dict of action-specific parameters. That is a meaningful addition, but the actual keys of params remain entirely opaque and the agent must make a discovery call to learn them.

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 ("Execute a memtomem action by name") and positions itself as the gateway to features beyond the core tools, explicitly listing the core tools it is not (search, add, index, recall, status, stats, list, read). The one gap is that the set of valid actions is never enumerated, so the agent knows the category of the tool but not its surface.

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?

Clearly scopes use to advanced features not covered by the named core tools, which effectively routes the agent away from this tool for common operations. It also gives a concrete discovery path (action="help", plus params={"category": ...} for per-parameter detail). It stops short of explicit when-not conditions or a mapping of which advanced action to pick.

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

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

No annotations are provided, so the description carries the entire behavioral burden for what is a write/mutation operation. It discloses the force semantics (unchanged files are normally skipped) which is genuinely useful, but says nothing about whether removed or renamed files leave stale index entries, whether deletion is possible, what 'hybrid search' entails (embeddings? keyword?), cost/duration, or concurrency behavior during re-index.

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 one-sentence purpose followed by an Args block where each line adds distinct information. No filler, no restatement of the title, no redundant syntax notes.

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, and the parameter block covers the inputs well. But for an unannotated ingestion tool whose side effects persist in a searchable store, the absence of any note on staleness, incremental-vs-full semantics beyond force, or failure/partial-index behavior leaves the agent unable to predict consequences of calling 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?

Schema description coverage is 0%, so the description must compensate, and it largely does: all five parameters are described with meaning and defaults, and 'force: re-index all files even if unchanged' and 'auto_tag: keyword-based auto-tagging on newly indexed chunks' convey behavior not derivable from the schema titles. The namespace entry is thin — it says chunks are assigned but not what a namespace scopes or whether the search must reuse the same value.

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 (index / re-index) and resource (markdown files) plus the downstream purpose (hybrid search). It is clearly distinguishable from read-oriented siblings like mem_search or mem_read, but never contrasts itself with mem_add, which also appears to ingest content — a missed differentiation rather than a clarity failure.

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?

Usage is implied by the phrase 'index or re-index' and by the force parameter ('re-index all files even if unchanged'), so an agent can infer when to use incremental vs forced runs. However, there is no explicit when-not guidance, no statement of prerequisites (does the store need to be initialized? does mem_add already cover this?), and no pointer to alternatives among the many siblings.

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

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

With no annotations, the description carries the full burden and does a solid job: it discloses pagination, the 1-500 bound with a default of 50, and that the cursor must be copied from the previous response's 'More:' line. It doesn't state permission requirements, behavior on an empty result, or ordering of results.

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 one-line summary, then a compact Args block, then two illustrative examples. Every line adds information; nothing repeats the schema without adding 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?

An output schema exists, so return structure needn't be explained, and the description still usefully notes chunk counts and the 'More:' pagination line. Minor gaps remain around ordering and empty-result behavior for a list tool with no annotations.

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 entirely — and it does: source_filter semantics (substring vs glob with *, ?, []) , namespace scoping, limit range and default, and cursor provenance are all spelled out. These are details the bare schema does not convey.

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 names a specific verb and resource — 'list indexed source files with chunk counts' — and adds the pagination scope ('one page at a time'). That clearly separates it from retrieval siblings like mem_search or mem_read, though no sibling is 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?

The two examples show concrete call patterns (glob filtering, namespace filtering), which gives an agent clear use contexts. However, there is no explicit when-not guidance — nothing says to use mem_search instead when you need content matching, or that listing is the discovery step before reading.

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 so well: it discloses project-scoped ID resolution and the specific failure mode that out-of-scope IDs 'read as not found.' That is real behavioral information beyond the schema. It doesn't discuss permissions or limits, 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?

The purpose and the scoping caveat are front-loaded in two short paragraphs, and nothing is padded. The trailing 'Args:' block is somewhat redundant with the schema, but it carries the useful provenance hint, so it still 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 single-parameter read tool with an output schema covering return values, everything an agent needs is present: what it returns, when to call it, how IDs resolve, and what happens on a cross-project miss. 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?

Schema coverage is 0%, so the description must compensate, and it does: chunk_id is described as 'The chunk's UUID (from mem_search results),' telling the agent both the format and where to obtain the value. That is the key semantic the bare string 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 line states a specific verb and resource — 'Read a chunk's content and metadata by UUID' — which is clearly distinct from sibling list/search tools like mem_search or mem_list. It stops short of explicitly naming a sibling it replaces, but the retrieval-by-identifier framing does the disambiguation work.

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 concrete call situations: 'Inspect a chunk before editing, or see the text behind a search preview.' That tells an agent exactly when this beats mem_search. No explicit when-not or prerequisite conditions are stated, keeping it from 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 does real disclosure work: it states results are ordered newest-first, that tag_filter is applied before limit, and — critically — the default scope-merge behavior (user + project tiers in-project, user only out-of-project). It omits any permission/auth notes and doesn't say what happens when since/until are omitted.

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 one-line summary and return-ordering statement are front-loaded, followed by a clean Args list and concrete examples. It runs long, but nearly every line adds operative detail; only the ADR-0011 reference is jargon an agent can't act on.

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 shapes needn't be spelled out, and the description still covers ordering, default limit, and scope defaults. The notable gap is behavior when all filters are null — it's unclear whether that means 'all memories' or requires since/until.

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 carries the full burden and does so: every one of the 8 parameters gets meaning beyond its name, including accepted date formats, glob/substring matching semantics, ANY-tag matching order relative to limit, mutual exclusivity of single-vs-glob for scope, and the hints field in structured output.

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: 'Recall memories created within a date range', with return ordering clarified. However, it frames the tool narrowly as a date-range recall even though scope/source/tag/namespace filters make it a general listing tool, and it never distinguishes itself from siblings like mem_list or mem_search.

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 Examples block shows three call patterns but gives no explicit when-to-use guidance or exclusions relative to mem_search, mem_list, or mem_read. An agent must infer that this is the unfiltered-by-content listing tool rather than a search tool.

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 does so thoroughly: it discloses namespace/scope visibility defaults, as_of validity semantics, rerank server-config limitations, record side effects (no cache/history), and score-scale caveats.

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?

Well structured and front-loaded: the first sentence states the tool's purpose, followed by parameter details and caveats. The length is largely justified by 14 parameters and no schema descriptions, though the final scoring-scale paragraph is reference-manual depth rather than essential invocation guidance.

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

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

Given the tool's complexity, 14 parameters, no annotations, and a present output schema, the description is complete enough for correct invocation. It covers visibility rules, parameter interactions, deprecated fields, output formats, and scoring caveats without needing to duplicate the 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 0% and there are 14 parameters, so the description must compensate. It documents every argument, including defaults, allowed forms, constraints (both weights finite and not both zero), deprecation behavior, and nuanced semantics such as glob filters and context-window neighbor rules.

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 ('indexed memory files'), plus the retrieval mechanism ('hybrid BM25 + semantic search'). It does not explicitly differentiate itself from siblings such as mem_recall or mem_list, so it falls 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?

Provides useful usage contexts for rerank=false (latency-bounded callers), record=false (fan-out callers), namespace omission, scope defaults, and top_k expectations. However, it gives no explicit guidance on when to use this tool versus sibling tools like mem_recall or mem_list.

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

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

No annotations are provided, but the tool takes zero parameters and has an output schema, so the behavioral surface is small. The description implies a read-only inspection and lists the returned fields, but says nothing about side effects, auth needs, or whether the index is recomputed or cached — modest but not rich 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?

Two sentences, zero waste, with the return contents front-loaded. The second sentence adds genuine routing value rather than restating the first, though it stops short of the differentiation that would make it fully earned.

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 zero-parameter read tool with an existing output schema, the description covers purpose and a usage moment adequately; the output schema carries the return shape. The only notable gap is disambiguation from the very similarly named mem_status sibling.

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 there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly avoids inventing parameters.

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 (Return) and resource (memory index statistics), and even enumerates the returned fields: total chunks, sources, storage backend. It does not, however, distinguish itself from the similarly named sibling mem_status, leaving ambiguity an agent must resolve on its own.

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 sentence 'Use this to quickly assess how many memories are indexed before searching' gives one clear usage context. It names no exclusions and never contrasts with mem_status, mem_list, or mem_search, so an agent cannot tell from the description alone when stats is preferable to status.

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 delivers: it discloses that configuration drift produces a Warnings block, that kind is an open enum to be tolerated rather than errored on, and that certain keys (stored/configured, same_parent) are stable across versions. It never explicitly states read-only/side-effect behavior beyond the word 'show', which keeps it from 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-loaded with the purpose and what it reports, then the warning semantics. Information-dense with no filler, though the second paragraph of key-level detail is fairly dense for a description and could be trimmed if the output schema already covers field names.

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 enumeration is not required, and the description appropriately adds only the semantics the schema can't convey (open enum tolerance, key stability, drift warnings). Combined with the mem_cleanup_orphans handoff, an agent has what it needs 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?

The tool takes zero parameters, so the baseline is 4. The description correctly makes no parameter claims and instead spends its budget on result 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+resource: 'Show indexing statistics and current configuration summary,' and enumerates what is reported (storage backend, embedding info, chunk/source counts, orphan warnings). It does not differentiate itself from the sibling mem_stats, which plausibly overlaps, 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?

The description gives one concrete routing rule — when orphaned source files are reported, run mem_cleanup_orphans — which is genuinely actionable. However, it never says when to use mem_status versus mem_stats or mem_list, leaving the most likely ambiguity unresolved.

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