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

Annotations already establish readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description mainly restates that ('writes nothing') and adds the modest detail that an empty occupants list is legal and produces an explicitly degraded report. It does not mention the verification behavior for episode_id claims, which the schema covers instead.

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 dense sentences with the core purpose front-loaded and the fallback case parenthesized at the end; no filler. The em-dash clause stack is slightly compressed but still parseable.

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 full annotations, a rich nested schema and an output schema, the agent needs little more than purpose and payload shape, both of which are present. The one gap is that the description never situates this tool among its twelve siblings, which matters for a diagnostic-style 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?

The top-level schema is only a 'params' wrapper (reported coverage 0%), so the description has to carry semantic load - and it does, mapping the occupant fields to plain language ('label, size, live or not'). The nested definitions are also well documented, so the agent can populate the payload without guessing, though budget/staleness semantics are 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+resource: it reports the composition of the caller's context window and returns 'ranked proposals' for what to drop, and it explicitly says it 'writes nothing'. That distinguishes it from write-oriented siblings like memshelf_shelve and memshelf_purge. It does not name any sibling directly, so it stops short of top marks.

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 a usable usage condition - pass occupants when you want the window side analyzed, omit them and you get the shelf side only - so the agent can infer when to call it. However, it never contrasts itself with the many nearby read siblings (memshelf_stats, memshelf_recall, memshelf_search), so routing between them 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 readOnly/idempotent/non-destructive/openWorld, so safety is covered; the description adds genuine extra context by listing the specific invariants checked, stating it performs no repairs, and disclosing that check_remote hits the network and is off by default. It does not describe failure reporting or exit behavior, but that is largely covered by the output 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?

Two tight sentences, heavily front-loaded with the diagnosis scope, followed by the non-fixing guarantee and the one parameter caveat that changes behavior. No filler.

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

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

For a read-only diagnostic tool with an output schema, the description covers scope, non-mutating behavior, and the network caveat — enough to invoke correctly. Minor gap: it never states what a failure result looks like, though the output schema plausibly carries that.

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?

Top-level coverage reads as 0% (the single visible param is the wrapper), but the nested DoctorInput fields are themselves well documented in the schema. The description adds real meaning only for check_remote (network probe for a publicly visible remote) and says nothing about shelf_path defaults or derived_stale_after_hours, so it sits at the schema-does-the-work baseline.

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

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

States a concrete verb and resource ("Diagnose shelf integrity") and enumerates the exact checks performed: episode schema, digest contract, leaked secrets, ledger consistency, INDEX budget. That scope is more specific than siblings, though it never names memshelf_lint_digest or memshelf_advise to draw the boundary 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?

"Read-only; fixes nothing" implicitly tells the agent this is the inspection step rather than the repair step, and the check_remote sentence explains when the optional network probe applies. However, there is no explicit when-to-use / when-not guidance and no routing to overlapping siblings like lint_digest or stats.

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 write behavior (readOnlyHint=false), idempotency, and no destructiveness, so the safety profile is covered. The description adds the notable trait 'without pulling it through context' and that extract writes to a working file, but says nothing about permissions, error behavior, or what the write touches.

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 followed by the method breakdown in two tight clauses. No filler, though the sentence is dense with backticked terms that blur quick scanning.

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 annotations cover the safety profile. The description covers the dual-mode workflow adequately, leaving only minor gaps around preconditions and parameter specifics.

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 description adds meaning for the `method` enum by describing both modes, but with reported schema coverage at 0% it does not compensate for path, out, select, markers, or limit. It only partially 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?

The description names a specific action (retro-shelve an exported dialog) and immediately breaks it into its two operational modes (`discover` lists, `extract` cleans and writes). It does not explicitly contrast itself with siblings like memshelf_shelve, but the verb+resource is clear enough to place it.

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 distinguishes the two methods by function ('discover' lists conversations, 'extract' cleans one to a working file), which implies which to pick. However it never states prerequisites, when-not-to-use, or how this differs from memshelf_shelve or memshelf_index, leaving the agent to infer 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that the payload is small and read whole, which is useful sizing context, but it does not disclose anything further about auth or scope. Adequate but not rich given the low bar set by 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, zero waste, with the primary instruction (read this first) front-loaded ahead of the follow-up action.

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 one-parameter read tool with an output schema, the description covers purpose, ordering, and the alternative. Minor gap: it never mentions shelf selection, though the input schema handles that adequately.

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 description says nothing about the shelf_path parameter, so it adds no meaning beyond the schema. The schema's own description does explain the $MEMSHELF_SHELF_PATH default and when to override it, so semantics are documented somewhere; the description simply does not contribute.

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 ("Return the shelf INDEX") and immediately characterizes it as "the small recall entry point," which distinguishes it from the sibling memshelf_recall without the agent needing to open 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?

Explicitly prescribes when to call it ("Read it before answering anything about past work") and how it relates to the alternative ("then recall only what you need"), effectively routing the agent to memshelf_recall as the follow-up rather than as a substitute.

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

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

Annotations already declare destructiveHint=false, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered; the description adds value by enumerating exactly what gets created and by promising it never overwrites existing files. It does repeat the idempotency claim slightly, but the non-overwrite guarantee is genuine added 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?

Two tight sentences with no filler; the create action and artifact list come first, the idempotency/non-overwrite guarantee second. Efficient and front-loaded.

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, and annotations cover the safety profile. The gap is on the input side: for a bootstrapping tool with nested params at 0% coverage, the description should at least hint at storage modes and the shelf_path/env-var interaction, which it omits.

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% per the signals, so the description should compensate, but it says nothing about the name, storage mode (plain/git-local/git-remote), remote URL constraints, or the shelf_path env-var fallback. An agent must rely entirely on the nested schema, and the meaningful storage-mode semantics are left unexplained.

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?

Specific verb (create/top up) plus resource (memory shelf) and an explicit list of artifacts produced (layout, categories, INDEX preamble, POLICY.md, shelf.yml). It is clearly distinguishable from siblings like rebuild, purge, or import, though it never names an alternative tool directly.

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?

'Create (or top up)' implies this is the bootstrap/first-run step, and the idempotency note hints it is safe to re-run. However, there is no explicit when-to-use vs. when-to-prefer-siblings guidance (e.g., versus memshelf_rebuild or memshelf_import), leaving routing 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 readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds value beyond them by explaining that `strict` escalates warnings to failures and that this is the identical validator used at shelf time, though 'writing nothing' partly restates the readOnly annotation.

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 tight sentences, front-loaded with the core action and the writing-nothing guarantee, followed by the strict-mode modifier. No filler and nothing 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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. The description supplies the purpose, the timing, and the strict behavior, though it could have clarified the digest parameter for full completeness.

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 reported as 0%, so the description should carry the load. It explains the `strict` behavior and its effect (warnings become failures), but says nothing about the `digest` parameter itself, leaving its semantics to the schema alone.

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 (check/lint), resource (a digest), and scope (against the contract, while being written), and explicitly links itself to the sibling `memshelf_shelve` by noting it is the same validator that tool runs. An agent can distinguish this from `memshelf_shelve` 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?

It clearly frames the use case — validating a digest in-progress before it is shelved — and names the related tool it mirrors. It stops short of an explicit when-not or a statement of what to call instead once the digest is finalized, but the timing condition is well conveyed.

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' destructiveHint/idempotentHint by disclosing that the default is a dry run, that deletion is scoped to working-tree files, and that git history retains the removed episodes, plus a reindex is triggered afterward. These are exactly the safety details an agent needs before invoking a destructive 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?

Two short sentences, no filler; the destructive condition and the reversibility caveat are both front-loaded and immediately actionable.

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 destructive annotations, an output schema covering return values, and only one nested parameter object, the remaining burden is behavioral disclosure and the description supplies it (dry run, scope of deletion, git retention, reindex). 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 reported at 0%, so the description must carry parameter meaning; it does cover the semantics of `apply` (dry run vs real delete) but is silent on `today` and `shelf_path`, which the nested schema documents instead. Partial compensation for the coverage gap.

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 ("Drop") plus the exact resource and selection rule ("episodes past `retain_until`"), then adds the follow-on action ("then reindex"). This is clearly separable from maintenance siblings like memshelf_rollup or memshelf_rebuild without opening any schema.

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

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

It tells the agent the default mode (dry run unless `apply=true`), which is strong operational guidance, but says nothing about when to purge versus other maintenance tools, nor any precondition (e.g. that it should be run after retain_until changes). Usage is implied rather than specified.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so safety is partly covered. The description adds real context beyond that: which files are rewritten, that check=true is non-mutating drift reporting, and the concurrency caveat about not running while a bot is rendering. It doesn't cover atomicity or failure behavior, keeping it out of 5 territory.

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 compact sentences: the primary action and its outputs come first, followed by the mode qualifier and the operational caveat. No filler, no repetition of the title.

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 idempotency and mutation profile, the description supplies what's missing: artifact names, the two modes, and the recommended run condition. The only gap is guidance on choosing between check and full rebuild in normal workflows, which an 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?

The schema's own nested descriptions for adopt, check, and shelf_path are already detailed; the description only restates the check=true semantics ('only reports drift') and adds nothing for adopt or shelf_path. Reported top-level schema coverage is 0%, but the nested field documentation carries the burden, so this lands at the baseline rather than below it.

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?

Specific verb ('Regenerate') plus resource ('the derived files') and it enumerates the exact artifacts produced (ledger.tsv, .meta.json, INDEX.md, stats.svg), so an agent knows precisely what this produces. It does not name the sibling tools it overlaps with (memshelf_index, memshelf_rollup, memshelf_stats), so disambiguation from those still requires inference.

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 clear operational condition: 'Hand-run it only on a shelf whose bot is not rendering', which tells the agent when this is appropriate vs. letting the automated path handle it. The check=true mode is also framed as a reporting-only path. It stops short of naming an alternative tool for the report-only case (e.g., lint/doctor 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered by structured data. The description adds only the vague 'as a data envelope' return-shape hint and says nothing about the default side effect of appending a recall-log entry (documented only in the `log` schema property) or about shelf resolution via $MEMSHELF_SHELF_PATH.

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 compact sentences with the core fetch semantics front-loaded and no filler. The second sentence earns its place by routing the `section` choice, though it could have been folded into the first for a tighter single-sentence definition.

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 the envelope contents, and read-only safety is covered by annotations. What is missing is minimal but real: no note that recalls are logged by default, which is the one behavior an agent might want to know before 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?

The visible schema itself documents episode_id, section, log, and shelf_path in some depth, so the description is not obligated to carry the full load; it reinforces the id and `## Section` selectors but says nothing about `log`, `max_bytes`, or `shelf_path`. The raw coverage signal (0%) reflects the top-level `params` wrapper, but the nested schema descriptions mean the description's marginal contribution is small.

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?

Specific verb ('Fetch') plus resource ('a shelved episode by id, or one `## Section` of it') tells the agent exactly what comes back, and 'by id' implicitly separates this from the keyword-oriented memshelf_search sibling. It stops short of naming any sibling explicitly, so the differentiation is inferred rather than stated.

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?

'Prefer the section when it answers the question' is a genuine when-to-use hint for the `section` parameter, which is the main branching decision in this tool. However, there is no guidance on when to recall by id versus using memshelf_search, memshelf_advise, or memshelf_resolve, nor any stated precondition that the episode must already have been shelved.

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 non-readonly, idempotent, non-destructive behavior, but the description goes further: it discloses that derived rows are unioned (no loss), that INDEX is rebuilt and doctor is run as side effects, and that episode conflicts are reported rather than auto-merged. This clarifies the limits of automated resolution beyond what the hints convey, though auth/permission requirements are unstated.

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

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

Three dense sentences with the core purpose front-loaded and no filler; each clause carries information about behavior or scope. The structure is terse but readable, though the compound second clause packs several operations together.

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, return values need not be explained, and the description covers the mutation's side effects, conflict semantics, and safety conditions. The only real gap is parameter-level guidance (commit/shelf_path), which is left entirely to the nested 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?

The description never mentions the commit flag or shelf_path, and notably omits the staged-vs-committed distinction that the commit parameter controls. The reported schema description coverage is 0% for the top-level parameter, so the description is expected to compensate for parameter behavior and does not.

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 scenario ("Settle the two-writers-on-parallel-branches conflict") and enumerates the concrete operation steps it performs: union derived rows, rebuild INDEX, run doctor. It also implicitly distinguishes itself from siblings like memshelf_index and memshelf_doctor by showing those are internal sub-steps of resolve rather than separate calls.

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 triggering situation (two writers on parallel branches) and adds "safe outside a conflict too," which tells the agent the tool is not restricted to conflict state. It does not explicitly name alternatives or exclusions, but the usage context is clear enough to route correctly.

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. The description usefully reinforces the non-destructive contract ('nothing is deleted') and discloses the effect on INDEX ('shrinking INDEX'). However it never addresses the notable idempotency=false trait (what happens on repeat calls) or reversibility, so the added behavioral context is only partial.

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 tight sentences, front-loaded with the core action and the non-destructive guarantee. The trailing 'Not the answer to `index-bloat`' is compact but its cryptic reference to an external concept costs a little clarity for the space it saves.

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, return values need not be explained, and the mutation semantics are largely covered by annotations. Still, the description leaves the agent without a clear picture of when this beats memshelf_shelve or memshelf_purge, and the ambiguous 'index-bloat' reference is not self-explanatory.

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 description clarifies the single most important argument — 'a digest-of-digests you write', i.e. the digest must be the caller's own synthesis — which matches the schema's digest contract. It adds nothing about date/until/slug/episode_ids/sections/display_title, so it does not meaningfully extend parameter meaning beyond the schema.

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

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

States a specific verb and resource: it archives episodes 'behind one digest-of-digests', names the affected artifact (INDEX) and clarifies scope ('a period's episodes'). An agent understands the operation, though differentiation from siblings like memshelf_shelve is only gestured at via the cryptic 'Not the answer to `index-bloat`' line.

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 phrase 'Not the answer to `index-bloat`' is an implicit exclusion, telling the agent this is the wrong tool for that problem, but it never names the correct alternative nor states a positive when-to-use condition. Usage is implied rather than explicit.

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

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

The annotations already declare this a safe, idempotent, non-destructive read, so the safety profile is fully covered. The description adds the AND-token matching semantics and return shape, which is modest extra value, but says nothing about result limits, ranking, or empty-match behavior.

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

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

Two tightly written clauses with zero filler; the retrieval semantics and the usage trigger are both front-loaded.

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 core search behavior and trigger condition are present. The one gap is max_results, whose default of 10 and effect on results is never described anywhere.

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 schema itself documents query (space-separated tokens, all must hit) and shelf_path (env-var default), so the description's restatement of token-AND matching is largely redundant. max_results carries no description in the schema and none here, leaving one parameter's semantics unexplained.

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 (grep/search), resource (episodes on the shelf) and the matching rule (every query token), plus what it returns (addresses and snippets). It is clear on its own but never names a sibling, so an agent must infer the boundary with memshelf_recall/resolve rather than being told.

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?

"Use when the episode id is unknown" gives an explicit trigger condition and implicitly routes the agent away from id-based lookups. It stops short of naming the alternative tool (e.g. memshelf_recall) or stating when this search should NOT be used.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=false), so the bar is lower. The description still adds real behavioral detail beyond them: redaction runs, a digest contract is enforced, and a git commit is produced, plus an explicit statement that derived artifacts are written by a different tool. It does not mention push/publish side effects, but the schema carries those.

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

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

Three short clauses: what it does, what it deliberately does not do, and where the full documentation lives. The purpose is front-loaded and nothing is redundant — a good model of density for a tool with a heavy schema.

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 rich schema plus annotations cover the mechanics. What is missing is onboarding context: the shelf must already exist (the sibling memshelf_init / default $MEMSHELF_SHELF_PATH is only implied), and no pointer is given to the lint/advise steps that normally precede a shelve.

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 description contributes nothing about arguments. The reported 0% schema description coverage is an artifact of the top-level 'params' wrapper having no description; the nested ShelveInput properties are in fact documented at high density (push/publish exclusivity, sync refusal behavior, amend semantics, retention, approx_tokens absent-vs-zero). With the schema effectively doing the work, the baseline of 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 — offloading one closed topic into a durable, indexed episode — with concrete constituents (redaction, digest contract, git commit). It also marks a boundary against memshelf_rebuild ('derived files are not written here'), which helps an agent separate the two. It does not distinguish itself from memshelf_import or memshelf_advise, so it stops short of full sibling differentiation.

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?

'Offload one closed topic' implies the trigger condition (a topic has been completed) and the rebuild reference routes one sub-concern elsewhere, but there is no explicit when-to-use/when-not guidance against the 13 siblings. The reader must infer that this is the write path that precede rebuild/index. Implied usage only.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds meaningful context about what the report contains (standing cost, compression claims, realized savings), but says nothing about cost of computation, staleness, or whether stats are recomputed on demand.

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?

A single front-loaded sentence with no filler; the colon-and-list structure efficiently names the three accounting outputs. Slightly telegraphic ('standing cost vs shelved mass'), but every phrase carries 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 values need not be explained, and annotations plus detailed nested parameter docs cover safety and invocation. For a read-only single-parameter stats tool this is close to sufficient; only the absence of any usage framing keeps it from being complete.

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 reported schema_description_coverage of 0% applies only to the top-level 'params' wrapper; the nested StatsInput properties actually carry rich descriptions covering the $MEMSHELF_SHELF_PATH default, the $MEMSHELF_CONTEXT_WINDOW fallback chain, the 200,000 default, and units in tokens. The description itself contributes no parameter meaning, so the schema is doing all the work.

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 a precisely scoped resource ('the shelf's token economy'), then enumerates the exact metrics returned: standing cost vs shelved mass, claimed compression, realized savings from logged recalls. This is clearly distinguishable from siblings like memshelf_recall, memshelf_search, or memshelf_doctor 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives or complementary tools (e.g. memshelf_recall, which is referenced indirectly via 'logged recalls'). The agent must infer that this is a reporting tool used to inspect token accounting.

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