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

Annotations already declare the write/destructive/non-idempotent profile, so the description only needs to add context. It adds meaningful architectural detail (separate reference store, pure cosine-similarity retrieval) but says nothing about what ingestion overwrites or how repeated ingests behave, which matters for a destructiveHint=true 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?

Short and front-loaded: the core action and store definition come first, then the return shape. The return-value sentence is slightly redundant given an output schema exists, but the description remains 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?

For a two-parameter ingest tool with full schema coverage and an output schema, the description covers purpose, storage model, and return shape. The only real gap is behavioral detail on the destructive/non-idempotent nature already hinted at in annotations.

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

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

Schema description coverage is 100%, so both parameters (path, source) are already documented in the schema, including the server-filesystem caveat. The description adds no parameter-level meaning beyond that, making the baseline 3 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 ('Index a file into the reference bank') and scopes it to background documents, which separates it from the memory_* cluster. It doesn't explicitly name document_search as the retrieval counterpart, so it's clear but not fully sibling-differentiated.

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

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

Usage is only implied: the examples (papers, manuals, codebases) and 'kept apart from conversational memory' suggest when this store applies, but there is no explicit when-to-use statement and no named alternative such as document_search or memory_store.

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 adds the corpus-scope constraint, but says nothing about result ordering, relevance behavior, or chunk granularity beyond what the schema/output schema implies.

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 zero waste; the corpus-scope constraint is front-loaded ahead of the cross-reference to the alternative tool.

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

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

With annotations carrying the safety profile, an output schema present, and both parameters fully documented, the description only needs to establish scope and routing — which it does completely.

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% (query and top_k both documented in the schema), so the baseline is 3. The description adds no syntax, formatting, or query-construction guidance beyond the schema's 'Natural-language description of the passage wanted.'

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 a precisely scoped resource (the reference bank / ingested documents only), and explicitly names the sibling it is not (memory_search). An agent can distinguish it from the ~30 memory_* siblings 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 when-to-use (reference bank only, no conversational memories) and the alternative plus its selecting condition (docs AND memories together → memory_search). Nothing about tool selection 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false, but the description offers little beyond constraints: park expiry defaults (12 h/7 d max), 'children <=8', 'advisory files', 'No globs/directories/edit enforcement', 'Park/status grants no approval'. It never explains idempotency, retry behavior, or the effect of each action, which matters for a non-idempotent, non-read-only tool. The bearer-auth note is useful but leans on annotations for the rest.

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 prose is a dense, telegraphic wall of semicolon-separated fragments ('Ringing needs live listener; waits need wait-mail/Codex doorbell/next-turn reachability') that is difficult to parse and not front-loaded with the tool's core purpose. Many sentences do not earn their place in their current form because their referents are unclear, so this fails conciseness and structure despite being short.

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

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

An output schema exists, so return values need not be described, but for a 15-parameter, non-read-only, non-idempotent coordination tool the description leaves key behaviors (what 'list' returns, how claims/parks interact, failure/retry semantics, which actions accept which params) unexplained. The scattered hints help but fall well short of what an agent needs to call this correctly across its four actions.

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

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

Schema description coverage is 0%, so the description must supply meaning, and it partially does: park_reason enum values, park_clear_by options (agent id/maintainer/anyone), children <=8 with '[] clears', expect semantics ('overdue seconds'), and the claim scheme (coordinator:<project>/claim:<path>). But 15 parameters exist and several (path, task, lease, worktree, repository_id, park_needs, park_resume, park_expires) are only mentioned in passing or have their semantics left implicit.

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 concrete resources (claims, parks, leases, projects/tasks) and a bearer-auth requirement, and the first line hints at a list-before-shared-work workflow. However, it never opens with a clear statement of what the tool does as a whole (e.g., 'Coordinate multi-agent state: register activity, claim work, park/resume tasks'), so an agent must infer the purpose from scattered fragments. The 'project/task: relevance only' fragment is opaque without context.

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 offers implied guidance: 'list before shared work/resume' and 'project/task: relevance only', plus action-ish hints ('reclaim renews, release frees, busy queues'). But there is no explicit statement of when to use this vs. siblings like memory_message or memory_session_title, and no when-not-to-use. The advice is present but fragmentary and requires the agent to piece it together.

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, non-idempotent, non-read-only, so the safety profile is covered by structured data. The description usefully adds the downstream effect (lookups resolve to the same node) and the return value, but it never discloses what the 'destructive' behavior actually is — e.g. whether re-binding an alias already owned by another entity overwrites that binding.

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 operation is front-loaded, and the effect and return value follow immediately. No sentence is filler.

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

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

With an output schema present, the description needn't explain the returned alias list, and annotations cover the mutation safety profile, so the core is complete. The one meaningful omission for a destructive bind is conflict/overwrite behavior, which leaves it slightly short of full.

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 both parameters are documented as 'canonical entity' and 'alternative name', so the schema carries the load. The description's example directionally reinforces the alias→entity mapping but adds no format, collision, or validation semantics. 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?

It uses a specific verb and resource ('Bind an alternative name to an entity') and the `pg` → `postgres` example makes the direction of the binding unambiguous. It is distinguishable from siblings like memory_set_add or memory_graph_relate, though it never names an alternative to contrast against.

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 clause 'so facts and graph lookups under either name land on the same node' conveys the rationale and implies when aliasing is useful, but there is no explicit when-to-use, when-not-to-use, or pointer to a sibling such as memory_graph_relate. Usage is implied rather than stated.

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

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

Adds real behavior beyond the annotations: all-or-nothing atomicity ('All targets must resolve before any changes'), the exact failure modes that suppress mutation ('Missing, retired or ambiguous'), and the post-condition that 'selected entries remain as history after replacement.' These are the facts an agent needs before a destructive call and none are in the 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?

Front-loads the action, then constraint, then failure behavior, then return shape. No sentence is filler; the return-key line is dense and useful.

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, atomic, multi-target mutation, the description covers what is replaced, how targets are selected, what happens on failure, and what history remains. The output schema exists and the description's return summary is a harmless convenience rather than a gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds selector-mode semantics on top: exactly one of 'replaces'/'entry_ids' must be used and there is no similarity fallback, which is stronger than the schema's 'omit with entry_ids.'

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') with the outcome ('one canonical note'), so the agent knows exactly what it does. It does not differentiate from the sibling memory_supersede, which arguably overlaps, leaving the agent to infer the boundary.

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 rules: 'Use exactly one selector mode; there is no similarity fallback,' plus the failure path ('search again and resubmit IDs'). It stops short of naming the sibling tool an agent should use instead when it does not already have a resolved cluster.

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. The description adds genuine context beyond that: the commit path must use member IDs rather than texts, with the rationale that 'IDs survive rewording and duplicate phrasing, exact text does not.' It also surfaces the anchor requirement, which the annotations do not.

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 definition is front-loaded with the core purpose and follows with the workflow, ID guidance, and return shape. Every sentence is substantive. The 'Returns:' line is mildly redundant given an output schema exists, which keeps it from a 5.

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 read-only safety and an output schema documenting the return shape, the description only needs to convey purpose, workflow, and the commit handoff. It does all three. A richer treatment of how clusters are ranked or how many to expect might push it higher, but nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by requiring the caller to 'anchor with a query or an episode' — the schema shows both as optional and defaulting to null, so this either/or constraint is real added guidance. The rest of the parameter description is redundant with the schema.

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

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

The description states a specific verb and resource — 'Find clusters of near-duplicate memories ripe for consolidation' — with a concrete example ('the same thing phrased five ways across five sessions'). It distinguishes this step from the commit step by naming memory_consolidate as the follow-up, though it doesn't contrast directly with general search siblings like memory_search or memory_recall.

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 workflow: anchor with a query or an episode, read the clusters, synthesise one canonical note, then commit via memory_consolidate. That names the next tool and the condition for using this one. It stops short of saying when NOT to use this tool versus a plain search, so it falls just short of a 5.

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

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

With annotations already declaring destructiveHint=true and readOnlyHint=false, the description adds real context beyond them: rollback reverts facts + events while traces/cursor are kept, deep snapshots graph tables before writing and defaults to a dry run, duplicate lesson/world slots require hand curation, and lists are capped with 'truncated' holding full counts. It does not discuss auth requirements or cost/rate limits, so it is rich 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?

The purpose is front-loaded in one sentence and the action list is organized and scannable. Given six actions and seven parameters the length is defensible, though a few lines (e.g. rollback details) could be tighter without losing meaning.

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

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

For a multi-action tool with 7 params and an output schema, the description covers nearly everything an agent needs. The one gap is the 'commit' action, which appears in the enum and is referenced inside the pull line but never given its own described entry, leaving its behavior 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 description coverage is 86%, so most parameters are already documented. The description adds meaning beyond the schema for the 'action' enum values, whose schema entries carry only a title, by explaining what each action does and its read/write semantics; it also flags 'commit' as the write step after pull. The remaining param notes largely restate schema 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?

The opening states a specific verb+resource: 'Drive the dream — consolidation of recent memories into canonical facts and graph structure,' and each action (status/pull/run/deep/runs/rollback) is named and described. However, it never explicitly differentiates itself from consolidation-related siblings like memory_consolidate or memory_consolidation_candidates, so the agent must infer the boundary.

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?

Per-action guidance is strong: status is labeled read-only, pull is for unconsolidated memories (oldest first) with an explicit follow-up path via memory_fact_set then commit, deep is full-corpus with dry-run default, rollback reverts a committed pass. It stops short of stating when NOT to use this tool versus siblings, so it lacks full alternative 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 declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is already covered. The description adds the stack-pop semantics (closes and returns to parent), but omits what happens when there is no open sub-episode and does not mention that repeated calls are non-idempotent.

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

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

A single front-loaded sentence with no filler; the action and its effect come first. It is efficient, though it could carry one clause of precondition without bloat.

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

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

An output schema exists, so return values need not be explained, and the tool is simple with one optional parameter. However, for a non-idempotent state-mutating stack operation the description says nothing about error or no-op behavior when there is no open sub-episode.

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

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

Schema description coverage is 100% and the single 'episode' parameter is already documented in the schema, including the session-scope constraint and the guarantee that the session root is never closed. The description adds nothing 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?

States a specific verb ('Close') and resource ('the current open sub-episode') plus the stack effect ('pop back to its parent'), which clearly distinguishes it from memory_episode_start. It does not explicitly name its sibling counterpart, but the operation 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 only implied: an agent infers it should call this when a sub-episode is open, and it should use memory_episode_start to open one. There is no explicit when-to-use, no statement about what happens if no sub-episode is open, and no named alternative.

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

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

Annotations only declare the write/idempotency profile (readOnlyHint=false, idempotentHint=false); the description goes beyond them by disclosing the nesting/stacking semantics and the side effect that memories written while open carry the episode id + title. It omits auth or concurrency caveats beyond the reference to several sessions running concurrently.

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 zero filler. The core action and the nesting relationship are front-loaded, and the closing counterpart is mentioned last as a natural follow-on.

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

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

An output schema exists, so return values need not be explained. The description adequately covers the state transition and scoping effect for a stateful episode tool, leaving only minor gaps such as what happens on nested or repeated opens.

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 title, hint, and episode (session handle). The description adds no format or syntax detail beyond what the schema provides, 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 and resource ('Open a named sub-episode') and immediately clarifies the containment model (nests under the session episode). It also names the sibling that undoes it ('memory_episode_end closes it and pops back'), so an agent can distinguish the pair without reading 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?

The description explains the condition for use: memories stored while the episode is open get tagged with its id and title for episode-scoped search, which implies you open one before storing related memories. It names the closing complement, but does not explicitly contrast against other ways of scoping memories (e.g. memory_store alone).

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. Beyond that, the description adds a genuinely useful behavioral fact: the tool returns {found: false} when the episode id is unknown, which tells the agent how to detect a miss instead of assuming an exception.

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 compact sentence with no filler. The return-value content is front-loaded rather than the action verb, which is a minor ordering quirk, but 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 return values need not be enumerated, and the description nonetheless flags the unknown-id case. For a one-parameter, read-only summary tool this is close to complete; only the absence of routing guidance against similar read tools leaves a small 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?

There is a single parameter with 100% schema description coverage ("An episode id, as it appears on search/recent results"), so the schema already carries the semantics and the description adds nothing further about the id. 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?

The description names the resource (one episode) and enumerates what is returned: stats, tag/source distribution, and recent entries. It is clearly a read/summary operation, distinct from siblings like memory_episode_start/end, though the verb itself 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?

The quoted phrase "summarise what we worked on" gives an implied use case, but there is no explicit when-to-use guidance, no exclusions, and no named alternative (e.g. memory_recent or memory_history which could also surface recent activity). Usage must be inferred.

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

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

Annotations already cover read-only safety, so the description is free to add deeper semantics: null means EMPTY (not unknown), set slots return {kind: "set", members, removed}, non-empty contenders signal conflict, and re_verify flags a corrected source memory. It even distinguishes PostgreSQL durable warnings from file-mode behavior — context far beyond the annotations.

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

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

Dense but front-loaded: the core lookup and the null-is-empty rule come first, followed by return shape and edge-case flags. Nearly every sentence earns its place, though the return-format detail is heavier than strictly necessary given 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?

For a 3-parameter read tool with a rich output schema and full annotation coverage, the description covers the edge cases an agent would otherwise misread: empty vs unknown, set-slot shape, conflict signaling, and staleness warnings. 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. The description adds meaning beyond the schema's terse "Full record; the default drops bookkeeping keys" by specifying that verbose adds provenance, support, and temporal stamp. That is genuine added value over the structured field.

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 precise verb+resource+scope: "Look up the one CURRENT value at an (entity, attribute) slot." This clearly distinguishes it from memory_fact_set (writes a slot), memory_fact_resolve (settles conflicts), and memory_search (broad retrieval). An agent can identify the exact operation without opening the schema.

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

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

Routes the agent to alternatives with conditions: memory_search for context on empty slots, memory_fact_resolve for unsettled conflicts, memory_history for version chains. It lacks an explicit "use this instead of X when..." framing for the primary lookup case, but the sibling routing is concrete and actionable.

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, non-idempotent, non-read-only, so the safety profile is partly covered. The description adds genuinely new context: the human-confirmation precondition and the failure shape ({resolved:false, reason:'no_contender'}). It does not, however, elaborate on the destructive consequences beyond what the schema's 'accept' description already says.

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 action and its precondition. The Returns block is somewhat redundant given an output schema exists, but naming the 'no_contender' failure shape is still worth the space, so it stays efficient overall.

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 with an output schema and full annotation coverage, the description supplies the purpose, the human-confirmation precondition, and the failure mode. Return-value detail is rightly left to the output schema. A bit more on alternatives and destructive consequence would complete it.

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

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

Schema description coverage is 100%, so the schema already carries the parameter meaning, including the accept True/False semantics. The description adds only the notion of a 'parked contender' and the human-check context. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource: settling a 'CONTESTED fact slot'. This is clearly distinguishable from siblings like memory_fact_set and memory_fact_get, which imply setting/getting rather than resolving a contested state. It stops short of explicitly naming those siblings, so it earns a 4 rather than a 5.

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

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

It gives one implied precondition: this is only for a slot that is already contested, and only 'after checking with the human'. That narrows usage meaningfully. However, it never names the alternative tools (memory_fact_set, memory_supersede) or states when NOT to use this, so the routing guidance remains inferential.

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

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

Adds substantial context beyond the annotations: the old value is superseded but history is kept (softening the destructiveHint), conflicting writes park as contenders rather than overwriting, and authority/distortion_tolerance inherit slot labels unless restated. This is exactly the mutation-safety detail the destructive/non-idempotent annotations flag as risky.

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?

Densely front-loaded — the core action leads, then conflict semantics, then inheritance, then the return shape. No filler sentences, though a few clauses are terse enough to require a second 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?

For a 9-parameter mutation tool with a contested-state model, the description covers action semantics, conflict handling, inheritance behavior, and even the return shape (despite an output schema existing). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description earns an extra point by documenting cross-parameter behavior the schema cannot express: authority and distortion_tolerance inherit the slot's labels unless restated, which changes how an agent should reason about defaults on a write.

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 precise verb and resource: 'Assert a canonical fact — insert, confirm, or correct a slot.' The three modes map cleanly onto the slot model, and it explicitly routes the conflict case to the sibling memory_fact_resolve, so an agent can distinguish it from memory_fact_get and memory_store.

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 conditional guidance for the contested case ('check with the human, settle via memory_fact_resolve') and explains supersede vs. confirm behavior. It lacks an explicit statement of when NOT to use this versus memory_store or memory_supersede, so it stops short of the top tier.

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 material context beyond them: memory/fact are hard-deletes with no audit trail (retiring digests and orphaning facts/edges), while world/lesson retire with an audit row undoable via memory_graph_review(restore_slot), and the bulk-confirm refusal path at 20 matches. This is exactly the behavioral depth the annotations cannot convey.

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

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

The text is front-loaded with the per-scope behavior, then parameter constraints, then the return shape. It is information-dense but a single sentence spans hard-delete vs retire plus the restore path, which slightly crowds the structure. 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?

For a 9-parameter destructive tool with an output schema, the description covers the per-scope effects, required-parameter alternatives, destroy-vs-retire semantics, the bulk-confirm guard, and the escape hatches (memory_fact_set, memory_supersede, restore_slot). An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value on top by stating that scope=memory needs at least one of text/substring/source/episode/tag, that several narrow via AND rather than widening, and that the other scopes require entity – conditions the per-property schema descriptions don't capture.

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 specific verb ('Forget' / hard-delete / retire) and resource (entries across four named scopes), and names the sibling tools (memory_fact_set, memory_supersede, memory_graph_review) with which it could be confused. It distinctly differentiates itself by scope behavior, which no other sibling 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 explicitly states which alternative to use for the 'now wrong, keep history' case – memory_fact_set for facts and memory_supersede for memories – and carves out when hard-delete is appropriate (junk/test cleanup) versus when retiring is appropriate. When-not guidance is 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?

Adds meaningful behavior beyond the annotations: reading gently reinforces the memory (explaining why readOnlyHint=false), superseded entries include replaced_by, and forgotten entries return {found: false, faded: true}. It omits permission/auth context, but the reinforcement side effect is the key non-obvious trait and it is 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 with the core action and kept short. Some fragments ('Superseded: adds replaced_by, as in search.') are terse to the point of being cryptic, but there is little wasted text.

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 need not be spelled out, and the description still adds the special-case response for forgotten entries. For a single-parameter read tool it is nearly complete, missing only explicit routing among sibling memory reads.

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 entry_id parameter is already documented in the schema, including where the id comes from. The description adds only marginal 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 (dereference) and resource (a memory id to its full stored episode plus consolidated_into), and clarifies what the payload contains. It differentiates the episode payload from the canonical facts it produced, but does not explicitly contrast with near-siblings like memory_fact_get or memory_episode_summary.

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

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

Usage is implied: you call it when you hold a memory id from search results or a fact's source_entries and want the full episode. The 'as in search' clause hints at behavioral parity with search, but there is no explicit when-to-use versus alternatives such as memory_fact_get.

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 real behavioral value beyond them: transitive/inverse edges arrive pre-derived and are flagged derived:true with rule provenance. It does not explain the non-idempotent hint or cost/limits, but the derived-edge semantics are genuinely useful.

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

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

Three compact sentences, front-loaded with the core action and followed by the derived-edge caveat. The explicit 'Returns:' line is somewhat redundant given an output schema exists, but it is brief rather than 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 read-only traversal tool with an output schema and safety annotations, the description is largely sufficient: it states scope, the pre-derived edge semantics, and the return keys. Nothing an agent needs to invoke it correctly is missing, though a note on traversal cost or depth limits would round it out.

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

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

Schema description coverage is 100%, so the schema already documents entity, depth, to, include_facts, and relation_filter. The description adds no extra parameter semantics (e.g., depth interaction with relation_filter or path folding behavior beyond what the schema states), so the baseline 3 applies.

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

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

Specific verb+resource: 'Read an entity's graph neighborhood: nodes, typed edges, and each node's canonical facts.' This is clearly distinct from the graph mutators (memory_graph_relate/unrelate) and review tools, but the description never names a sibling to route against, so it stops short of explicit 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 by 'read an entity's graph neighborhood', so an agent can infer it is the traversal/expansion tool. However, with ~40 siblings including memory_search, memory_recall, and memory_fact_get, there is no explicit when-to-use-this-vs-that guidance or exclusion criteria.

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

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

Annotations already declare the mutation/safety profile (readOnly=false, destructive=true, idempotent=false), and the description adds meaningful behavior on top: entities auto-create and resolve through aliases, re-asserting an edge bumps confidence (which explains the non-idempotent hint), and unknown relations are rejected with suggestions. No contradiction with the annotations.

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

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

Front-loads the action and an example, then behavior, then the return shape, in a compact paragraph with no filler. Dense but each sentence carries information; the only minor redundancy is restating the return shape despite an output schema existing.

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

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

For a 7-parameter mutation tool, the description covers the critical unknowns an agent needs: auto-creation side effects, alias resolution, confidence bumping on re-assert, the rejection/suggestion path, and the fallback tool. With full schema coverage and an output schema present, nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents src/dst/relation/confidence/origin/types, including the closed relation registry and its normalisation/rejection behavior. The description reinforces the triplet shape with an example but adds no syntax or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource ('Assert a typed relation between two entities') and grounds it with a concrete triplet example ("web-app", "runs-on", "host-1"). It also distinguishes itself from the vocabulary-management sibling memory_relation_define, so an agent can identify the tool's role 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 explicit branch guidance for the failure case: on a rejected relation, pick a suggestion, fall back to related-to, or call memory_relation_define to grow the vocabulary. This names an alternative tool and the condition that selects it, though it does not state when to prefer this over other writes like memory_store or memory_set_add.

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, and the description is consistent with them. It adds meaningful context beyond the annotations: 'forgets retire, never delete', that relate writes the relation edge and dismisses the pair, and what accept_merge/accept_junk actually do to data. It stops short of disclosing auth/permission needs or irreversibility per action.

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

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

Purpose is front-loaded in one sentence, followed by a scannable action list and a one-line return note. The awkward indentation and the split of some entries across lines cost a little, but there is no filler and each line carries information.

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

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

An output schema exists, so the brief 'per-action dict; {error} on bad input' note is sufficient. All 11 enum values are described, and with 0 required params the default of `list` is implied by the description. Missing only per-action required-parameter hints, which would help an agent call non-default actions correctly.

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

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

Schema description coverage is 89%, so the schema already documents nearly every parameter and even maps params to actions (e.g. 'relate/dismiss_pair: the first entity'). The description's param mentions ('store + src (the retired key)', 'settle an edge proposal by id') largely restate 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?

States a specific resource (the graph review queue) and frames it as 'deep-dream proposals that need a verdict before they touch the graph', then enumerates all 11 actions with one-line semantics. It distinguishes itself from siblings like memory_consolidate and memory_dream by tying the queue to dream proposals, but it never disambiguates the `relate` action from the sibling tool memory_graph_relate, which appears to write the same kind of edge.

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 per-action lines imply when each action applies ('relate' for related-not-duplicate, 'accept_junk' for over-extraction artifacts), which is real guidance. However, there is no explicit when-to-use-this-tool-vs-alternatives statement, no prerequisites or ordering, and no indication of which actions require which params before calling.

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 covered. The description adds valuable non-obvious behavior: the edge is marked superseded but kept for audit, and re-asserting revives it. This goes beyond annotations by explaining the audit/revival semantics. Minor gap: doesn't explicitly note non-idempotency, but annotations cover 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 sentences, front-loaded with the core action (retract a relation) followed by the behavioral detail (audit-kept, revival). 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?

Given annotations cover safety (destructive, not idempotent) and an output schema exists (so return details are not needed), the description provides sufficient context for correct invocation. A slight gap remains: no explicit guidance on when to prefer this over nearby alternatives, but the core behavior is well-specified.

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

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

Schema coverage is 100%, so the schema already documents src, relation, and dst. The description adds no additional semantics for these parameters. 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 (retract) and resource (a relation/edge in the memory graph), and distinguishes itself from the sibling memory_graph_relate by describing the opposite operation. An agent can distinguish this from graph_relate without opening 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?

Clear implied context: use when a relation should be retracted / removed from graph results. The mention of revival on re-assertion gives the agent a hint about reversibility. However, no explicit 'when to use this vs alternatives' (e.g., vs memory_forget, memory_supersede, memory_set_remove) is given.

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 adds real context beyond them: oldest-to-newest ordering, the fields returned per version (writer/session, tx/valid time, age), and the ~30d compaction caveat. The compaction note is a genuinely useful behavioral trait not visible in any structured field.

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

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

Dense but front-loaded: purpose first, then mode breakdown, then return shapes. Each clause carries information (mode, ordering, fields, caveat) rather than filler, though the inline return-shape enumeration is somewhat verbose given 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?

For a two-mode read tool with a documented output schema and full parameter coverage, the description covers mode selection, ordering, returned fields, and a data-retention caveat. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents attribute ('omit for chain mode') and as_of ('slot mode only'). The description reinforces the mode-switch meaning of attribute but adds little syntactic detail beyond what the schema states, 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 (read) and resource (an entity's past) and cleanly splits the tool into two named modes with distinct semantics. An agent can tell exactly what it does without opening the schema, and the two-mode framing distinguishes it from simple retrieval siblings like memory_get.

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

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

Gives explicit mode-selection logic (attribute given = slot mode, omitted = chain mode) and parenthetical example questions that map intent to mode. It stops short of naming alternative sibling tools or exclusion conditions, so it is clear context without 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 cover the safety profile (readOnly, non-destructive), but the description adds substantial beyond-annotation context: lessons describe their source run rather than the current one, polarity flags dead-ends, and re_verify marks entries whose facts have changed. The anchoring warning is a genuinely useful behavioral caveat.

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, timing, application caveats, and return shape are ordered sensibly with the action front-loaded. It is a little dense and tangential in the middle (the anchoring/stale-framing aside), but nearly every sentence carries meaning.

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

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

With a real output schema present, the description plausibly does not need to spell out return values, yet it still enumerates the entry fields (polarity, re_verify, confidence, etc.), which helps interpretation. Coverage of how to read results is complete; pagination/limits are handled by top_k in the schema.

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

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

Schema description coverage is 100%, so query, top_k, and verbose are already documented. The description adds only a loose restatement of query ('similarity to the task at hand') and no extra syntax or format guidance, 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 (search) and a specific resource (learned lessons / procedural memory), which cleanly separates it from the general-memory siblings like memory_search, memory_recall, and memory_world_search. An agent can identify the memory category without opening the schema.

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

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

Gives concrete when-to-call guidance ('Call at the START of a task') and how to apply results (apply where today's specifics match, heed polarity '-' entries, re-derive re_verify entries). It stops short of naming a specific alternative sibling or stating when NOT to use it, so it is strong but not exhaustive.

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

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

Despite annotations already flagging readOnlyHint=false and openWorldHint=true, the description adds substantial behavioral context: adapter auth requirement, 24 h body retention with audit retention/redaction, rate limit 'urgent (6/h)', and a permission constraint ('Done: only maintainer/maintainer's delegate/clearer urgent'). These are meaningful disclosures beyond the annotations, though the telegraphic style makes some of them hard to parse.

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

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

The description is a dense, telegraphic wall of fragments rather than front-loaded prose; the first line leads with 'Adapter auth required' instead of the tool's purpose. While few words are outright filler, the structure actively impedes comprehension and fails to front-load the most decision-relevant information.

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

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

For an 11-parameter, 4-action tool with 0% schema description coverage and a separate output schema, the description covers auth, action behaviors, retention windows, cursor rules, and wake/ring semantics fairly completely. The main shortfall is that the peer/clears/urgent parameters are not clearly disambiguated across actions.

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

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

Schema description coverage is 0%, so the description carries the full parameter burden and does compensate for many: 'to' format ('8+ hex prefix or project:<name>/all'), 'text <=8192 UTF-8 bytes', 'unique request_id, retry unchanged', cursor semantics for 'after', 'limit <=50', and 'message_id(s), comma-separated'. But several parameters (peer, clears, urgent) appear only as ambiguous fragments with no clear tie to an action, leaving real gaps.

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 never states the tool's purpose in a clean verb+resource sentence; it opens with 'Adapter auth required' and dives straight into per-action detail. The send/receive/ack/history actions do convey that this is a peer-messaging tool, but an agent must infer the overall purpose rather than read it, and there is no differentiation from siblings like memory_agents or memory_search.

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

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

Action-specific usage is implied through fragments ('omit: replay unacked', 'Read-only', 'Ack message_id(s): read, not done'), which give some sense of when each action applies. However there is no explicit when-to-use vs when-not guidance, and no routing against alternative sibling tools, so usage remains inferred rather than stated.

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

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

Annotations already declare the write/non-idempotent/non-destructive profile, so the description's added value is the Postgres dependency ('needs Postgres'), the credit mechanism for used_ids, and the one-hour expiry window. It also explains the used_ids_* result buckets, which clarifies what a partial or failed attribution looks like. It stops short of stating permissions or failure behavior beyond the used_ids_errors bucket.

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 front-loaded in the first sentence, followed by dependency and return information. The long used_ids_* enumeration is informative but dense and partly duplicates the output schema, slightly bloating the definition.

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

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

For a 7-parameter write tool with annotations and an output schema, the description covers purpose, environment dependency, the credit/timing constraint, and partial-failure semantics. Nothing critical is missing, though the relationship to sibling memory tools is unstated.

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

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

Schema description coverage is 100%, so every parameter is already documented, including used_ids, about, detail, and polarity. The description mostly restates the used_ids semantics ('the relevance label only you can write', 'at most 50', last-hour crediting) rather than adding new meaning. 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?

The description gives a specific verb+resource ('Record a procedural outcome') and enumerates the recorded outcome kinds (worked, failed, corrected). It is clearly distinguishable from storage siblings like memory_store or memory_message in substance, though it never names an alternative to route against.

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 'what worked, failed, or was corrected' and by the instruction to log used_ids 'before that lapses' (a one-hour window), which is genuinely actionable timing guidance. However, there is no explicit when-to-use/when-not statement and no named alternative among the many memory_* siblings.

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

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

Annotations cover only the safety profile (readOnlyHint true, destructiveHint false); the description goes well beyond by disclosing capping behavior (10/15/6 with per-hop reservation), fact cap of 5, the meaning of re_verify on corrected memories, pinned constraint facts, and what truncated/searches_issued implies about missing data. This is unusually rich behavioral context.

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

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

Purpose is front-loaded in the first sentence and every later sentence carries operational detail (caps, re_verify, truncated). It is dense rather than bloated, though 'Read-only' duplicates the readOnlyHint annotation and the return-field listing slightly overlaps 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?

Despite having an output schema, the description supplies the interpretive layer the schema cannot: what capping, re_verify, pinned facts, and truncated mean for the agent's next action. Combined with the doc pointer, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents hops, top_k, and verbose. The description still adds meaning by tying hops to the truncated failure mode ('lower hops') and explaining why results are capped independently of top_k, which the schema does not spell out.

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 (multi-hop retrieval) and resource (knowledge graph) plus the exact class of question it serves (relational, link-following). It explicitly distinguishes itself from memory_search, which 'can't chain', so an agent can route without opening either schema.

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

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

Names the alternative (memory_search) and the condition that selects it, gives a fallback rule when low_confidence is true, and tells the agent to narrow the question or lower hops when truncated. When-to-use, when-not, and recovery paths are all explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds non-obvious behavior: the ordering guarantee and that sources/episodes/tags filters AND-combine, which an agent could otherwise assume was OR. It does not need to explain return values since an output schema exists.

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

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

Three short sentences, zero waste, with the core identity (most recent N, newest first) front-loaded before the usage hints and the filter-combination 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?

For a 5-param, zero-required read tool with full schema coverage, annotations, and an output schema, nothing an agent needs is missing: ordering, scope, filter interaction, and use contexts are all stated.

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 goes beyond the per-parameter schema text by specifying that the three filter parameters AND-combine, a cross-parameter semantic not derivable from individual field 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), resource (memories), quantity (N), and ordering semantics ('newest first — timestamp order, not relevance'). The 'not relevance' clause implicitly contrasts with memory_search, letting an agent distinguish the two without opening either schema.

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

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

Names two concrete use cases ('what did I just store?' and 'catching up at the start of a session'), which is clear positive guidance. It stops short of explicitly naming memory_search as the alternative for relevance-based retrieval or stating when-not to use it, so it falls just below the top tier.

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 disclose that this is a non-read-only, non-idempotent, non-destructive operation, so the safety profile is covered. The description adds the useful effect ('resist forgetting') but does not address whether repeated calls compound strength (relevant given idempotentHint=false) or how invalid ids are handled.

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

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

One front-loaded sentence that leads with the action and its rationale. 'Read first, then reinforce' mildly restates the earlier 'after reading it via memory_get' clause, a small redundancy.

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

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

For a one-parameter mutation with an output schema, the description supplies the intent, the trigger, and the ordering. The remaining gap is idempotency/compounding behavior, which is a minor omission given the output schema carries the response.

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 described in the schema, so the baseline is 3. The description adds only a light link between the id and the memory_get workflow, without new format or constraint details.

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 ('Strengthen') and resource ('one memory'), and clarifies the effect ('helps it resist forgetting'). It is clearly distinguishable from siblings like memory_forget, memory_supersede, and memory_reinstate, which imply opposite or different semantics.

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

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

Gives an explicit trigger — only after reading via memory_get and finding it 'genuinely useful' — and states the ordering constraint ('Read first, then reinforce'). It does not, however, name specific alternative siblings or state when reinforcement should be skipped in favor of them.

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

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

The description adds substantial context beyond the annotations: backend constraint ('PostgreSQL only'), an auth requirement ('requires a named principal'), a precondition ('exact retirement preimage'), and explicit refusal/scope behavior ('Refuses trace-invalidated entries and never changes derived cortex'). These go well beyond the destructive/idempotent hints the annotations already 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?

Four dense sentences with the core verb+resource front-loaded and each clause carrying distinct information (backend, auth, precondition, refusal behavior, retry). No filler, though it is slightly more compact-packing than a maximal 5 might demand.

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

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

For a 9-parameter mutation tool with an output schema, the description covers auth needs, preconditions, refusal cases, mutation scope, and retry semantics; return values are appropriately left to the output schema. A minor gap is that the resulting state transition after reinstatement is only implied.

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 9 parameters in detail. The description adds only indirect context ('by durable ID', 'same UUID', 'exact retirement preimage'), which reinforces but does not extend what the schema provides. 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 — 'Reinstate one reviewed retired entry by durable ID' — which distinguishes it from the opposite operation (memory_supersede) and from memory_reinforce/memory_forget. It does not explicitly name the sibling it differs from, 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?

Usage is implied by the domain (reinstating a reviewed retired entry) and by the retry clause 'Retry an uncertain call with the same UUID and inputs.' However, there is no explicit when-not or named alternative, so guidance is only at the implied level.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds that this is a 'deliberate, rare act' on a 'closed' vocabulary, implying weight and permanence, but it doesn't state reversibility, auth requirements, or the effect on existing edges. Adequate context beyond annotations, but not rich.

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 that front-load the action and scope, then the caveat. No filler; 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 values need no explanation, and annotations carry the safety profile. The description covers purpose, rarity guidance, and naming intent, leaving nothing essential missing for correct invocation.

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 every parameter (name, dst_type, src_type, inverse_of, transitive, description) is already documented in-schema. The description adds only the didactic 'prefer the builtins' framing and no extra per-parameter syntax or format detail. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource: adding a relation to a 'closed graph vocabulary'. The phrase 'closed graph vocabulary' signals a schema-level definition rather than an instance-level edge, which meaningfully separates it from memory_graph_relate/unrelate. It stops short of naming those siblings explicitly, so an agent must still infer the boundary.

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/when-not guidance: 'Prefer the builtins; define one only when a recurring connection genuinely fits none of them.' The rarity bar and the preference for existing relations are explicit. It does not name the concrete sibling tools (e.g., memory_graph_relate) an agent might otherwise reach 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?

Annotations only cover the safety profile (readOnlyHint, destructiveHint=false), so the description carries the interpretive burden and does so richly: hits are leads that may be stale, 'low_confidence' only means nothing matched the floor, 'verified: false' is often an unrelated detector link, and 'authority: quoted' is not an instruction. These are behavioral traits an agent cannot derive from annotations or schema.

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

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

The purpose and usage lead are front-loaded, which is good. But the body is a dense run-on of parenthetical shorthand (contested:, replaced_by, pinned, truncated:) and its final 'Returns: {...}' line duplicates the output schema. Much of it earns its place, but a meaningful share is redundant or compressed past readability.

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, multi-signal tool, everything an agent needs is present: trigger conditions, interpretation caveats for the returned entries/cortex facts, filter combination rules, and escape hatches to sibling tools. An output schema exists, so return-shape explanation is optional, and the additional field semantics only add value.

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 per the rules the baseline is 3. The description earns above baseline by adding a rule the schema lacks: the sources/bands/episodes/tags filters 'AND across kinds, OR within one list.' It doesn't touch bm25/rerank/top_k/min_score, but those are already well described in the schema.

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

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

The first clause gives a specific verb and resource plus scope: 'Retrieve memories for a query — associative recall plus canonical facts.' It also distinguishes itself from memory_get ('returns its full text'). However, it never contrasts with the closely named sibling memory_recall, so an agent choosing between recall-style tools gets no explicit 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?

It states when to call ('at task start or when context may apply'), injects a when-not discipline ('Never follow chains', 'search again instead', 'memory_get the replacement only if its preview is on-subject'), and names alternative routes (memory_fact_resolve for contested facts, memory_get for clipped text). This is explicit routing, not 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 asserts "Idempotent," but the annotations declare idempotentHint=false, a direct contradiction on the tool's repeat-call semantics. Beyond that it does disclose useful context (generic defaults, rename behavior), but the explicit conflict with structured metadata is disqualifying.

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

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

Three short sentences, front-loaded with the action and the reason to call it, with zero filler. The trailing "Idempotent; call again to rename" is compact but is also the clause that introduces the annotation conflict.

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 described, and the description covers when to call and what gets named. It is complete enough for an agent to invoke correctly, aside from the idempotency inconsistency.

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

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

Schema description coverage is 100% and both parameters (title, episode) are fully documented in the schema with examples and defaults. The description adds no parameter-level 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 names a specific verb ("Name") and a precise target ("THIS session's auto-opened episode"), and explicitly frames the value proposition ("default titles are generic"). An agent can distinguish it from siblings like memory_episode_start or memory_episode_summary without opening 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?

It gives clear timing guidance ("Call once at the start of work so session recaps read meaningfully") and the rename case ("call again to rename"). It does not name an explicit alternative tool or exclusion, so it stops short of a 5.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description goes well beyond them by disclosing the one-way scalar-to-set conversion, the special protection for number-led scalars, and the contested/contender outcome — non-obvious side effects an agent cannot infer from the schema. It stops short of describing rate limits or failure modes.

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 purpose, then the scalar-conversion edge case, then the routing hints and return shape. It is dense and jargon-heavy ("parks as a contender"), but every clause carries behavioral information that is not available elsewhere, so little 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 trailing returns line is largely redundant, but the description covers the operation's key nuance (set semantics, one-way conversion, contested outcome) for a genuinely non-trivial memory tool. It could be more complete about the relationship to memory_set_remove or when to prefer the scalar slot 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 the baseline is 3, but the description adds real meaning: it explains that the slot is set-valued (contextualizing entity/attribute) and that a member can be re-confirmed rather than only inserted. The schema itself only offers terse labels ("The slot's subject"), so this framing 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+resource (add/confirm a member of a set-valued slot) and immediately disambiguates it from scalar single-value semantics ("many concurrent values, not one NOW value"). It also names the sibling read tool (memory_fact_get) and the resolution tool (memory_fact_resolve), so an agent can place it in the family without opening 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?

Clearly signals when this tool applies: set-valued slots with many concurrent members. It routes contested adds to memory_fact_resolve and reads to memory_fact_get. It does not explicitly say when NOT to use it (e.g., the scalar alternative memory_fact_set), which keeps it short of a full 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds real context beyond them: '(audit row kept)' discloses soft-delete/retention semantics, telling the agent the retraction is recoverable and auditable. It does not address idempotency (idempotentHint=false) or what happens on a repeated 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?

Very short and front-loaded: the operation and its audit behavior come first. The 'Returns: {...}' line is largely redundant since an output schema exists, which is the only wasted space.

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

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

For a 3-required-param mutation with annotations and an output schema, the definition covers purpose, retention semantics, and the read path. Gaps are minor: no idempotency note and no statement of what happens when the member is not currently present.

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

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

Schema description coverage is 100%, so entity/attribute/member are already documented. The phrase 'current set member' adds a mild constraint that the member must be currently present, but no format or error semantics 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: 'Retract one current set member'. The word 'Retract' contrasts implicitly with the sibling memory_set_add, and 'one' bounds the operation. It stops short of naming the add/supersede alternatives outright, so the sibling contrast must be inferred.

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 only routing guidance is 'Read with memory_fact_get', which points at the read path but does not say when to retract vs. using memory_supersede, memory_forget, or memory_fact_resolve. Usage is implied by the verb rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile for this read-only tool. The description adds only a list of reported metrics, which the output schema already provides, and gives no additional behavioral context such as auth needs, rate limits, or side effects.

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 first front-loads the resource and its metrics, the second gives the use case. No wasted words.

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

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

For a zero-parameter read-only stats tool with an output schema and comprehensive annotations, the description covers purpose and usage adequately. It could be slightly richer about what the metrics mean or when to prefer other introspection tools, but nothing critical 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?

Zero parameters, so the baseline is 4. The description adds no parameter information, but none is needed because the schema is empty.

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 ('Memory-bank vital signs') and enumerates the exact metrics returned (store occupancy vs capacity, hit rates, true-drop count, totals), so an agent knows what the tool does. However, it does not name a sibling or use a clear verb like 'get', so it is clear but not maximally differentiated.

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 explicit when-to-use guidance: 'Use to gauge how much has been remembered or to diagnose why retrieval feels off.' It does not mention when not to use it or name alternative introspection tools (e.g., memory_agents, memory_toolset), so it gives clear context without exclusions.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description reinforces this by disclosing that near-duplicates are dropped rather than erred, with stored=False and reason='below_surprise_threshold'. It adds real behavioral context beyond the annotations, though it doesn't spell out what a store overwrites or any permission/rate constraints.

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 purpose in the first sentence and then gives a compact decision procedure. It is dense but every clause carries guidance; the parenthetical return-key detail is slightly redundant given the output schema, which keeps it just short of a 5.

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

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

With an output schema present, the description need not explain return values, and it still summarizes them. For a seven-parameter mutation tool, it covers purpose, routing, dedup behavior, and the volatile-value caveat adequately, though it omits any note on overwrite/permission semantics.

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

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

Schema coverage is 100%, so the schema documents all seven parameters, and the description does not map its PERSIST/RE-VERIFY guidance onto the authority or distortion_tolerance enums. It even references a freshness_class parameter that lives on memory_fact_set, not this schema, so it adds little beyond the structured fields. 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 (Store) and resource (one durable fact, decision, or observation) and immediately distinguishes itself from memory_fact_set, which is named as the destination for canonical NOW. An agent can tell what this tool is for and how it differs from the closest sibling.

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 guidance (proactively, one claim per call) and a decision procedure: persist durable claims, leave task-scoped detail in context only, re-verify volatile values, ask when ambiguous. It also names the alternative (memory_fact_set) and the condition that selects it, leaving little 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 (destructiveHint/readOnlyHint/idempotentHint). It discloses that the old entry is retained-but-flagged, that failed selectors produce no mutation, that there is no similarity fallback, and how derived facts are FLAGGED (never rewritten) with truncation-cap semantics — all material behavior an agent needs before mutating.

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 and selector rules before the returns detail; every section is dense with operative content. The Returns block is long and partly overlaps the output schema, but its semantic interpretation (has_current_value, truncation flags) is not pure repetition.

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

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

For a destructive mutation with an output schema and full annotation coverage, this is essentially complete: purpose, selector rules, failure behavior, and return semantics are all covered. Minor redundancy with the output schema keeps it from a 5.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: 'Use exactly one selector,' telling the agent entry_id and old_text are mutually exclusive alternatives and that entry_id is preferred. That constraint is not obvious from the schema alone.

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

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

States a specific verb+resource ('Mark a stored memory obsolete and record its replacement') and immediately clarifies the distinguishing semantic: the old entry is kept but flagged, so retrieval ranks the correction higher. This separates it from deletion-style siblings like memory_forget without needing to name them.

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

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

Gives clear operating guidance: 'Use exactly one selector,' failure modes (missing/retired/ambiguous targets cause no mutation), and the remediation ('search again and resubmit an ID'). It does not explicitly name which sibling to use instead of this tool (e.g. forget vs supersede vs reinstate), so it stops short of full alternative 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?

The description adds behavioral context beyond the annotations: it specifies the tool is free and instant, scoped to credential/writer identity, and that expanding is required because 'clients reject hidden-tool calls.' It does not explicitly state what happens to visible tools when collapsing (e.g., whether they become hidden or inaccessible), which would be useful for a mutation tool. Annotations indicate non-read-only and non-destructive, which is consistent, but the description adds value without fully covering the consequences of collapse.

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

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

The description is compact and front-loaded: it starts with the core purpose, then lists tier contents, then adds critical usage guidance. Every sentence earns its place without redundancy.

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

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

Given the tool's complexity (managing visible toolset tiers) and the presence of an output schema (which likely reports status or tier changes), the description is largely complete for an agent to invoke correctly. It covers actions, tier contents, and the necessity to expand first. It could be improved by noting the exact effect of 'collapse' (e.g., whether tools are removed or just hidden) to fully inform the agent, but it is sufficient for most use cases.

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