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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds the conceptual context of a separate cosine-similarity store, but it does not explain the notable implications of the annotations: what is 'destructive' about ingesting, and whether re-ingesting the same file duplicates chunks given idempotentHint=false. Useful but incomplete beyond the structured hints.

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 purpose and a compact clarifying phrase, then a short returns line. Efficient overall, though the Returns enumeration is largely redundant given that an output schema exists.

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?

Purpose, storage context and return shape are covered, and an output schema exists so return values need not be spelled out. The one real gap is behavioral: for a non-idempotent, destructive-flagged ingestion tool the description never says whether repeated ingest of the same file duplicates or replaces chunks.

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 parameters (path with its server-side filesystem caveat, and the source tag defaulting to filename) are already fully documented in the schema. The description adds no parameter-level detail, which is the expected baseline when the schema does the work.

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

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

States a specific verb (Index) and resource (a file into the reference bank) and immediately characterizes the destination as a distinct store for background documents, differentiating it from conversational memory and from the sibling document_search (which retrieves rather than ingests). An agent can tell what this does 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?

The contrast with 'conversational memory' clearly implies when to route here (background corpora like papers, manuals, codebases) versus the many memory_* siblings, and names example document types. It stops short of an explicit when-not or a named alternative tool, so it is strong context rather than 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds the corpus boundary (only ingested documents, no memories), but adds nothing about ranking, empty results, or pagination behavior beyond that.

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, zero waste, with the scope constraint front-loaded ahead of the sibling redirect. 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?

With an output schema present, return values need not be explained, and the description covers scope and routing adequately. Minor omission of edge-case behavior (e.g. no-match handling) keeps it just short of a full 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% with a documented natural-language query and top_k default, so the schema carries the parameter meaning. The description adds no syntax or format detail beyond what the schema already provides, making the baseline 3 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 (Search) and resource (the reference bank / ingested documents), and immediately scopes it against the sibling by clarifying it returns documents only, with no conversational memories. An agent can differentiate this from memory_search without opening either schema.

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

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

Gives an explicit when-to-use plus a named alternative and its triggering condition: docs alone -> this tool, docs AND memories together -> memory_search. Nothing is left to inference.

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

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

Goes well beyond the annotations: discloses that board writes require an authenticated adapter, that status/parks grant no approval, that file claims are advisory rather than edit locks, that automatic wake needs a live listener or mail waits a turn, and that reclaim renews while a busy lease queues you. It also spells out the non-obvious side effect that a status update without park fields clears any park and surfaces a warning.

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 purpose, then groups guidance by action (list, update, claim/release), which matches how an agent will scan it. The telegraphic, fragment-heavy style compresses 16 parameters into little space, but a few clauses ("idle_omitted counts idle peers") are too terse to parse on first 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?

An output schema exists so return values need not be documented, and the description covers the high-risk gaps for a 4-action, 16-param tool: auth requirement, advisory nature of claims, wake/listener caveat, park defaults and expiry behavior. Only the list/update scoping of project/task relevance is left implicit.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds cross-parameter semantics the schema cannot express per-field — mutually exclusive selector forms (lease vs worktree+path vs repository_id+path), 'omitted fields stay' on update, and park-clearing behavior. cryptic fragment like "idle_omitted counts idle peers" is unexplained and adds little.

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 opening sentence names the resource (agent sessions on the shared board) and enumerates the four verbs (list, update, claim, release), so an agent can tell what it does without opening the schema. It never names a sibling, but no sibling in the list covers leases/board coordination, so ambiguity is low.

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?

"List before shared work and on resume" and "Park when you stop ... done means no follow-up expected" give concrete triggering conditions for two of the four actions. Claim/release selection is also guided by the one-selector rule. It lacks explicit when-not/alternative-tool routing, keeping it below 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=false, so the safety profile is covered. The description adds the useful consequence that lookups under either name resolve to the same node, but it never explains the destructive aspect the annotation flags (e.g. whether an alias already bound elsewhere is silently overwritten) or persistence 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 sentences, zero filler, with the core action and its rationale front-loaded and the return value disclosed last. Nothing 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?

An output schema exists, so the return-value note is a bonus rather than a necessity, and the two parameters are fully documented in the schema. The only gap is conflict/overwrite semantics, which the destructiveHint annotation raises but the description does not address.

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's ``pg`` → ``postgres`` example adds real meaning by clarifying the direction of the alias/canonical relationship that the terse schema descriptions ("The alternative name", "The canonical entity to bind onto") leave slightly ambiguous.

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 concrete verb ("Bind") and resource ("an alternative name to an entity") and reinforces it with a concrete example (``pg`` → ``postgres``). It is clearly distinguishable from most siblings, though it never names the adjacent tools (memory_set_add, memory_graph_relate) that also create bindings.

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 through the example and the phrase "so facts and graph lookups under either name land on the same node." There is no explicit statement of when to prefer aliasing over other binding tools, nor any prerequisite or exclusion 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 destructiveHint=true and idempotentHint=false, but the description adds real value beyond them: pre-flight atomicity (all targets resolve or nothing mutates) and the fact that superseded entries are retained as history rather than deleted. It doesn't cover auth/permission needs, but the mutation semantics are well disclosed.

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 purpose sentence, then compact operational rules, then the return shape. Every sentence carries distinct information 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 destructive consolidation tool with full schema coverage, an output schema, and safety annotations, the description covers the remaining gaps: atomicity, selector exclusivity, history retention, and the return keys. 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 the baseline is 3. The description adds meaning beyond the schema by stating that exactly one selector mode must be used and that there is no similarity fallback, which clarifies the replaces vs entry_ids relationship that the schema only hints at with 'prefer over replaces'.

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 (replace) and resource (a cluster of near-duplicate memories) plus the resulting artifact (one canonical note). It implicitly separates itself from single-entry tools like memory_supersede, but never names a sibling to draw the line explicitly.

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

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

Gives concrete operating guidance: use exactly one selector mode, no similarity fallback, all targets must resolve before mutation, and re-search/resubmit on missing/retired/ambiguous targets. Strong when/how context, but it does not name alternative tools (e.g., memory_supersede or memory_consolidation_candidates) or state when not to consolidate.

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 destructiveHint=false, so safety is covered; the description adds genuine context beyond that — this is read-only discovery feeding a separate mutation, and the ID-not-text commit contract matters because IDs survive rewording. It also discloses the return shape. It stops short of noting limits on how many clusters or entries are scanned beyond the schema's defaults.

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 paragraphs, purpose front-loaded, then the workflow, then the commit contract and return shape. The prose is dense but every clause carries actionable information; nothing is filler.

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

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

Covers purpose, anchor choice, the follow-up commit call, the ID-vs-text caveat, and the return shape, which is more than sufficient given an output schema already exists and annotations carry the safety profile.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including the topic-driven vs session-driven anchor distinction. The description restates the query/episode anchoring but adds no syntax, format, or interaction detail beyond it, 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 ('find clusters of near-duplicate memories ripe for consolidation') and frames the scope precisely as a discovery step, clearly distinct from the sibling memory_consolidate which performs the write. An agent can separate the two tools without opening either schema.

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

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

Gives an explicit three-step workflow (anchor with query/episode, read clusters, synthesise, commit via memory_consolidate) and names the alternative tool for the write step. It also resolves the no-required-params ambiguity by telling the agent to supply an anchor.

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

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

With destructiveHint=true and non-idempotent already declared, the description still adds real substance: which action is read-only (status), that deep snapshots graph tables before writing, that rollback reverts facts and events while keeping traces/cursor, and that list results are capped with full counts in 'truncated'. It does not cover auth requirements or concurrency/rate behavior, so it stops 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?

Strong front-loading: the one-line purpose precedes a tidy action-indexed list, and each bullet earns its place by pairing an action with its workflow consequence. Minor deduction for the dense wrapping and for the action list omitting 'commit', which forces the reader to reconstruct it from the pull bullet and the commit_token parameter.

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

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

An output schema exists, so the terse 'Returns: per-action dict; {error} on bad input' is sufficient. For a 7-parameter, destructive, multi-mode tool, the per-action map covers most what an agent needs, but the enumerated 'commit' action is never given its own entry, leaving one mode described only indirectly.

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 86%, so the schema already documents apply, limit, run_id, snippets, cursor and commit_token with per-action context. The description largely mirrors that (dry-run apply, pull default of 40), adding only marginal framing such as the pull-then-commit token flow. Baseline 3 is appropriate when the schema carries the load.

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 opening sentence gives a specific verb and resource ('consolidation of recent memories into canonical facts and graph structure'), and the per-action breakdown makes each mode legible. It falls short of a 5 only because it never distinguishes itself from close siblings such as memory_consolidate and memory_consolidation_candidates, 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?

Each action carries contextual guidance: 'status' is read-only backlog inspection, 'pull' is for unconsolidated memories with an explicit follow-up chain (memory_fact_set then commit), 'deep' is a dry run unless apply and routes candidates to memory_graph_review. What's missing is any when-not guidance or explicit comparison against the sibling consolidation tools.

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

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

The annotations already declare readOnly=false, destructive=false, idempotent=false, and openWorld=false. The description adds stack-pop semantics and scope ('current open sub-episode', 'parent'), but it does not explain error behavior when no sub-episode is open or what happens to the closed episode's content.

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 that states the core action with no filler. Every word 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?

With an output schema, full parameter documentation, and annotations covering safety, the description only needs to convey the core operation, which it does. It would be stronger if it stated the prerequisite of an open sub-episode or the behavior when none 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%: the single optional episode parameter is fully documented in the schema as the session handle. The main description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb-resource pair: closing the current open sub-episode and returning to its parent. It does not explicitly contrast with the sibling memory_episode_start, so it stops short of full sibling differentiation.

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

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

The description gives no explicit when-to-use or when-not-to-use guidance, nor does it name alternatives such as memory_episode_start. Usage is only implied by the phrase 'current open sub-episode.'

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

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

Annotations declare non-readonly, non-idempotent, non-destructive, but the description adds genuine behavioral context beyond them: the sub-episode nests under the session episode, memories written while open are tagged with its id and title, and end pops back to the parent. What it does not clarify is what repeated starts do or whether state persists across calls.

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 action and then the consequence and pair-tool. The only blemish is the awkward mid-sentence line wrapping in the source text; content-wise there is 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?

An output schema exists, so return values need not be described, and the description covers the lifecycle (start/end), the nesting model, and the memory-tagging effect. It is nearly complete for a state-mutating episode tool, missing only edge-case behavior on repeated starts or when a session handle is absent.

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

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

Schema description coverage is 100%, so title, hint, and episode are already documented in the schema; the description only reinforces 'named' and the title's role in recaps/episode-scoped search. It adds no syntax or format detail beyond the schema, 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 ('Open') and resource ('named sub-episode') and immediately explains the nesting relationship and its effect on subsequently stored memories. It also names the paired sibling memory_episode_end, so an agent can distinguish it from the closing tool 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 the effect statement ('memories stored while it is open carry its id + title for episode-scoped search') and by naming memory_episode_end as the closer, but there is no explicit 'use this when / not when' guidance or discussion of alternatives for scoping memories.

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, destructiveHint=false, and closed-world, so the safety profile is covered. The description adds one genuinely useful behavioral detail: it returns {found: false} for an unknown id. Beyond that edge case it adds nothing (no pagination or permission notes), so a 3 is fair.

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?

Extremely tight and front-loaded: the returned contents lead, followed by the intent paraphrase and the not-found case. Slightly awkward inline-code formatting, but no wasted sentences.

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

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

For a single-param read tool with a rich output schema, full schema coverage, and annotations, the definition is nearly self-sufficient; the {found: false} disclosure covers the main behavioral unknown. Nothing further is strictly required, though alternative routing remains undocumented.

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?

With one parameter and 100% schema description coverage (the id is described as 'as it appears on search/recent results'), the schema carries full weight. The description adds no syntax or format detail beyond the schema, 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?

The description names the resource (one episode) and enumerates the outputs (stats, tag/source distribution, recent entries), so an agent can tell what it returns. However it lacks an explicit verb and doesn't distinguish itself from siblings like memory_stats or memory_get beyond the episode scoping. Clear but not sibling-differentiating.

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 a natural-language trigger ("summarise what we worked on"), which hints at intent, but no explicit when-to-use, when-not-to-use, or named alternatives among the many siblings (memory_stats, memory_episode_end, memory_get). The agent must 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 declare readOnlyHint=true and destructiveHint=false, and the description goes well beyond them: null means EMPTY not unknown, contenders signals an unsettled conflict, re_verify warns the value may be stale, and it discloses a backend difference (PostgreSQL keeps the warning after eviction, file mode has no durable retraction). This is unusually rich behavioral disclosure for a read 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?

The core purpose is front-loaded in the first clause and every sentence carries information. It is dense with backtick notation and multiple nested concepts, which costs some readability, but there is little 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?

Despite an output schema existing, the description supplies interpretation the schema cannot: what null, contenders, candidates and re_verify mean. An agent has everything needed to call and correctly interpret this 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 coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that verbose=True brings in provenance, support and temporal stamp, complementing the schema's terser 'default drops bookkeeping keys'.

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: 'look up the one CURRENT value at an (entity, attribute) slot'. It explicitly distinguishes itself from the sibling memory_search ('open questions go to memory_search'), so an agent can route correctly without opening either schema.

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

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

Gives clear routing guidance to memory_search for open questions and points to memory_fact_resolve for unsettled conflicts and memory_history for the version chain. It does not, however, state exclusions like when this tool is the wrong choice for a set-valued slot versus memory_set_add/remove.

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 the human-check precondition and the two outcome branches (resolved/no_contender), but since an output schema exists, the return-value text is largely redundant and it adds little about what is actually destroyed beyond what the schema's accept parameter explains.

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?

Very short and front-loaded: the action and precondition come first, followed by the return shape. The return block is arguably redundant given the output schema, but the whole thing is tight and waste-free.

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 with full annotation coverage and an output schema, the description supplies the key context an agent needs: that this resolves a contested slot and requires prior human confirmation. Nothing essential is missing, though it could state the consequence of accepting vs discarding more explicitly.

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 all three parameters (entity, attribute, accept) are documented in the schema, including the history-keeping behavior of accept. The description adds no parameter-level meaning, 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 (settle) and resource (a CONTESTED fact slot), which signals it handles only the contested-resolution path rather than general fact writes handled by siblings like memory_fact_set or memory_supersede. It stops short of explicitly naming those alternatives, so sibling differentiation is implied rather than stated.

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

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

"after checking with the human" supplies a clear precondition/context for when this tool is appropriate, and "CONTESTED fact slot" narrows the trigger condition. No explicit when-not cases or named alternatives are given, but the usage context is unambiguous.

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 a destructive, non-idempotent write, and the description adds substantial context beyond that: a new value supersedes the old with history retained, a conflicting write parks as a contender and returns action="contested" with the winner under current, and authority/distortion_tolerance inherit from the slot's labels unless restated. That is real behavioral disclosure about destructive effects and conflict semantics.

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

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

The core action is front-loaded in the first sentence, followed by sibling routing, supersede/contest semantics, inheritance defaults, and the return shape — every sentence carries information. It is dense and fragment-heavy, which slightly taxes readability, but there is 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?

Despite nine parameters and a write path, the description covers the decisive details an agent needs: sibling routing, error case (set-valued slot), conflict outcome and its resolution path, inheritance defaults, and even the return shape (redundant with the output schema but harmless). Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: authority and distortion_tolerance inherit the slot's labels unless restated, which explains the interaction of two otherwise opaque enum parameters. The remaining parameters (origin, episode, confidence, freshness_class) are left to the schema, which is adequate but no more.

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 ('Assert a canonical fact — insert, confirm, or correct a slot's one NOW value') and explicitly separates itself from siblings memory_store (narrative) and memory_set_add (many concurrent values). An agent can distinguish it from memory_fact_resolve and memory_supersede 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: narrative/decisions/observations go to memory_store, many concurrent values go to memory_set_add, and a set-valued slot errors here. It also says how to handle the contested case ('check with the human, settle via memory_fact_resolve'), which is precisely the when/when-not/alternative guidance the dimension asks for.

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

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

Goes well beyond the destructiveHint annotation by disclosing which scopes hard-delete with no audit trail (fact) versus retire with an audit row (world/lesson), the confirm_bulk threshold of 20, and the would_delete refusal shape. These are exactly the behavioral facts an agent needs before a destructive call.

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

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

Dense but front-loaded: scope behaviors first, then alternatives, then filter rules, then the bulk-refusal guard. Every clause carries information, though the backtick-heavy formatting and run-on density cost it a point.

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

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

Given 9 parameters, an output schema, and destructive annotations, the description covers the required scope-dependent rules, the bulk-confirmation guard, and the undo path. Nothing material to correct invocation 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 cross-parameter semantics the schema cannot express: scope="memory" needs at least one filter, several filters NARROW the match (AND), and non-memory scopes require entity. This mapping of filters to scopes is genuinely additive.

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 (forget/delete/retire) and resource (memory store) and enumerates the four scopes with their distinct behaviors. An agent can distinguish this from siblings like memory_supersede or memory_fact_set 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 routes the agent: 'For now wrong, keep history use memory_fact_set (facts) or memory_supersede (memories) instead,' and names memory_graph_review(action="restore_slot") as the undo path. When-to-use and when-to-use-something-else are both 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?

Discloses behavior annotations cannot express: that reading gently reinforces the memory (which explains readOnlyHint=false and idempotentHint=false), that superseded entries additionally return replaced_by, and the exact forgotten-state payload {found: false, faded: true}. This is a read with a documented side effect, and the description is the only place that fact lives.

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

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

Front-loaded with the core purpose and tightly written, with no filler sentences. The phrasing is telegraphic ('Superseded: adds replaced_by, as in search'), which is efficient but slightly fragmentary rather than cleanly structured.

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

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

With an output schema present, return values need not be enumerated, yet the description still flags the important edge-state shapes (superseded, forgotten) and the reinforcement side effect. Only minor gaps remain, such as behavior for an invalid or unknown id versus a forgotten one.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema, including where the id originates. The description adds no syntax, format, or constraint information about entry_id beyond what the schema already 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?

States a specific verb and resource: dereference a memory id to the full stored episode plus the canonical facts it produced (consolidated_into). It implicitly contrasts with the search/fact siblings by naming what it returns, but never names an alternative tool outright, so it stops short of full sibling differentiation.

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

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

Usage is implied through the entry_id parameter ('as returned by search results or by a fact's source_entries'), which tells the agent where ids come from. There is no explicit when-to-use/when-not, no named alternative (e.g. memory_fact_get or memory_search), and no guidance on when dereferencing is preferable to those.

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 establish the safety profile (readOnly, non-destructive, closed-world), so the description only needs to add read-specific context — and it does: transitive/inverse edges arrive pre-derived, are flagged `derived: true`, and carry rule provenance. That is real behavioral detail an agent cannot get from annotations, though pagination/size limits are unmentioned.

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?

Tight and front-loaded: purpose first, then the derived-edge behavior, then the return keys. The trailing return-shape sentence partially duplicates the output schema, but it is short enough not to be wasteful.

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 a 5-parameter schema at full coverage, an output schema, and annotations covering the safety profile, the description supplies the one thing structured data cannot — how edges are derived and flagged. It is nearly complete; a note on result size or the shortest-path behavior would close the 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 description coverage is 100%, so depth, to, include_facts, and relation_filter are fully documented in the schema itself. The description adds no parameter-level meaning beyond that, which matches 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?

States a specific verb and resource ('Read an entity's graph neighborhood') and enumerates what it returns (nodes, typed edges, canonical facts). It clearly reads as the graph-traversal counterpart to memory_get/memory_search, but it never names or distinguishes itself from those siblings explicitly.

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

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

The scope ('an entity's graph neighborhood') implies when you'd reach for it, and the mention of a `to`-style shortest path is only in the schema. There is no explicit when-to-use/when-not guidance versus memory_get, memory_recall, or memory_graph_review.

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 destructive=true, idempotent=false and openWorld=false, and the description adds real substance on top: entities auto-create, names resolve through aliases, re-asserting bumps confidence, and unknown relation names are rejected WITH closest matches plus a suggestions payload. It does not explain why the call is flagged destructive or whether conflicting existing edges are overwritten.

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 a worked example, and each following clause carries new information (auto-create, alias resolution, confidence bump, error recovery). Minor waste: the trailing return-shape sentence duplicates the output schema, and the dangling ``(full)`` qualifier on memory_relation_define is unclear.

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 mutating graph tool with full annotations and an output schema, the description covers the behaviours an agent actually needs: creation side effects, alias resolution, idempotency-ish confidence bumping, and the rejected-relation recovery path. Gaps remain around overwrite/conflict behaviour and the exact meaning of the destructive flag.

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 earns extra by explaining the runtime semantics of src/dst (auto-creation and alias resolution) and of relation (closed registry, normalisation, rejection behaviour) rather than just restating field names. It adds no detail on origin, src_type/dst_type, or how confidence interacts with re-assertion.

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 (assert) on a specific resource (typed relation between two entities) and pins the semantics down with a concrete triple example using a real registry relation. It also names the sibling memory_relation_define as the escape hatch, and the 'assert' vs sibling memory_graph_unrelate contrast is implicit but 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 explicit conditional guidance for the failure path: on a rejected relation, take a suggestion, fall back to ``related-to``, or extend the registry via ``memory_relation_define``. It does not, however, say when to reach for this tool versus memory_graph, memory_store, or memory_graph_review.

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, but the description adds real behavioral context beyond them: restore_slot notes 'forgets retire, never delete', relate 'writes the relation edge and dismisses the pair', accept_junk deletes over-extraction artifacts, and accept_merge folds entities. It also documents the return shape and {error} on bad input. It doesn't state auth/rate-limit constraints, so 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?

Front-loaded purpose sentence followed by a scannable action list; every line carries a distinct verdict or effect. Efficient for an 11-action multiplexer, with only minimal redundancy from the trailing return note.

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

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

An output schema exists and annotations cover the safety profile, so the description needn't explain return values. It covers all 11 actions and the retire-never-delete semantics, but omits sequencing prerequisites (e.g. whether a list/propose must precede an id-based settle).

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 89%, so the schema already documents src, dst, store, scope, relation, proposals, proposal_id and proposal_ids in detail. The description reinforces parameter roles in context ('store + src (the retired key)', 'settle an edge proposal by id') but adds little beyond the structured fields. 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 opening sentence gives a specific verb and resource: work the graph review queue for deep-dream proposals awaiting a verdict before touching the graph. That clearly separates this from direct-write tools like memory_graph_relate or generation tools like memory_dream. It stops short of naming a sibling or explicitly contrasting, so 4 rather than 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?

Each of the 11 actions is annotated with what it decides (e.g. 'relate: related-not-duplicate verdict', 'dismiss_pair: mark src/dst genuinely distinct', 'reject_entity: keep the entity, dismiss the proposal'), which functions as per-action usage guidance. No explicit when-not or alternative-tool routing is given, so it lands at 4.

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, but the description adds crucial nuance beyond them: the retraction is a soft delete ('marked superseded (kept for audit)') rather than a hard erase, it removes the edge from memory_graph results, and re-asserting the same triple revives it. This materially changes how an agent should treat the 'destructive' operation.

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: the core effect (superseded, kept for audit, removed from results) is front-loaded and the revival behavior follows. No filler.

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

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

With annotations covering the safety profile and an output schema covering return values, the description's remaining job is the soft-delete/revival semantics, which it delivers well. It could still be strengthened by contrasting with the relate/supersede siblings, but nothing needed 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 description coverage is 100% (src/relation/dst each documented), so the schema carries parameter meaning. The description alludes to the triple structure ('the same triple') but adds no format, syntax, or edge-resolution 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 ('Retract') and resource ('a relation') and describes the effect (edge marked superseded, leaves memory_graph results). It does not explicitly distinguish itself from the nearby sibling memory_graph_relate or memory_supersede, so an agent must infer the pairing, but the operation itself 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 implied by the operation (retracting an existing triple), and the revival note hints at reversibility, but there is no explicit when-to-use/when-not guidance or named alternative despite siblings like memory_graph_relate and memory_supersede. Minimum viable.

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, non-destructive, closed-world), so the description rightly spends its budget elsewhere: it discloses result ordering (oldest→newest), included metadata (writer/session, tx/valid time, age), and a genuine degradation trait — compaction thins chains past ~30 days. That retention caveat is information an agent cannot get from annotations or schema, though it could say more about pagination or why idempotentHint is false on a read.

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 the mode branch, with uppercase mode labels making the split scannable. The trailing 'Returns:' block is largely redundant given an output schema exists, which is the only real waste.

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 three-parameter read tool with a full schema and an output schema, the description covers mode semantics, ordering, metadata, and retention limits adequately; return-shape detail is duplicated rather than needed. An agent has enough to call it correctly, with only sibling differentiation left unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents `as_of` (slot-only, ISO-8601/epoch, no relative words), `entity`, and `attribute` mode-switching. The description restates the given/omitted mode logic, which is useful framing but adds no syntax or format detail beyond the schema, 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 ('Read an entity's past') and precisely delineates two operating modes keyed on whether `attribute` is supplied. It is immediately clear what the tool returns in each mode, but it never names or contrasts itself with the many plausible siblings (memory_recall, memory_get, memory_fact_get, memory_search), so an agent cannot fully distinguish it without reading other 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?

Gives explicit mode-selection rules ('SLOT mode (attribute given)' vs 'CHAIN mode (attribute omitted)') plus intent examples ('what did this used to be? who set it?', 'what led to X?') that let an agent map a question to the right mode. It stops short of when-not-to-use or naming an alternative sibling for overlapping temporal queries.

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, non-destructive, non-idempotent, closed-world), so the description earns credit for adding what annotations cannot: the 'apply where today's specifics match' caveat against stale framing, and the meaning of re_verify as flagging lessons whose subject facts changed. It doesn't discuss scoring, ranking, or rate limits, keeping it at a 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?

Core instruction ('Call at the START of a task') is front-loaded ahead of interpretation guidance, and every sentence carries operational content. The backtick-laden prose is slightly dense and the Returns block is arguably redundant given a real output schema, but there is little true waste.

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 search tool with full schema coverage and an output schema, the description covers timing, result interpretation, polarity semantics, and the re_verify caveat — everything an agent needs to use it correctly. Including the return shape is redundant rather than missing, so completeness is high but not perfect.

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 query/top_k/verbose are already documented in the schema, and the description adds no input-parameter meaning beyond them. The 'Returns' block describes output fields rather than inputs, 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 and resource ('Search learned lessons (procedural memory) by similarity to the task at hand'), and the '(procedural memory)' qualifier separates it from the general memory_search/memory_recall siblings. An agent can tell what it will get back 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 timing guidance ('Call at the START of a task') plus concrete usage rules ('Heed polarity - entries — known dead-ends'). It tells the agent when to run it and how to interpret results, though it doesn't name a competing sibling tool for contrast.

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 non-read-only, open-world, non-idempotent, non-destructive; the description goes far beyond, disclosing the auth prerequisite ('Needs an authenticated board adapter'), wake-receipt code meanings (rung/hinted/withheld/not_needed/no_path/capped), that rung is scheduling not proof of reading, 24h pending-body expiry, request_conflict on changed inputs with a reused request_id, and invalid_cursor (cursor_ahead). This is exactly the behavioral context annotations cannot carry.

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

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

The action list and send requirements are front-loaded, and it uses line breaks to separate receive/history/continuity sections. It is dense and long, and a few clauses (e.g. the receipt-code list) read as a wall of text, but nearly every sentence carries actionable constraint 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?

Despite an output schema existing (so return shapes need not be explained), the description still supplies the semantics of result codes, plus auth, expiry, retention, cursor isolation between receive and history, and the main error codes. For a 12-parameter, four-action tool this is complete enough to invoke correctly without further digging.

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 cross-parameter semantics the schema lacks, such as 'Reuse a request_id only for the identical send', the cursor being reset when the peer changes, and reply_to implying the recipient when 'to' is omitted. It is largely complementary rather than duplicative, so it lands above baseline.

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

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

The opening line 'Mail between agent sessions: send, receive, ack or history' states a specific resource (inter-agent mail) and enumerates all four verbs the single tool dispatches, so an agent can immediately tell it apart from the memory_* recall/store siblings. The per-action sections then pin down what each verb does.

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

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

It gives explicit conditions for the ambiguous choices: ack means 'read, not done', use ack=true to combine read+ack, clears 'only when the message really satisfies the peer's park_needs', urgent 'only when it cannot wait', and 'Do not resend to force a ring'. There is no sibling routing (this tool is self-contained), so it stops short of a full when/when-not/alternatives matrix, but the internal guidance is strong.

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 establish this is a non-read-only, non-idempotent, non-destructive write, and the description adds substantial context beyond that: it requires Postgres, it feeds a downstream dream/consolidation cycle, and it documents failure/partial modes (used_ids_unmatched, used_ids_served_elsewhere, used_ids_ignored, used_ids_truncated, used_ids_errors). It does not address idempotency — repeated logging of the same outcome presumably creates duplicate signals given idempotentHint=false — which is the one notable 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?

The purpose is correctly front-loaded, but the final sentence enumerates seven used_ids_* return fields — redundant given that an output schema exists and the description is not required to explain return values. That enumeration bloats the description and dilutes the actionable content.

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

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

For a 7-parameter write tool with annotations and a full output schema, the description covers purpose, the DB dependency, the crediting window, and the downstream lesson cycle. The main omission is whether repeated calls are safe/duplicative, which matters given idempotentHint=false.

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; baseline would be 3. The description goes beyond the schema by explaining the semantics of used_ids (it credits this session's searches, and only those from the last hour) and the downstream meaning of unmatched/served_elsewhere outcomes, adding genuine value over the field text.

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

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

States a specific verb ("Record") and resource ("procedural outcome") and enumerates the outcome space ("what worked, failed, or was corrected"). The phrase "signals into next session's lessons" and the used_ids crediting make clear this is the outcome/lesson-logging tool rather than the general-purpose memory_store or memory_lesson_search 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?

Provides one concrete usage constraint — used_ids only credits searches from the last hour, so "log before that lapses" — which implies a timing window for calling it. But there is no explicit when-to-use-this-vs-alternatives guidance: nothing tells the agent when to pick memory_outcome over memory_store, memory_message, or memory_reinforce.

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 (readOnly, non-destructive); the description goes well beyond by disclosing the capping/reservation behavior, the meaning of re_verify (memory corrected, value still stands but check it), pinned constraint facts, and the truncated/searches_issued early-stop semantics with remediation advice.

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 and the memory_search distinction are front-loaded, and each subsequent sentence describes a distinct return-field behavior (caps, re_verify, pinned, truncated). It is dense and long, but almost every sentence earns its place by adding behavioral semantics rather than restating structured fields.

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

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

An output schema exists, yet the description supplies the interpretation layer the schema can't (what truncation and re_verify mean for the caller). For a multi-hop, non-idempotent retrieval tool, an agent has everything needed to call it correctly and interpret results.

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 hops, query, top_k, and verbose are already fully documented in the schema, establishing a baseline of 3. The description adds only marginal param meaning, e.g. tying hops to truncation ('lower hops') and hinting at question narrowing, but adds no syntax 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 ('Multi-hop retrieval over the knowledge graph') and scopes it to RELATIONAL questions with concrete examples. It explicitly distinguishes itself from the sibling memory_search by noting single-shot retrieval 'can't chain' the links this tool follows.

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 ('what does X ultimately run on?'), when-not (single-shot questions belong to memory_search), and a concrete fallback condition (low_confidence: true means no seed matched, fall back to memory_search). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, explaining the safety profile, so the description adds the ordering semantics (timestamp vs relevance) and the filter combination rule ('AND-combine'). It does not discuss result bounding/pagination beyond the n limit, so it is solid but not exhaustive.

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, with the ordering constraint front-loaded before the use cases. 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?

An output schema exists so return shape needn't be explained; the description covers purpose, ordering, and filter interaction. It could be marginally more complete by naming the relevance-based sibling it contrasts with, but nothing needed 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 baseline is 3, but the description adds real semantics beyond the schema: the sources/episodes/tags filters AND-combine (the schema does not state the combination operator). That is genuine added value over the per-parameter descriptions.

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) and resource (most recently stored memories) plus the ordering contract ('newest first — timestamp order, not relevance'), which implicitly separates it from the relevance-ranked memory_search sibling. An agent can select 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?

Gives concrete when-to-use contexts: 'what did I just store?' and catching up at session start. It stops short of naming the alternative tool (memory_search/memory_recall) for contrast, so the routing is contextual rather than explicit.

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

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

Annotations already establish that this is a non-readOnly, non-destructive, closed-world operation, so the description only needed to add context. It does add meaningful behavior: the required read-before-write ordering and the intended effect of reducing forgetting. It stops short of explaining whether repeated calls stack or are capped, which matters given idempotentHint=false.

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 action in the opening clause and follows with the condition and the ordering rule. Two sentences with no redundant padding, though the em-dash aside is slightly more ornate than necessary.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile. For a single-parameter mutation-with-effect tool, the description supplies the trigger, the ordering constraint, and the purpose, leaving nothing an agent needs in order 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?

Only one parameter, and schema description coverage is 100% ('The id of the memory to strengthen'), so the schema already carries the semantics. The description implies the target must be a single memory previously fetched via memory_get, which is mild added context but does not exceed the schema. 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: 'Strengthen one memory' and explicitly frames the effect as helping a memory 'resist forgetting'. It clearly differentiates itself from memory_get by naming it as the prerequisite read step. It does not, however, contrast itself with adjacent siblings like memory_reinstate or memory_supersede.

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

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

Gives a clear situational trigger ('after reading it via memory_get and finding it genuinely useful') and an explicit procedural rule ('Read first, then reinforce'). It lacks any when-not guidance or a pointer to an alternative tool for cases where the memory was not useful.

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 destructive=true and idempotent=true, so the safety bar is pre-cleared; the description adds real value beyond them with refusal rules ('Refuses trace-invalidated entries'), a blast-radius limit ('never changes derived cortex'), and retry semantics. It omits what exactly is mutated on reinstate, keeping it out of 5 territory.

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

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

Four short front-loaded sentences covering action, constraints, refusal behavior and retry, with no filler. Dense but every clause carries an operational fact, though the ';' run-on packs several ideas into one sentence.

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

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

With an output schema and rich annotations present, the description covers the remaining essentials: engine constraint, preimage requirement, refusal behavior, and retry guidance. The only loose end is the un-parameterized 'named principal' reference against the actual reviewer_ids field.

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?

At 100% schema coverage the baseline is 3, but the description earns more by linking concepts to parameters: 'durable ID' anchors entry_id and 'exact retirement preimage' plus 'same UUID and inputs' anchors the hash/operation_id fields. It doesn't resolve the fact that 'named principal' has no matching parameter.

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

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

The description gives a precise verb and resource ('Reinstate one reviewed retired entry by durable ID'), and the single-entry scope makes it distinguishable from broad write tools. It does not explicitly name a sibling such as memory_supersede or memory_forget, so it stops short of a 5.

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

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

It states prerequisites ('PostgreSQL only', 'requires a named principal and exact retirement preimage') and a retry protocol, which is clear context for correct invocation. It never says when to choose this over alternatives like memory_supersede, so no exclusion 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?

The annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is covered structurally. The description adds the useful framing that this is a 'deliberate, rare act' against a 'closed graph vocabulary,' but says nothing about permanence, name-collision behavior, or whether a defined relation can ever be removed.

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

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

Two short sentences, front-loaded with the purpose and followed immediately by the caution. No filler, and the most decision-relevant constraint (prefer builtins) lands before the agent scans 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?

An output schema exists, so return values need no explanation, and the schema carries all parameter detail. What remains thin is the consequence model: this mutates a global vocabulary but the description does not state whether the addition is permanent or how conflicts are handled.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including hyphenation, soft type expectations, inverse pairing and transitivity. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

The description names a specific verb and resource: 'Add a relation to the closed graph vocabulary.' The word 'vocabulary' implicitly separates it from sibling edge-manipulation tools like memory_graph_relate, but it never names that contrast explicitly, so an agent must infer the distinction.

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 when-not condition ('define one only when a recurring connection genuinely fits none of them') and routes the agent toward alternatives ('Prefer the builtins'). This is exactly the routing guidance needed for a rare, high-consequence 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 cover the safety profile (readOnly, non-destructive), so the bar is met, yet the description goes well beyond: hits are 'leads about the PAST' requiring re-derivation, cortex facts come first, contested/pinned/authority/low_confidence flag meanings, superseded replaced_by handling, verified:false semantics, 'never follow chains', and current:false meaning re-search. This is unusually rich operating context that the schema and annotations do not provide.

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

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

Front-loads purpose, then usage, then hit-interpretation, then filters, then return shape – a sensible ordering. It is dense and telegraphic in places (semicolon-chained clauses), but almost every sentence carries operational meaning; a small amount of the flag glossary could be tightened.

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 12-parameter, output-schema-bearing tool this covers what an agent needs: when to call, when to call siblings, how to interpret each hit flag, filter semantics, and the return shape ({query, count, entries, cortex, low_confidence} plus events for temporal queries) even though the output schema exists.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning not in the schema: filters 'narrow direct entry hits, not cortex, documents or added neighbors' and combine 'AND across kinds, OR within a list'. The bm25/rerank/min_score overrides are left to the schema, so it is 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?

Opens with a specific verb+resource ('Search shared memory in natural language') and enumerates the content types covered (past work, decisions, preferences, canonical facts, documents). It explicitly demarcates itself from siblings by naming memory_fact_get, memory_lesson_search, memory_recall, memory_world_search and document_search for the cases it does not handle.

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 invocation timing ('Call at task start and whenever prior context may matter') and routes the agent to alternatives by condition: exact (entity, attribute) to memory_fact_get, lessons to memory_lesson_search, multi-hop to memory_recall, cited external facts to memory_world_search. Nothing is left to inference.

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

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

The description explicitly claims "Idempotent," but the annotations declare idempotentHint=false. This is a direct textual conflict on a declared behavioral trait, and an agent could be misled into blind retries. The useful context it does add (state mutation, rename semantics, timing) is outweighed by contradicting the structured safety hints.

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

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

Two short sentences, purpose front-loaded, with the rationale for calling it early rather than burying it. Every clause carries information; nothing is redundant padding.

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

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

An output schema exists, so return values need not be described, and the annotations cover the safety profile for this narrowly scoped mutation. The description covers when to call and what it affects, but the idempotency statement leaves the mutation/retry semantics muddled rather than fully resolved.

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, but the description adds meaning the schema omits: it clarifies that omitting `episode` targets this session's own auto-opened episode, whereas the schema leaves the null default's behavior unexplained. That is genuine added value for the optional parameter.

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 and scope: "Name THIS session's auto-opened episode," and explains the default it replaces ("default titles are generic"). It is clearly separable from siblings like memory_store, memory_message, or memory_episode_start, which do different things.

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 timing ("Call once at the start of work") and a follow-up case ("call again to rename"), which is real when-to-use guidance. It does not name an alternative sibling or state when not to use it, so it stops short of 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 declare the safe-write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds substantial beyond-that context: the one-way scalar-to-set conversion on first call, the protected number-led scalars, and the action='contested' parking behavior. This is exactly the kind of side-effect disclosure the 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?

Front-loaded with the core action and scope, and the returns block is short. The parentheticals ('32', '$1,500') and em-dash clauses make it dense but every sentence carries information, so it stays efficient.

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

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

An output schema exists so return values need not be spelled out, and the description still summarizes them. Conversion semantics, the contested path, and read alternatives are all covered; only explicit permission/auth prerequisites are absent for a non-destructive mutation.

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 entity/attribute/member are already documented, and the description adds little per-parameter meaning. It clarifies that a 'member' is added or re-confirmed into a set, but the baseline 3 applies 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 ('Add/confirm a member') and resource ('set-valued slot'), and immediately scopes it against the scalar case ('many concurrent values, not one NOW value'). An agent can tell it apart from memory_fact_set and memory_set_remove 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?

Gives clear when-to-use context (sets rather than scalar NOW values) and routes the contested case to memory_fact_resolve and reads to memory_fact_get. It does not spell out when NOT to use the tool versus other mutators, but the set/scalar distinction effectively covers the decision.

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=false, so the safety profile is partly covered. The description nonetheless adds a genuinely non-obvious behavioral fact — '(audit row kept)' — telling the agent this is a soft retraction with a preserved audit trail rather than an erasure, 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?

Front-loaded and very tight; the destructive behavior and the read-path pointer come first. The trailing 'Returns: {...}' line is redundant given that an output schema exists, which costs it a perfect score but not much else.

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 3-required-param mutation tool with full schema coverage, annotations, and an output schema, the description covers the essentials: what it mutates, that the audit trail survives, and how to verify. It is silent on failure behavior when the member is absent, but that gap is minor given the structured data available.

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

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

Schema coverage is 100% and all three parameters are documented in the schema, so the description need not restate them. It adds no syntax, format, or edge-case meaning beyond 'the current member to retract,' which is already implied by the schema text; 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: 'Retract one current set member.' The parenthetical clarifies the scope (single member) and the audit semantics, so an agent can distinguish this from memory_set_add or memory_forget without opening the schema. It does not, however, explicitly name those 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?

'Read with memory_fact_get' gives one concrete follow-up action, which is useful routing guidance. But there is no statement of when to use this versus memory_set_add, memory_supersede, or memory_forget, so the selection guidance remains implicit.

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 destructiveHint=false, so the safety profile is covered and the bar is lower. The description adds that this is a diagnostic/inspection surface rather than a mutation, but with an output schema present it needn't restate return structure, and it offers no extra behavioral context (refresh cadence, cost, scoping) beyond the metric names.

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 the metric list front-loaded and a single actionable usage clause following. No filler sentences; 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 zero-parameter tool with a published output schema and rich annotations, the description supplies enough context to call it correctly and know why. It could be slightly more complete by hinting at what to do with a bad reading (which sibling to turn to), but nothing required for invocation is missing.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain; per the rubric this is the baseline 4. Nothing in the description misleads about inputs.

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 resource (the memory bank's "vital signs") and enumerates the concrete metrics returned: store occupancy vs capacity, hit rates, true-drop count, and totals. This clearly sets it apart from the read/write memory siblings, though it never names a sibling directly to sharpen the contrast.

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 to gauge how much has been remembered or to diagnose why retrieval feels off" gives two explicit usage contexts, which is strong when-to-use guidance. It stops short of stating when-not to use it or naming an alternative (e.g. memory_search for retrieval debugging), so it isn't 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?

Adds real behavior beyond annotations: near-duplicates are silently dropped rather than errored, with stored=False and reason="below_surprise_threshold", and it sketches the return keys. Annotations (destructive=true, idempotent=false, openWorld=false) cover the write/safety profile, so this supplementary dedup semantics is the valuable addition.

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

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

Front-loads the core action and the persist/context/verify routing before edge-case details. It is dense but mostly earns its length; the trailing 'Returns:' block partially duplicates the output 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?

Given seven parameters, rich enums, and an existing output schema, the description supplies enough routing and dedup context for correct invocation. The explicit return-value listing is redundant against the output schema but not harmful.

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

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

Schema coverage is 100% and enums are self-documenting, so the schema already carries parameter meaning. The description adds only the general constraint of one claim per call and indirect framing of authority/freshness, without explaining tags, origin, source, or episode beyond what the schema already states.

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 one durable fact, decision, or observation) and explicitly distinguishes itself from the sibling memory_fact_set for canonical NOW values. An agent can identify the tool's role 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 decision rules: PERSIST what stays true, leave task-scoped detail to CONTEXT ONLY, RE-VERIFY volatile values at source via memory_fact_set, and ASK when ambiguous. It also names the alternative tool for canonical now-values, so when/when-not is fully covered.

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