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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description usefully narrows that by stating files are not overwritten unless force is true, plus enumerating exactly what gets generated. It adds real context beyond the safety flags, but omits any auth/permission requirements or what a partial failure leaves behind.

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?

Four sentences, front-loaded with what it does and what it produces before the interview and guardrail details. Slightly dense but each clause adds information an agent needs to run the interview correctly.

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 7-param mutation tool with no output schema, it covers generation targets, the guarded overwrite, the interview scope, and what the return contains (setup instructions). Only minor gaps remain, e.g. behavior when clients is omitted.

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

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

Schema coverage is already 100%, so the baseline is 3, and the description goes further by mapping the required params to interview questions (name, user, purpose, voice) and clarifying the clients runtimes ('claude-code', 'gemini-cli', or generic template). The force guard is restated for emphasis.

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 — "Initialize a new loom identity from scratch" — and names the concrete artifacts produced (IDENTITY.md, preferences.md, self-model.md), which cleanly separates it from siblings like update_identity, identity, and harness_init.

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?

"From scratch" plus the four-question interview framing makes the use case clear: greenfield identity creation, not editing. It also gives a concrete when-NOT to ask instruction ("do not ask for it") for structural fields, though it never names update_identity as the alternative for existing identities.

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 only cover read-only and closed-world behavior; the description adds genuinely non-obvious context: that the content is written in the third person for non-Art agents, that it encodes a push-back mandate, and that workers are expected to refuse bad work even from Art or Jonathan. That is real behavioral disclosure beyond the annotations, though nothing about cost, size, or precedence rules is given.

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?

Purpose is front-loaded in the first sentence and there is no filler, but the middle clause ('Returns Art's standards, taste, operating constraints, and how Art wants work done') partially restates the opening phrase rather than adding 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 read-only loader with no output schema, four fully documented optional params, and no annotation surprises, the description covers what the tool is and what it returns well enough to call it correctly. It does not say what happens with no arguments, which is the only notable gap.

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 four parameters (role, model, client, project) are already documented with examples and env-var override behavior. The description adds nothing about parameters, 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?

Specific verb (Load) plus a precisely named resource (Art's operating brief/dossier for a worker body), and it enumerates the returned content — standards, taste, constraints, working expectations. The resource is unmistakably distinct from every sibling (memory/knowledge/person tools), so an agent can identify it 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?

It implies the audience — agents that are NOT Art but execute tasks on Art's behalf — which is a useful targeting cue, but it never states when to call it (e.g. at session start, when adopting a role) or what alternatives exist. Usage is inferable rather than stated.

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 (readOnly, closed-world), so the description adds genuine behavior context: chronological ordering guarantees ('time-ordered, oldest first') and the fact that results are never ranked. The 'same block identity injects at boot' note explains a related constraint, though the return shape is not described.

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, front-loaded with the resource definition followed by usage triggers. Efficient, but the heavy jargon slightly reduces immediate parseability for an agent unfamiliar with the domain vocabulary.

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-optional-parameter read tool with annotations but no output schema, the description covers scope, ordering, and usage triggers adequately. It could say more about the shape of an episode entry, but the essentials for correct invocation are present.

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% for the single 'hours' parameter, which already documents the look-back window and default of 24. The description's 'last N hours' restates the same concept without adding syntax or edge-case 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?

The description names a specific resource (the episode tape) and states its scope precisely: events across ALL bodies of this identity within the last N hours. It distinguishes the behavior from a ranking tool ('never ranked'), though the metaphorical framing ('tape', 'bodies', 'sleeves') and lack of explicit sibling routing keep it from 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 two concrete when-to-use moments: mid-session catch-up on what other sleeves did since loading, and a nightly indexing pass. It does not, however, name an alternative tool or state when NOT to use it, so it stops short of full routing 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 readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds that self is excluded when anchoring on `ref` and that `text` is embedded on the fly, but both facts are duplicated verbatim in the schema property descriptions. Useful but adds little beyond structured data.

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 what the tool does, followed by when to use it and the anchoring mechanics. Every sentence earns its place and nothing is padded.

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

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

For a 6-parameter read-only lookup with full schema coverage and no output schema, the description covers purpose, workflow context and anchor selection. The only gap is that it doesn't hint at the return shape (e.g. scored neighbours), which an agent selecting among recall/memory_list might want.

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 six parameters are already fully documented (ref, text, limit, project, category, min_relevance). The description adds only a reinforcing framing of ref-vs-text anchoring, not new syntax or constraint detail, so 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+resource: 'Surface memories semantically near an existing ref or free-form text.' An agent immediately knows this is a semantic-neighbour lookup. However, it does not name or contrast against the obvious sibling (recall), so sibling differentiation is left to 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?

Explicitly names the scenario: 'Use during consolidation/dream workflows to find overlap and dedupe candidates,' and clarifies the two anchoring modes (ref vs text). It stops short of stating when NOT to use it or pointing to `recall` as the general-purpose alternative.

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=true and idempotentHint=true, so the safety profile is partly covered. The description adds genuinely new behavior beyond that: omitting confirm yields a free dry-run preview of what would be deleted. It does not say whether deletion is soft or permanent, which keeps it below 5.

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

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

Three tight sentences, front-loaded with the verb and resource, then modes, then the confirm/safety rule. Every sentence carries information an agent needs, 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?

For a 6-param destructive tool with no output schema, the description covers the important cases: both deletion modes, the confirm gate, and the dry-run return behavior. It omits whether deletions are reversible and any permission requirements, so it is not fully 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value by showing how parameters combine: ref or category+title for single deletion, category and/or project for bulk. That combination logic is the key thing the flat schema cannot convey on its own.

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 (Remove) and resource (memories), and further splits the operation into single vs bulk modes with their parameter combinations. It is clear and precise, but does not differentiate itself from similarly destructive siblings like memory_prune, memory_purge, or memory_archive, so an agent must still guess which deletion tool to pick.

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

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

Gives concrete conditions: single deletion via ref or category+title, bulk via category and/or project scope, and explicitly states that scope deletions require confirm:true while single-target deletions never do. It lacks explicit when-not guidance or routing to sibling deletion tools, keeping it short of a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description corroborates and adds context — 'Re-runnable: overwrites the manifest each time' — and explains how the target path is derived (from clientInfo.name). It stops short of describing failure modes or permission requirements, so not a full 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 purpose, then trigger condition, then constraint, then content guidance. Every sentence carries information an agent needs and there is no redundancy.

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 no-output-schema mutation tool whose annotations cover the safety profile, the description supplies purpose, trigger, constraints, and content expectations. Only minor gaps remain (no mention of validation or error behavior), which is acceptable given the rich 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 coverage is 100%, so the baseline is 3, but the description adds real meaning for `content` by enumerating what the body should cover (tool surface/prefixes, sandbox & filesystem, delegation primitive, scheduling, session search, memory layers, gotchas). This goes beyond the schema's terse 'manifest body (markdown)'.

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 — 'Self-describe the CURRENTLY CONNECTED harness: write its manifest at <contextDir>/harnesses/<key>.md' — and disambiguates from siblings by noting 'you can only describe yourself, not another harness.' An agent can distinguish it from harness_init and identity 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 names the trigger: 'Call this when identity() reports an onboarding block for an unknown runtime,' and the self-only constraint. It routes the agent to the sibling to run first, leaving nothing 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?

Although annotations already declare idempotentHint and destructiveHint, the description adds real substance: skip-exists default vs overwrite:true replacement, the loom-managed marker block and its embedded hash line, and the three re-run outcomes ('no-change'/'created'/'updated'). This tells the agent exactly what is overwritten and when the tool is safe to re-run.

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 and trigger in the first sentence, followed by the conditional `target` behavior. It is dense and the marker/hash detail is verbose, but every clause carries operational information rather than 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 destructive, idempotent write tool with no output schema, the description covers the trigger, idempotency contract, destruction/replacement semantics, the conditional injection path, and the returned status strings — everything an agent needs to invoke and re-invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining the side effect of `target` (it additionally writes a marker-bounded block, typically into CLAUDE.md) and the exact behavior of `overwrite`. This adds meaning the schema's one-line parameter notes do 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?

Specific verb+resource ('Scaffold a harness manifest') with an exact destination path (<contextDir>/harnesses/<name>.md) and template source. It names the triggering signal ('identity() reports a missing manifest') so it is clearly separable from siblings like identity, bootstrap, and harness_describe.

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 when to call it — when identity() reports a missing manifest — naming the sibling that produces the signal. It does not state when NOT to use it or name a direct alternative for existing manifests, so it stops just short of full routing 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing what gets loaded (creed, memories, preferences, self-model) and that it is the mandatory entry-point call, though it does not explain sourcing or ordering of the loaded artifacts.

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

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

Three sentences, front-loaded with the purpose before the emphasized directive. The final sentence is somewhat rhetorical ('who you are and how you should behave') but it reinforces the tool's role rather than wasting space.

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 no-required-param, no-output-schema loader, the description covers purpose, returns, and call ordering adequately, and the schema carries the parameter detail. It is slightly thin on how the optional role/model/client overrides interact, but nothing essential 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%, with all five optional params (role, model, client, people, project) fully documented in the schema. The description adds no parameter meaning, so 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+resource ('Load the persistent identity') and enumerates what it returns (creed, memories, preferences, self-model), which clearly separates it from write-side siblings like update_identity. It does not, however, name the identity-adjacent alternatives (bootstrap, harness_init) an agent might confuse it with.

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 strong, explicit directive: 'Call this tool FIRST before doing any other work,' which tells the agent exactly when to reach for it. It provides no when-not guidance or named alternatives, so it stops short of the top mark.

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 and idempotentHint=true, but the description goes further by naming the actual state change (status set to archived), the downstream effects (excluded from knowledge_recall and knowledge_maintain), and the recovery path (fully recoverable via knowledge_restore). It does not cover permission/auth requirements, which keeps it just short of 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, then layers scope, exclusions, recovery, and alternatives in three tight sentences with no filler. Every sentence carries a distinct decision-relevant fact.

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

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

No output schema, but the description fully covers what changes, what is excluded elsewhere, recoverability, and the sibling alternative needed for merges. 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 coverage is 100%, so both parameters are already documented. The description adds framing by calling 'note' a 'tombstone note' explaining retirement, but adds no syntax or format detail beyond the schema's baseline. 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?

States a specific verb and resource ('Soft-retire a knowledge page: set its status to archived') and explicitly distinguishes itself from knowledge_restore (recovery), knowledge_supersede (dedup merges), and generic deletion. An agent can identify the exact operation without opening the schema.

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

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

Explicit when-to-use ('Use this instead of deletion when the page may need to be audited or recovered') and when-to-use-something-else ('For deduplication merges, prefer knowledge_supersede'). Names the alternative and the selecting condition, leaving nothing 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 only declare the safety triad (readOnly=false, destructive=true, openWorld=false); the description adds genuinely new behavior: replace-writes snapshot the displaced body, retention is newest-kept and capped, and restore snapshots before overwriting so it is recoverable. The 'never destructive' phrasing sits in mild tension with destructiveHint=true, though the tool does mutate the page body, so the annotation is a conservative default rather than a true conflict. The cap size and listing pagination are left unspecified.

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

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

Three sentences, front-loaded with the resource model, then the mechanism, then the mode matrix — no filler. The parentheticals are dense but each carries real information; the mode sentence is slightly compressed and requires a careful read.

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 correctly describes what each mode returns (metadata-only listing vs full body). Coverage of the mutation path and its reversibility is strong. Remaining gaps are the retention cap value and the absence of any sibling routing, so it is not fully 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?

Schema coverage is 100%, so parameter meanings are already documented and the baseline is 3. The description adds value beyond the schema by explaining the combination semantics (revision_id requires a slug; restore requires revision_id) and by clarifying that the slug-only listing returns metadata while the revision_id read returns a full body.

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 ('Body-revision history for a knowledge page') and frames the tool's role as 'the recovery surface', which separates it from siblings like knowledge_write, knowledge_restore, and memory_history. The snapshot mechanism sentence makes the resource model unambiguous.

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 mode matrix keyed on arguments: slug alone lists metadata, slug + revision_id reads one body, restore: true writes it back. That is clear when-to-use guidance. It does not name a sibling alternative (e.g. use knowledge_write to produce revisions) or state when not to reach for this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description goes well beyond them: it explains that cold/expansion ranking uses the shared hit_count/last_accessed aggregate rather than a per-identity split (and why), that only the full loom server runs branch (4) while the knowledge-only server skips it, and that the output is 'a report, not enforcement.' That is substantive behavioral context beyond the 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?

Purpose is front-loaded, which is good, but the body is a dense wall of nested parentheticals and self-referential asides that is hard to scan. The content largely earns its place given the four-branch scope, but the structure could be tightened into clearly delineated branches.

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

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

No output schema exists, so the description carries the full burden of describing what the report contains, and it does so thoroughly via the four named branches plus the ranking caveat and the server-variant note. An agent knows what it will get back and how to interpret ambiguous cases (e.g., ours/ with internal sourcing is not a misfile).

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 cold_days, thin_body_threshold, and expansion_hit_threshold with defaults and bounds. The description adds no parameter syntax or edge-case meaning beyond what the schema provides, so the baseline 3 is correct.

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 immediately: 'Read-only health report for the knowledge store,' then enumerates four concrete branches (expansion candidates, cold pages, misfile audit, person-page check). An agent can distinguish this from knowledge_recall, knowledge_verify, and knowledge_history 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?

Usage is implied by the branch descriptions, and 'Pair with knowledge_write to act on findings' is a useful action hint. However, there is no explicit statement of when to invoke this versus siblings like knowledge_verify or memory_audit, and no exclusions are drawn regarding tool selection (only interpretation of the report).

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?

Despite annotations marking this destructive, the description adds substantial operational detail: citations are re-parented and deduplicated by a specific tuple, verified_at uses MAX across pages, losers are archived with tombstones and supersession pointers, and loser bodies are returned for review. This is well beyond annotation coverage.

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 action, then behavior, then alternatives. The density is justified by a destructive multi-step operation, and every sentence contributes either scope, behavior, or routing 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 complex destructive merge with no output schema, the description covers citation consolidation, verified_at selection, loser archival, tombstone behavior, returned bodies, and the optional append flag. An agent has enough to call it correctly and anticipate consequences.

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

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

Schema coverage is 100%, so the schema already documents all five parameters, including hard_delete_losers and append_loser_bodies. The description mentions append_loser_bodies and the result-body behavior, but adds little parameter meaning beyond what the structured schema provides.

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 — consolidate knowledge pages into one canonical target — and explicitly contrasts with knowledge_supersede. An agent can distinguish this from siblings without opening the schema.

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

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

Gives explicit routing: use knowledge_write first if the target body needs updating before merging, and use merge rather than knowledge_supersede when consolidating multiple pages. It names both the prerequisite and the alternative 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?

Annotations only declare the coarse profile (mutating, non-idempotent, not destructive). The description adds substantive behavior beyond that: a supersessions pointer old→new is written on rename unless leave_pointer=false, collisions are rejected rather than merged, and batch modes are atomic with rollback on any missing slug.

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 and the in-place guarantee, then structured as three numbered modes. Information-dense with little waste, though the long single paragraph could be trimmed slightly around the mode labels.

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 7-parameter, zero-required-parameter mutation tool with no output schema, the description covers all three invocation shapes, the atomicity guarantees, and the cross-tool escape hatch. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by mapping parameters to modes (which combinations are valid per mode) and clarifying leave_pointer's default-on pointer semantics and the collision behavior of new_slug.

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 (re-key/re-domain) and resource (knowledge page), and explicitly scopes it in place: 'same row, same uuid, citations and verification history preserved.' It also names the sibling it is distinguished from (knowledge_merge), so an agent can route 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?

Enumerates three concrete modes with the exact parameters each requires (slug + new_slug/new_domain; slugs + new_domain; from_domain_prefix + to_domain_prefix). It states the negative condition explicitly: a colliding new_slug is rejected, so use knowledge_merge instead.

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 declare destructiveHint=true and readOnlyHint=false, so the safety profile is already covered. The description goes well beyond that by disclosing citation cascading, the archive-first guard, whole-batch atomicity on a mixed list, the confirm gate, and that supersession pointers are deliberately preserved. This is rich behavioral context an agent needs before calling an irreversible 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 verb and appropriately dense, with each sentence carrying actionable information. There is mild redundancy in restating the archive-first constraint twice ('rejects any page that is not already archived' and 'All slugs must be archived; a mixed list...'), which is emphatic but slightly repetitive.

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

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

No output schema exists, and the description nonetheless covers the mutation's effects (hard delete, cascade, preserved supersession pointers), failure behavior, and the safety gate. For an irreversible two-parameter tool, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema documents both parameters, including that all slugs must be status=archived and confirm must be true. The description mostly reinforces this but adds real meaning: the batch-level rejection rule when a mixed list is supplied and the citation cascade triggered by the slugs. Limited to elaboration rather than new format/syntax detail, so not a full 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?

Specific verb (hard-delete) plus resource (archived knowledge pages) with explicit scope including citation cascade. It also distinguishes itself from the sibling it depends on (knowledge_archive), so an agent can tell them apart 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?

States the prerequisite ('call knowledge_archive first'), the intended use ('clean up tombstoned cruft after merge/supersede workflows'), and the exclusion ('not for retiring active pages'). Both the when-to-use and when-not are 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?

Annotations are sparse (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries the burden and does: it discloses the hidden write side-effect (stamping last_accessed/hit_count, and that index mode does not stamp), the archived-page exclusion, and the size-guard degradation path with its recovery instruction ('recall by slug to read them'). This also explains why readOnlyHint=false despite a read-shaped 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 purpose, then scope, then tier behavior, then routing advice — a logical order with no filler sentences. It is dense and slightly packed into a single block, but every clause carries operational 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?

With no output schema, the description still describes return shapes (compact slug/domain/snippet index entries vs. full pages with citations) and the degradation behavior when results overflow. Nothing an agent needs to call this correctly — defaults, precedence, exclusions, side effects — 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 real semantics beyond it: slug's precedence over query/domain/limit, the detail tier defaults tied to whether a query is present, and the meaning of the access stamp per tier. sort_by_verified gets no narrative treatment, but the schema's own text covers 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?

States two specific verbs (LIKE search over title/body/domain; exact fetch by slug) against a named resource (the knowledge store). It also carves out scope explicitly with 'Never surfaces archived pages', distinguishing it from knowledge_archive/knowledge_history siblings.

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 when-to-use routing: 'Prefer slug over query when you know the page', plus default behavior for query vs. browse ('full when a query is given, index when browsing without one'). It even explains why slug beats query (cross-reference false hits), which is the kind of reasoning an agent needs to choose 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 write, idempotent, non-destructive. The description adds real value beyond them: it names exactly what is mutated ('clears the archive flag and tombstone note') and the downstream effect ('becomes visible to knowledge_recall and knowledge_maintain'). It omits failure behavior (slug not archived / not found) and auth requirements.

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 sentences, front-loaded with the action, each adding distinct information (action, mutation detail, downstream visibility). No filler or repetition.

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

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

For a one-parameter state-flip with annotations covering the safety profile and no output schema, the description covers action, mutation, and effect. It stops short of stating what happens on an unknown or already-active slug, which an agent might need.

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% for the single slug parameter, so the schema already carries the meaning. The description only frames which pages qualify ('previously archived'), adding no syntax, format, or id-vs-slug guidance. 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 (restore) and resource (previously archived knowledge page) plus the resulting state (active). An agent can tell this apart from knowledge_archive, knowledge_supersede, or knowledge_purge without opening the schema.

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

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

Usage is implied by 'previously archived knowledge page', which tells the agent the precondition, but there is no explicit when-to-use statement, no exclusion, and no named alternative (e.g. when to prefer restore vs supersede vs re-write). Adequate but with clear gaps.

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 readOnlyHint=false and destructiveHint=false, and the description does not contradict them: it clarifies that the old page is archived (not deleted) and left with a tombstone pointing to new_slug, which is genuinely added context about what state changes. It stops short of saying the action is reversible (e.g. via the sibling knowledge_restore) or what auth is needed.

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?

Four tight sentences, front-loaded with the effect, then the mechanism, then a concrete call example, then the postcondition. Nothing is repeated and no sentence 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?

Covers effect, precondition, sequencing and side effects for a mutation tool with no output schema, which is most of what an agent needs. Failure modes (e.g. what happens if new_slug does not exist) and the undo path are unstated.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by disambiguating the roles in prose ('old_slug=loser, new_slug=canonical') and by restating the existence precondition for both, which maps directly onto the two required parameters. The optional note parameter is left 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+resource+consequence ('Mark one knowledge page as superseded by another, then archive the old page') and names the workflow role ('the dedup-merge primitive'). It also names the sibling it pairs with (knowledge_write), so an agent can place it in the pipeline without opening the schema.

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

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

Gives explicit sequencing ('write the canonical page with knowledge_write, then call knowledge_supersede') and a precondition ('Both pages must already exist'). It does not, however, say when to prefer this over the sibling knowledge_merge, which is the most likely confusion the agent will have.

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 only declare the safety profile (non-read-only, non-destructive, closed-world). The description adds substantial behavioral context beyond that: the verifier is server-resolved and never a settable field, the note is append-only, batch mode uses a shared timestamp, and rejected inputs fail whole rather than partially.

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 and scope, and every clause carries information. It is dense and run-on with heavy em-dash nesting, which slightly reduces scannability, but there is little filler to cut.

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

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

With no output schema, the description still covers both operating modes, rejection behavior, attribution semantics, and body-preservation guarantees — enough for an agent to invoke it correctly in either single-page or batch form.

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

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

Schema coverage is 100%, so the schema already documents all seven parameters; the description reinforces meaning and adds cross-parameter rules (slug/slugs mutual exclusivity, note and freshness_anchor being single-page only) plus the server-side verifier identity that is not a parameter at all.

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 ('Stamp a knowledge page as verified') with precise scope ('WITHOUT touching its body') and enumerates what it sets. It explicitly contrasts itself with the sibling knowledge_write, so an agent can distinguish it 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?

Names the alternative explicitly ('use it (never knowledge_write) to record "claims still hold"') and states the selecting condition. It also gives when-not conditions: archived pages are rejected, and a batch with any unknown slug is rejected whole, with batch/single-page modes delineated.

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

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

Annotations declare destructiveHint=true and idempotentHint=false; the description corroborates destruction ("body REPLACES by default") and adds non-annotation behavior: citation dedup, the epistemic gate, and the shared-readership constraint. The phrase "safe to re-send" sits in mild tension with idempotentHint=false, though in context it is scoped to citation dedup rather than the whole write, so this is a clarity wart rather than a contradiction.

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 and structured into class labels and a gated bullet list, so it scans well. It loses a point for redundancy: the repo-on-world-page rule is stated in the §E1 bullets, in the NOTE, and again in the citations/source_kind schema descriptions.

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 9-parameter, high-complexity mutation tool with no output schema, the description covers the class model, the epistemic gate, and audience expectations thoroughly. It is silent on what a successful upsert returns and on any auth/attribution failure modes (beyond the created_by note), which is the main remaining gap.

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 contributes real semantics beyond the schema: the relationship between domain class and citation classification (the §E1 gate), the world-filing test for `domain`, and the intended audience for `body`. Only `version`, `created_by`, and `freshness_anchor` get no additional description-level treatment.

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?

Opens with a specific verb+resource ("Upsert a knowledge page by slug") and immediately splits the resource into its two classes with concrete domain examples. An agent can distinguish this from knowledge_supersede, knowledge_move, knowledge_merge, and remember without opening any schema.

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

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

Gives explicit routing rules: world/ vs ours/ with a stated filing test ("knowledge must be true independent of Jonathan"), plus a named alternative for a whole class of inputs ("A personal reflection or working-out-loud note belongs in `remember`, not here"). That is when-to-use, when-not, and the alternative, all spelled out.

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

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

Beyond the annotations (which only declare idempotent, non-destructive, closed-world), the description discloses downstream side effects the agent could not otherwise infer: archived memories are excluded from recall, list, audit, and find_similar, and remain fully recoverable. This is exactly the kind of behavioral context that annotations cannot express.

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 filler, and the core mechanism (tombstone, not delete) is front-loaded ahead of the routing advice. Every clause 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 mutation tool with no output schema, the description covers what the operation does, what it excludes, how to reverse it, and when to prefer it over forget. Combined with the annotations covering safety semantics, 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 description coverage is 100% with 4 well-documented parameters, so the schema carries the burden and a baseline of 3 applies. The description's mention of the 'tombstone' loosely gestures at the note parameter but adds no syntax, format, or interaction detail 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?

The description names a specific verb and resource ('soft-retire a memory'), and immediately clarifies the mechanism ('move it to the archive tier with a tombstone instead of deleting it'). This distinguishes it from forget, memory_prune, and memory_restore without the agent needing to open any other 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 gives an explicit alternative and the condition selecting it: 'Use this instead of forget when the memory may need to be recovered or audited later.' It also names the inverse operation (memory_restore) for un-doing the action.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description's 'Read-only' merely restates that. It does add that the report is 'one-shot' (single call, no follow-up pagination implied) and discloses the finding categories, which is mild extra context, but says nothing about cost, scanning scope, or that thresholds change what is reported.

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 filler. The report content is front-loaded and the follow-up pointer is placed after, so an agent gets the essential information first.

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, and the description compensates well by enumerating the five sections the report returns, so an agent knows what to expect. Safety is covered by annotations and all three parameters are documented. Only the absence of any hint about scan cost or result size on large stores keeps it short of 5.

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%, with each parameter's meaning, bounds, and default documented in the schema itself. The description references thresholds conceptually ('untouched beyond threshold', 'above similarity threshold') but adds no syntax or units beyond what the schema provides, 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?

The description states a specific verb+resource ('One-shot health report for the memory store') and enumerates exactly what the report contains: totals, category breakdown, stale memories, near-duplicate pairs, and expired refs. This clearly separates it from siblings like memory_list (raw listing) and find_similar (single-purpose duplicate 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?

It points to the follow-up action path ('pair with forget/update to act on findings'), which is genuinely useful routing, but never says when to run this audit versus memory_list, find_similar, or memory_prune, and gives no exclusions. 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=true, but the description adds substantial context: how revisions are created (update() snapshots the displaced body before overwriting), and critically that the return shape is mode-dependent — metadata only for listing vs full content for a single read. This is behavioral detail the annotations cannot convey.

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

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

Four tight sentences, front-loaded with the core purpose and then the mechanism, modes, and routing. No filler; each clause carries information (how data arrives, two modes, the alternative tool).

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 carries the return-value burden and does so: listing returns metadata (id, op, replaced_at, char count) and single-read returns full content. Combined with the mode rules and the restore pointer, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented (baseline 3). The description adds real semantic value by mapping parameter combinations to behavior: 'ref alone' vs 'ref + revision_id' determine listing vs single-snapshot read, and it clarifies what the listing returns. It stops just short of adding syntax/format detail 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+resource ('Body-revision history for a memory') and immediately clarifies it is the read surface of a write/read pair with update(). It distinguishes itself from memory_revision_restore by name, so an agent can tell the read from the restore tool 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?

Explicitly describes the two invocation modes (ref alone lists, ref+revision_id reads one) and names the correct alternative for restoring ('use memory_revision_restore'). This covers both when to use this tool and when to route elsewhere.

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?

readOnlyHint=true and openWorldHint=false already establish the safe, local read profile, and the description is consistent with that. It adds the useful behavioral note that this is a browse/enumeration path rather than a retrieval-ranked path, but says nothing about ordering, pagination, or return shape.

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 compact sentences with the key differentiator (non-semantic browsing) front-loaded, followed by filters and use cases. No filler, though the final use-case sentence is the weakest.

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 simple, annotated, zero-required-parameter read tool with a fully documented schema and no output schema, the description covers purpose, filters, and usage adequately. Return ordering and pagination behavior are the only notable omissions.

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 all three parameters (limit, project, category) are documented in the schema itself. The description only echoes category/project filtering and adds no syntax, matching, or defaulting detail beyond what the schema already provides.

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?

Clear verb+resource ('Lists memories') with an explicit scope qualifier ('without semantic search') and the filter dimensions it supports. It distinguishes itself from the semantic-search siblings by mode, though it never names recall or find_similar 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?

'Useful for auditing, maintenance, and discovery' gives implied usage contexts, and 'without semantic search' hints the alternative is a semantic tool. But it never says when NOT to use it (e.g., versus memory_audit or recall), leaving the agent to infer the 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 flag destructiveHint=true, and the description adds substantial detail beyond them: losers are archived with a tombstone plus a supersession pointer, the target's times_seen absorbs each source's count, and hard_delete_losers defaults to false. It also warns that append_loser_bodies is off by default so the agent can review returned loser bodies first — exactly the pre-destruction context an agent needs.

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

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

Four sentences, all load-bearing, with the core action front-loaded before the mechanism, the alternative comparison, and the parameter caveats. No filler.

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

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

No output schema exists, and the description covers the gap by noting loser bodies are returned in the result for review. Combined with the mechanism explanation and destructive-operation semantics, an agent has everything needed to invoke it safely.

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 every parameter including defaults, so the baseline is 3. The description reinforces the survivor/loser roles of target_ref and source_refs and the times_seen merging behavior, but adds no syntax or format detail the 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?

States a specific verb and resource ('Consolidate 2+ memories into one canonical row') and explicitly distinguishes itself from siblings memory_archive/supersede (N:1 instead of 1:1) and forget/archive on a duplicate pair. An agent can route to it 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 trigger context ('Acts on a memory_audit duplicate finding') and the alternatives it supersedes ('Unlike forget/archive on a duplicate pair, this consolidates both sides into one row instead of just discarding one'). When-to-use and when-not-to-use are both 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful state context beyond that: results are drafts, are newest-first, and are explicitly excluded from recall/memory_list/find_similar/boot digest. It stops short of return format or pagination details, keeping it at 4.

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 sentences with zero waste; the core purpose and ordering are front-loaded, followed by scope exclusions and next-step actions. Every sentence 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?

For a zero-parameter read tool with no output schema, the description covers purpose, ordering, lifecycle state, and routing to memory_ratify/memory_reject. The only gap is the shape/fields of a returned proposal, which the absence of an output schema leaves unspecified.

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 per the rubric. There is nothing for the description to disambiguate and it introduces no misleading parameter assumptions.

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 (List), resource (pending proposals in the capture-propose queue), and scope (newest first). It also positively distinguishes itself from sibling read tools by declaring these drafts do not appear in recall, memory_list, find_similar, or the boot digest.

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 these as DRAFTS awaiting ratification and names the two follow-up alternatives with their conditions ('Ratify one with memory_ratify or discard it with memory_reject'), plus the exclusions from other listing tools. An agent knows exactly when this tool applies and what to do next.

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 only cover the safety profile (non-read-only, non-destructive, closed-world). The description adds the critical behavioral fact that the draft is invisible to recall, memory_list, find_similar and the boot digest until ratified, and that validation is deferred to ratify time so drafts may be rough. That is exactly the context an agent cannot infer from 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?

Three sentences, front-loaded with the core action, then the invisibility constraint, then the when-to-use rule. No filler and every clause 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?

Covers the full propose→ratify lifecycle, visibility semantics, and validation timing for a 7-parameter write tool with no output schema. It stops short of describing what staging returns (e.g. a proposal id) or the default retention of a draft, which would round it out.

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% (including the detailed category enum and ttl format), so the schema carries the parameter burden. The description adds only an indirect hint about content validation timing and nothing about ttl, source, project, or metadata semantics; 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 (stage) and resource (draft memory in the capture-propose queue) plus the downstream lifecycle step (ratification). The contrast with memory_ratify and with an 'authored memory' makes it distinguishable from siblings like remember and memory_proposals 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 the triggering scenario ('a background lane wants to suggest a write without committing it') and the gating condition (human/Art reviews and ratifies before it becomes canon). It also routes away from the direct-write path by stating a proposal is NOT an authored memory.

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=true and idempotentHint=true, so safety profile is covered. The description adds genuine context beyond that: the deletion criterion (TTL elapsed, i.e. expired memories only, not arbitrary ones) and the dry_run preview path. Missing detail on what happens to already-pruned or non-expired memories.

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 waste; the destructive action and its scope lead, followed by the safe-preview escape hatch. Every clause 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 destructive mutation tool with full annotation coverage and 100% schema documentation, the description supplies the essential scope and preview guidance. It lacks only edge-case behavior (what counts as expired, what happens if nothing matches), which keeps it short of a 5.

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 both parameters are fully documented in the schema, establishing baseline 3. The description only echoes dry_run and says nothing about stale_days, so it adds no 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 (Remove) and resource (memories) with a clear qualifying scope (TTL elapsed / expired). This distinguishes it from siblings like forget and memory_archive, though it doesn't name those alternatives 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?

Provides the dry_run preview guidance, which is useful operational advice, but gives no 'when to use this vs. forget/memory_archive' routing. Usage context is implied by the TTL scope rather than stated.

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

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

Beyond the annotations (which already declare mutation, idempotency, and non-destructiveness), the description discloses the failure mode ('refused with its typed reason and stays pending') and success side effects ('memory becomes recallable and the proposal is removed from the queue'). This is rich behavioral context an agent needs to reason about outcomes.

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 and the override behavior follows logically. Four sentences with one rhetorical line ('This is the gate') that earns modest emphasis but could be trimmed without loss.

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 whose annotations already carry the safety profile and which has no output schema, the description covers the essential lifecycle: load, override, validate, commit, failure handling, and queue effects. 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 every parameter including the override fields. The description adds a collective framing ('applies any optional overrides (your edits on accept)') but no new per-parameter syntax or constraints, so the baseline 3 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 and resource: 'Ratify a pending proposal into a REAL memory', and names the pipeline relationship to remember. An agent can distinguish this acceptance action from siblings like memory_propose and memory_reject without opening any schema.

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

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

The description gives clear context ('This is the gate: no proposal becomes canon without it') and implies this is the accept step for a pending proposal. It does not explicitly name the alternative rejection path (memory_reject) or state when-not to use it, so it falls short of exhaustive 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 destructiveHint=true and idempotentHint=true, but the description adds the important detail of what exactly is destroyed (the staging row) and what is not affected (no memory is written). It omits idempotency behavior on repeat rejection, keeping it short of 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?

Three tight sentences with zero filler; the core action and its non-commitment guarantee are front-loaded before the usage hint.

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-param destructive tool with no output schema, the description covers action, effect on storage, and selection guidance. It lacks only error/permission behavior (e.g., rejecting a non-pending id), which is a minor gap.

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?

Single parameter with 100% schema description coverage ('Proposal id (from memory_proposals)'), so the schema already carries the semantics. The description adds no syntax or sourcing detail beyond that, matching the baseline for full coverage.

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 ('Discard a pending proposal') and immediately scopes the effect ('Deletes the staging row; no memory is written'). An agent can distinguish this from memory_propose/memory_ratify purely on the 'without committing it' framing.

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 this for drafts that should not become canon' gives a clear selection condition for when to reject rather than ratify. It stops short of naming memory_ratify (or memory_prune/forget) as the explicit alternative, so the routing is implied rather than stated.

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 mutation (readOnlyHint=false), idempotency, and non-destructiveness, so the bar is lower. The description still adds real value by naming the concrete state changes ('clears the archive flag and tombstone note') and the downstream effects (visible to recall, list, audit, find_similar), which the annotations 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?

Three short sentences, front-loaded with the action and scope, then the mechanism, then the effect. No filler and nothing repeated from the name or annotations.

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

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

No output schema exists, so the description carries the return-value burden, and it does describe the resulting state reasonably well. It stops short of covering failure modes (e.g. restoring an already-active or nonexistent memory) or which identifier combination is required, leaving minor gaps for a mutation tool.

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

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

Schema description coverage is 100%, so all three parameters (ref, title, category) are already documented in the schema. The description adds no information about how ref relates to title/category or which identifier form to prefer, so the baseline 3 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?

The description states a specific verb and resource ('Restore a previously archived memory to the active set'), which is unambiguous about what the tool does. It implicitly pairs with memory_archive but never explicitly distinguishes itself from memory_revision_restore, knowledge_restore, or person_restore, so an agent must infer which restore variant applies.

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 only implied by the phrase 'previously archived memory' – the agent can infer this applies to archived items, but there is no explicit when-to-use, no prerequisites, and no routing between this and the other restore tools (memory_revision_restore, knowledge_restore, person_restore) in the sibling set.

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 description discloses a genuinely useful behavioral trait beyond the annotations: the current body is snapshotted first, making the restore recoverable. However, 'restore is never destructive' sits in tension with destructiveHint=true — the annotation warns the agent of a state-changing overwrite while the prose reassures it away, which could lull an agent into treating the call as harmless.

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: purpose and reversibility first, prerequisite second. Every clause earns its place and nothing is buried.

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 two-parameter tool with full schema coverage and no output schema, the description covers purpose, reversibility, and the required upstream lookup. Only minor gaps remain, such as what happens to prior snapshots over time or whether the restore invalidates the revision, which an agent could reasonably want to know.

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

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

Schema description coverage is 100% and both parameters are documented there, including the note that revision_id comes from the memory_history listing. The description restates that source but adds no format, validation, or edge-case detail (e.g., behavior when revision_id is stale), so the baseline 3 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?

The description states a specific verb and resource ('Restore a snapshotted memory body back onto the memory') and scopes it to a revision snapshot, which separates it from the archive-oriented sibling memory_restore. It stops short of naming that sibling or stating the distinction explicitly, so an agent must infer it from wording alone.

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

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

It gives an explicit prerequisite and routes the agent to a named alternative ('Use memory_history to list revision IDs before calling this'), which is exactly the kind of directional guidance that aids tool selection. There is no stated when-not-to-use case (e.g., when memory_restore or memory_merge is preferable), so it falls short of a 5.

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

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

Annotations only declare readOnlyHint and openWorldHint=false; the description adds real behavioral context: the exact return envelope, that a missing card is a non-error {found: false}, and the freshness marker vocabulary ([ok], [unverified], [STALE <n>d]) with a warning not to trust stale data. That is substantial disclosure beyond what the annotations 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?

Front-loaded with the verb and resource, then tight sentences on the return shape and the missing-card case. Efficient overall, though the phrase 'where fields carry a freshness marker' is awkwardly worded and briefly obscures which fields it refers to.

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 must describe the return, and it does: it lists the response keys, explains the not-found case, and defines the freshness markers. It is close to complete for a single-read tool, missing only sibling routing.

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%, with both 'slug' (with format example) and 'include_archived' fully documented in the schema. The description adds nothing about either parameter, so the baseline 3 is correct.

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

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

States a specific verb and resource ('Read one person card') and enumerates the returned fields, so the agent knows this fetches a single entity rather than a list. It never names person_list as the alternative, so the distinction from its closest sibling must be inferred from the word 'one'.

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 rather than stated: the tool is for retrieving a single card, and the note that a missing card returns {found: false} rather than an error tells the agent how to interpret a miss. There is no explicit when-not-to-use guidance or routing to person_list, person_history, or person_verify.

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

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

Adds substantial behavior beyond the annotations: it is a soft retire (not a hard delete), it writes a tombstone capturing who/when/why, the card drops out of identity's room block and person_list, and it rejects writes until restored. This is exactly the reversibility/scope context the readOnlyHint=false / destructiveHint=false annotations leave open, and it is consistent with them.

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 with zero filler; the core action is front-loaded and the consequences follow. Every clause 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?

No output schema, and the description adequately covers what the operation does to the card and how to reverse it. It does not describe any confirmation or response behavior, but for a reversible mutation whose safety profile is already carried by annotations, nothing essential 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 both "slug" and "reason" are already documented. The description's "who, when, why" framing loosely reinforces the reason parameter but adds 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 ("soft-retire a person card with a tombstone") and distinguishes itself from the sibling reverse operation by naming person_restore. An agent can tell it apart from person_restore, person_write, and forget without inspecting schemas.

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 reversibility path ("until person_restore") is mentioned, implicitly routing to a sibling, but there is no explicit when-to-use/when-not guidance versus alternatives like person_prune or forget. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: every change snapshots the previous card and only the newest 10 revisions are retained, which tells the agent about the retention window and what data is exposed.

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 packed sentences with zero filler. The purpose and ordering are front-loaded, followed by behavior and the handoff to the sibling tool; every clause 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 read-only listing tool with one fully documented parameter, the description covers purpose, ordering, returned fields, retention limit, and the restore path. No output schema exists, and none is needed since the fields are enumerated inline.

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?

Single parameter with 100% schema description coverage; the slug format is fully documented in the schema. The description adds no parameter-level detail, so 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+resource: 'Revision history of a person card', with ordering ('newest first') and the exact fields returned (id, op, replaced_at). It is clearly distinguishable from siblings like person_revision_restore and person.

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 routes to the alternative: 'Use person_revision_restore to put one back,' naming the sibling and the condition that selects it. No explicit when-not and no prerequisites stated, so it falls short of a full 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?

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. With no output schema, the description earns credit by disclosing the return shape (slug, name, archived, updated, synthesized_at, stale/unverified counts, memories_since_synthesis) and explaining the derived semantics of the last field.

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

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

One front-loaded sentence that starts with the verb and resource; nothing is wasted. The trailing parenthetical is dense and slightly tangled, which costs it the top score.

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 list tool with one optional flag and no output schema, the field enumeration plus the memories_since_synthesis explanation covers the main gap an agent would otherwise face. Ordering is the only notable omission, and it is minor.

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

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

Schema description coverage is 100% and the single optional parameter include_archived is fully documented in the schema ('default false'). The description adds nothing about it, which is the expected baseline 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?

States a specific verb and resource ('List person cards') and enumerates the returned fields, so the agent knows exactly what this produces. It does not, however, distinguish itself from adjacent siblings like person or person_history, leaving that routing to 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?

There is no explicit when-to-use or when-not-to-use statement and no named alternative, but the parenthetical about memories_since_synthesis implies a real workflow ('how the consolidation lane finds summaries that have fallen behind'). That is implied usage rather than real 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 readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The phrase 'fields intact' adds useful context that field values are preserved rather than reset, but nothing is said about error behavior for already-active cards or permission requirements.

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 the action, target state, and preservation guarantee — 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 one-parameter, non-destructive mutation with no output schema and full annotation coverage, the description supplies everything essential. Minor gaps (idempotency, failure modes) are not strictly needed here.

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% with a single, well-documented slug parameter including format and example, so the schema does the heavy lifting. The description adds no parameter-level detail beyond what the schema already provides, matching the baseline 3.

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?

Names a specific verb (reactivate) and resource (archived person card), making it clearly the inverse of person_archive and distinguishable from person_revision_restore (a different kind of restore). It stops short of explicitly naming those siblings, but the purpose is unambiguous.

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 strongly implied: call this when an archived person card must be brought back. However, it never states preconditions (e.g., card must currently be archived) or disambiguates from person_revision_restore, which also restores person-related state.

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 description adds real context beyond the annotations: it snapshots the current card before overwriting and restores the card plus its synthesized_at, and archive state is untouched. However, the claim 'it is never destructive' sits in tension with the declared destructiveHint=true; it is defensible only because the snapshot makes the prior state recoverable, and the description does plainly state that the card is written.

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 sentences, zero filler, and the action is front-loaded before the safety mechanism and the scope boundary. Every clause (revision source, snapshot, archive invariance) carries information an agent needs.

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

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

For a two-parameter mutation tool with full schema coverage and no output schema, the description covers purpose, the safety mechanism, and a scope boundary. It stops short of addressing failure modes (unknown or mismatched revision_id) or the return payload, so it is strong but not exhaustive.

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 slug format and revision_id's origin in person_history are already documented in the schema. The description reinforces the revision provenance but adds no new syntax, constraints, or edge cases (e.g. what a revision_id from a different person does). Baseline 3 applies when the schema carries the parameter documentation.

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 uses a specific verb and resource: it puts a person card back to a revision, explicitly sourcing that revision from the sibling tool person_history. It also carves out scope against a near-neighbour by stating 'Archive state is unchanged', which separates it from person_restore, though it never names that sibling 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?

Usage is only implied: the agent can infer this is for reverting a card to a prior version, and the archive-state clause hints at a boundary condition. There is no explicit 'use this when / use X instead' routing against person_restore or person_write, so the agent must infer the selection rule.

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

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

Adds real behavioral context beyond the annotations: values are not changed (so it is a metadata-only mutation despite readOnlyHint=false), the operation is all-or-nothing with unknown fields rejecting the call, and a failed check is recorded by simply not stamping. It does not cover idempotency on repeat stamps or permission requirements.

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 action and with zero filler. The opening phrasing 'Stamp where fields on a person card as checked' is grammatically awkward but still compact.

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, it discloses the mutation scope, atomicity/error behavior, and the negative case (failure = no stamp). Missing only repeat-call idempotency and permission context, which keeps it short of a 5.

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 baseline is 3. The description adds the verified_at default of now and the optional nature of source, but says nothing about slug semantics or the meaning of 'where field names' 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: stamp 'where fields on a person card' as checked, setting verified_at and source. It is clearly distinct from value-mutating siblings like person_write, though it never names the closest analog knowledge_verify to disambiguate.

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 (call it after a field has been checked) but the description never states when to prefer this over person_write or knowledge_verify/person_write alternatives, nor any prerequisites. Adequate but with a clear routing gap.

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 only carry the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description goes well beyond that, disclosing merge depth ('one level deep'), that a null field is removed, that merge:false overwrites the card wholesale, that passing summary has the side effect of moving synthesized_at, and that reserved keys are rejected. That is exactly the extra behavioural context annotations don't 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?

Front-loads the core identity of a person card, then layers merge semantics, then side effects and restrictions. It is a single dense passage rather than clearly delimited points, which makes it slightly harder to scan, but essentially no sentence is wasted.

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

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

For a 7-parameter mutation tool with nested objects and no output schema, the description covers identity, merge behaviour, replacement semantics, side effects and access restrictions. The one gap is that, with no output schema present, it never says what a successful write returns.

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

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

Schema coverage is 100%, so the schema already carries the baseline. The description nevertheless adds real meaning — merge's default and one-level merge semantics, null-as-delete for nested fields, and what passing summary signifies ('I re-read the evidence and this is still right'). It adds value on top of structured data rather than restating 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?

States a specific verb+resource ('Write a person card') and immediately scopes it against near neighbours by defining what a card is not — not a knowledge page, not the memories. An agent can distinguish it from knowledge_write and remember without opening the schema.

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

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

Gives concrete when-not guidance ('not a knowledge page, not the memories: those stay the evidence') and an explicit audience restriction ('Worker bodies must not call this — cards are written by Art'). It stops short of naming the alternative tools to use instead, so routing is implied rather than spelled out.

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 description adds substantial behavioral context beyond the annotations: MMR re-ranking with a default λ=0.7, the guarantee that the top result is the most relevant, and the effect of diversity: 0. However, it never addresses the readOnlyHint=false signal — a retrieval tool that apparently mutates state (e.g., access tracking) without saying so — which is a real, if non-contradictory, gap.

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, then usage, then ranking behavior. Well-sized overall, though the first two sentences are slightly redundant ('Retrieve memories...' / 'Returns matching memories from the persistent store').

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 5-parameter retrieval tool with no output schema, the description reasonably covers purpose, usage trigger, and notable ranking behavior. The main omission is the state effect implied by readOnlyHint=false; the return shape is only loosely described.

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 baseline is 3 and the schema already documents limit, query, project, category, and diversity. The description reinforces diversity semantics (MMR/λ) and the guaranteed-top-result behavior, but adds little parameter meaning that the schema does not already carry.

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

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

States a specific verb + resource ('Retrieve memories relevant to a query or topic') and clarifies the source ('persistent store'). The purpose is unambiguous, but it offers no differentiation from closely related siblings such as find_similar, memory_list, or knowledge_recall, which an agent must disambiguate 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?

'Use this when you need context from past sessions' gives a genuine when-to-use, but there are no when-not cases and no explicit alternatives, despite a crowded sibling space (find_similar, memory_list, episodes, knowledge_recall). An agent is left to infer which retrieval tool applies.

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 (readOnlyHint=false) but non-destructive, non-open-world behavior, so the safety profile is covered. The description adds one genuine behavioral fact — persistence across sessions — but says nothing about deduplication, whether the write is immediately recallable, or how it interacts with the propose/ratify flow.

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, both load-bearing: the first defines the operation and its durability, the second routes the agent to the moment of use. Nothing is repeated from the schema or annotations.

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 nine-parameter tool with nested metadata, three enums and no output schema, the description covers purpose and timing but not the surrounding workflow — no note on duplicate handling, project vs global defaults at a high level, or what a subsequent recall will show. The schema fills most of the gap, so this is adequate rather than 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?

Schema description coverage is 100% and the parameter docs are unusually rich (ttl formats, scope defaults, category semantics, sourcing trust tiers), so the description is not required to carry parameter meaning. It contributes no parameter guidance of its own, matching the baseline for fully documented 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 and resource ('Store an episodic memory') plus the defining property of persistence across sessions, so the agent knows this is a durable write, not a read or ephemeral note. It does not differentiate itself from adjacent writers like memory_propose or knowledge_write, and calling a seven-category memory tool 'episodic' slightly undersells its scope.

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 condition ('when you learn something important about the user, a project, or yourself that should be available in future sessions'), which is enough to recognize the right moment. It offers no exclusions or alternatives, so the agent gets no help choosing between this and memory_propose/knowledge_write.

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=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds that content replacement overwrites the existing body and that metadata/content are independently optional, but says nothing about failure when the target is not found or about partial-update 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 tight sentences with no filler; the core action is front-loaded and the addressing/update modes follow immediately. Nothing is repeated from the 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?

For a 6-parameter but entirely optional update tool with full schema coverage and safety annotations, the description covers addressing and mutation scope adequately. It omits only edge-case behavior (not-found errors) and confirmation of what a successful update returns, which is minor given no output schema exists.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds genuine value by tying the parameters into an OR relation (ref vs category+title) and noting ref comes from remember — an inter-parameter relationship the schema only hints at individually.

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 ("Update an existing memory") and clarifies the two lookup paths (ref, or category+title) plus the three update modes (content, metadata, or both). It does not explicitly distinguish itself from siblings like remember or memory_merge, but the resource and scope are unambiguous.

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 through the two addressing modes, but there is no explicit when-to-use versus alternatives (remember to create, memory_merge to combine, memory_propose to stage changes). An agent must infer the boundary from the sibling 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is signposted. The description adds non-obvious behavior beyond that: a dual list/update mode triggered by omitting section/content, and an immutability rule for IDENTITY.md that constrains where writes may land. It still doesn't spell out that replace destroys existing section content or any permission requirements.

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, each carrying distinct information (purpose/granularity, list mode, immutability constraint), with the core purpose front-loaded and 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 destructive write tool with destructiveHint already declared and no output schema, the description covers scope, targeting granularity, list mode, and the immutability boundary. It leaves minor gaps around failure behavior and permissions, but an agent has enough to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter semantics the schema documents only per-field: omitting both `section` and `content` switches the tool into a listing mode, and it clarifies the file scope relative to the immutable IDENTITY.md.

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 verb and resource (update self-model/preferences) plus the granularity of the edit (H2 sections in identity files), which is far more precise than the sibling `update`. It does not explicitly name a sibling tool to contrast with, 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 an explicit operational condition ("Call without section/content to list available sections") and an explicit exclusion ("IDENTITY.md ... is immutable — only self-model and preferences can be edited"). No alternative sibling tool is named, but the when-to-use and when-not-to-use guidance is concrete.

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