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

With no annotations provided, the description carries the full behavioral burden. It discloses that the operation writes to a separate reference bank and returns a specific object {source, chunks_stored, chunks_total}, giving the agent a clear outcome model. It does not mention overwrite/idempotency behavior or error conditions, but the core mutation and return contract are transparent.

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: the first sentence establishes the action and store semantics, and the second sentence gives the return contract. There is no filler or redundant restatement; every sentence contributes.

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

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

For a simple 2-parameter tool with complete schema descriptions and an output schema, the description provides sufficient context: the store purpose, the file domain, and the return shape. Minor gaps remain around duplicate handling and failure modes, but an agent can invoke this tool correctly with the supplied information.

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. Both path and source are already fully described in the schema: path is server-side and container-aware, and source defaults to the filename. The main description adds no parameter-level detail beyond what the schema provides.

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

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

The description states a specific action, 'Index a file into the reference bank,' and defines that bank as a separate store for background documents (papers, manuals, codebases) kept apart from conversational memory. This clearly differentiates document_ingest from the many memory_* siblings and from document_search, which is the retrieval counterpart.

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

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

The description gives clear context for when to use the tool: for background reference documents such as papers, manuals, and codebases, and it explicitly distinguishes these from conversational memory. It does not name the alternative tool (e.g., memory_store), but 'kept apart from conversational memory' strongly implies the boundary between this tool and the memory_* family.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the search is scoped to ingested documents and deliberately excludes conversational memories. The verb 'search' also implies a read-only operation, so no hidden side effects are suggested.

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

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

Two sentences with no filler. The core purpose is front-loaded, and the alternative tool is named in the second sentence. Every word earns its place.

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

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

The description fully scopes the tool, names its alternative, and the schema covers both parameters. With an output schema present, return-value details are not required. Nothing essential is 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%, already explaining both query ('Natural-language description of the passage wanted') and top_k ('Max chunks returned'). The description adds no parameter-specific detail, but the schema fully handles that burden.

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

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

The description states a specific verb and resource: 'Search the reference bank only' — ingested documents, excluding conversational memories. It clearly distinguishes document_search from memory_search, and the scope 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?

The description explicitly tells the agent when to use this tool (docs only) and when to use an alternative ('For docs AND memories together, use memory_search'). This is direct routing with no inference required.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses the core effect—facts and graph lookups under either name land on the same node—and the return value, but does not mention edge cases like overwriting existing alias bindings, behavior for missing entities, or reversibility.

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

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

Two tight sentences, front-loaded with the action, containing a helpful example and a clear statement of the return value. No redundant repetition of schema information.

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

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

For a simple tool with two required parameters and an output schema, the description adequately covers what it does, how it behaves, and what it returns. The main gaps are usage routing and mutation edge cases, which are not essential for basic 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 coverage is 100%, so the baseline is 3, but the description adds relational meaning beyond the schema: the example illustrates the direction alias → canonical entity and explains that both names resolve to the same node. This enriches the minimal 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?

States a specific action, 'Bind an alternative name to an entity', with a concrete example 'pg → postgres', clearly identifying it as alias management rather than generic memory storage. It is distinct from siblings by function, though it does not explicitly call out any sibling by name.

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 no explicit guidance on when to use this tool versus alternatives such as memory_supersede or memory_graph_relate. Usage is only implied by the purpose, with no exclusions, prerequisites, or 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It clearly states that matched entries are marked superseded, the new text is stored fresh, and the memory bank shrinks without losing the audit trail. This gives the agent a solid model of side effects without overclaiming.

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, with the primary action stated first and no filler. The return shape is included as a separate line, and every sentence adds information relevant to invoking the 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?

For a 4-parameter tool with an output schema and full schema coverage, the description covers the operation, side effects, and return value. It is slightly incomplete only in not explicitly guiding selection among the many closely related memory tools.

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 input schema already documents every parameter. The description adds contextual color ('canonical note', 'stored fresh') but does not need to duplicate parameter-level detail, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('Replace') and resource ('a cluster of near-duplicate memories'), making the core purpose immediately clear. It is not a tautology and is distinguishable from related tools like memory_store or memory_forget, though it does not explicitly name a sibling for comparison.

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

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

The phrase 'cluster of near-duplicate memories' implies the appropriate context, and the tool clearly is meant for consolidation rather than simple storage. However, it does not explicitly say when to prefer this over siblings like memory_supersede or memory_consolidation_candidates, leaving some routing to inference.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It does so well by framing the tool as a read-only finder ('read the clusters') and explicitly deferring the mutation to memory_consolidate. It also discloses the return shape. It could be stronger by explicitly stating the tool does not modify memories and clarifying what happens when both query and episode are supplied, but it is not misleading.

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. The first sentence states the core purpose, the second gives the actionable workflow, and the third states the return shape. Every clause earns its place, and the bolded instruction to synthesize and commit via memory_consolidate adds valuable workflow context without padding.

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

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

Given eight optional parameters, full schema coverage, and an output-schema hint, the description is sufficiently complete for an agent to use it correctly. It supplies the return format, workflow, and anchor strategy. The only notable gaps are the lack of an explicit 'read-only/no side effects' statement and no guidance on query/episode mutual exclusivity, but these are minor because the workflow implies them.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-specific meaning beyond the schema: it re-emphasizes query and episode as anchors but does not explain tags, sources, top_k, max_clusters, min_cohesion, or min_cluster_size in more depth. The schema already handles parameter semantics adequately.

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 opens with a specific verb-resource pair: 'Find clusters of near-duplicate memories ripe for consolidation.' It clearly differentiates this from memory_consolidate by positioning it as the discovery step before commit. The concrete example phrase 'the same thing phrased five ways across five sessions' makes the purpose vivid and 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?

The description gives clear usage context: anchor with query or episode, inspect clusters, synthesize a canonical note, then commit via memory_consolidate. It explicitly names the related sibling tool for the follow-up action. It does not enumerate exclusions versus memory_search or memory_recent, but the consolidation-specific framing is enough to guide selection.

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

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

With no annotations, the description carries the behavioral burden and discloses side effects: status is read-only, pull writes facts via memory_fact_set and then commits, deep can write with a snapshot, and rollback reverts facts/events while keeping traces/cursor. It does not address idempotency or commit as a standalone behavior, but nothing contradicts 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?

The description front-loads a one-line purpose, then presents a scannable action list with no redundant prose. Every bullet adds operational information, and the return note is appropriately brief.

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

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

For a complex seven-action tool with no annotations, the description covers most behavioral and workflow context, and the output schema covers return values. It is slightly incomplete because the commit action has no bullet of its own and there is no direct comparison to memory_consolidate, but the schema fills the commit cursor requirement and the overall picture is actionable.

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 83%, so the baseline is 3, but the description adds real value by decoding the action enum and linking parameter semantics to workflow (pull then commit, dry run unless apply, rollback targeting a pass). It leaves snippets to the schema, which already documents it, so the description complements rather than restates 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 opening sentence states the tool's purpose — consolidating recent memories into canonical facts and graph structure — and the action list makes the operational scope concrete. It does not explicitly contrast itself with sibling tools like memory_consolidate, so it stops short of full sibling differentiation.

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

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

Each action bullet provides usable context, including status being read-only, deep being a dry run unless apply is set, and rollback reverting a committed pass. However, there is no when-not or selection guidance against likely alternatives such as memory_consolidate, so the agent must infer when this orchestration tool is preferred.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the state transition ('closes', 'pops') and the scope limitation ('only within your own session's subtree; the session root is never closed'). It does not specify behavior when no sub-episode is open, but the core mutating behavior is clearly 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?

The description is one front-loaded sentence that states the action, target, and result with no filler. The important constraint is placed in the parameter schema, which is the right location for it. Every word earns its place.

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

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

For a one-parameter tool with a well-documented schema and an output schema, the description covers the normal invocation scenario and the key limitation. It does not spell out edge cases like calling with no open sub-episode, but the root-never-closed note partially covers boundary behavior. Overall, it is complete enough for an agent to select and use the tool correctly in typical cases.

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

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

The input schema has 100% description coverage and explains the single optional parameter well, including that 'episode' acts as a session handle and that the root is never closed. The tool description itself does not add parameter-level meaning beyond the schema, but it does not need to because the schema already handles it. Baseline 3 is appropriate here.

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

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

The description names a specific action ('Close'), a specific resource ('current open sub-episode'), and the outcome ('pop back to its parent'). This clearly differentiates it from sibling tools like memory_episode_start and memory_episode_summary. There is no ambiguity about what the tool 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?

The description states a clear condition for use: a sub-episode is currently open and should be closed while returning to its parent. The parameter description adds a useful exclusion by noting that the session root is never closed and that only the caller's own session subtree is affected. It does not explicitly name alternative tools, but the start/end relationship is obvious from the sibling list.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It states that the operation is stateful, nests under the session episode, attaches id/title to memories stored while open, and that memory_episode_end pops back. It leaves some edge behavior implicit, such as repeated starts while a sub-episode is already open, but the core side effects are clearly 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?

The description is two compact sentences that front-load the purpose and then give the lifecycle and close behavior. Every clause earns its place; there is no filler, repetition, or redundant per-parameter prose.

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 stateful scoping tool with a complete schema and an output schema, the description covers the operation, the reason to use it, and the complementary end call. The only omissions are edge-case behaviors such as what happens if no session episode exists or if called when a sub-episode is already open, which would push it to full completeness.

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

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

Schema description coverage is 100%, so the input schema already documents title, hint, and episode. The description only reinforces that title is carried by stored memories and adds no new parameter semantics. Baseline 3 is appropriate here.

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?

Description uses an active verb ('Open') with a clear resource ('a named sub-episode') and explains that it nests under the session episode. It also distinguishes itself from the sibling close/summary/session-title tools by describing the episode-scoped storage effect. An agent can tell at a glance what this tool is for.

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

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

The description gives a clear use context: open a sub-episode when you want subsequently stored memories to carry its id + title for episode-scoped search. It names the paired closing tool, memory_episode_end, but does not explicitly list when-not-to-use or alternatives, so it stops just short of full 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?

With no annotations provided, the description carries the transparency burden. It does well by stating what the tool returns and explicitly documenting the unknown-id fallback of `{found: false}`. It does not explicitly state that the tool has no side effects, but 'summary' and the return behavior strongly imply a read-only operation.

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

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

The description is compact and front-loaded: it lists the key content, gives a natural-language usage cue, and includes the important edge-case return value. No sentence is wasted.

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

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

For a one-parameter tool with an output schema, the description is sufficiently complete. It covers what the call returns, how to identify an unknown episode, and the source of valid ids (via the schema). Nothing critical is 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?

The input schema already documents the only parameter with a clear description ('An episode id, as it appears on search/recent results'), and schema coverage is 100%. The tool description adds little beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool's focus: stats, tag/source distribution, and recent entries for one episode. The plain-language cue 'summarise what we worked on' makes the intent obvious, though it does not explicitly distinguish this from sibling tools like memory_stats or memory_recent.

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 context is implied: you use this when you want a summary of a single episode, and the id should come from search/recent results. However, the description does not explicitly state when to prefer this tool over alternatives or when not to use it.

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

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

With no annotations provided, the description fully carries the behavioral burden. It reveals the meaning of null versus unknown, set-valued slot behavior, empty-set semantics, conflict signaling via contenders, the candidates field on empty slots, the re_verify flag, and its eviction/deletion limitation. This is unusually transparent and leaves little to guess.

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?

Although the description is long, it is densely packed with essential behaviors: value cardinality, null semantics, set handling, return fields, conflict resolution, and re_verify caveats. It front-loads the core purpose and spends every sentence on operationally relevant details. No filler is present.

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?

This is a nuanced tool with edge cases, and the description addresses all major ones: empty-vs-unknown, set-valued slots, unresolved conflicts, candidate leads, graph-node references, and the re_verify flag. Since an output schema exists, describing the full return shape is less critical, but the description still adds valuable semantic context about what each flag means in practice.

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 clarifying that entity and attribute jointly define a slot with exactly one current value, and that attribute types (scalar vs set) change the returned shape. This is useful enrichment rather than repetition of 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 action (look up the one CURRENT value) and a specific resource ((entity, attribute) slot). It clearly distinguishes this from memory_search by explaining that a null record means EMPTY, not unknown, and that memory_search still finds context. This is far beyond a vague purpose.

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

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

The description gives clear context for when this tool is appropriate: retrieving the current value at a slot. It points to memory_search for continued context on empty slots and to memory_fact_resolve for unsettled conflicts. It stops short of an explicit exclusion list or a direct 'use X instead' statement for a sibling like memory_get, but the guidance is largely present.

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

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

With no annotations, the description plausibly carries the burden of explaining behavior. It adds a useful return contract showing success keys and the no-contender failure case, and it signals a human-in-the-loop requirement. It does not explicitly describe the mutation effect itself, but the accept parameter schema and the return keys together provide enough 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?

The description is two short, purposeful sentences: the first explains what the tool does, and the second gives the return shapes. There is no filler, and the core purpose is front-loaded.

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

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

For a simple three-parameter tool with a fully described input schema and an output schema present, the description is largely complete: it names the contested-slot context, the human-check requirement, and the possible outcomes. It could be more complete by explicitly stating side effects and exclusions, but it is not missing anything critical.

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 tool description itself adds no parameter-level meaning beyond what the input schema already provides, although the schema's 'accept' description is already rich.

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 ('Settle') and resource ('a CONTESTED fact slot') plus the human-check prerequisite. It is clear about what the tool does, but it does not explicitly differentiate itself from sibling tools such as memory_fact_set or memory_supersede.

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

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

The capitalized 'CONTESTED' and the phrase 'after checking with the human' give a clear trigger condition: this tool is for resolving contested fact slots only after human input. It provides clear context but stops short of naming alternatives or explicitly saying when not to use it.

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

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

With no annotations provided, the description carries the full burden, and it delivers: it discloses that new values supersede old ones with history kept, that conflicting writes park as contenders with action='contested', that authority and distortion_tolerance inherit slot labels unless restated, and it states the return shape. This goes well beyond a simple mutation one-liner.

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 front-loaded with the core purpose, followed by two short behavior paragraphs and a return line. Every sentence carries distinct information; there is no filler or repetition of schema content.

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

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

For a 9-parameter tool with an output schema and no annotations, the description covers the key behavioral edge cases (supersede vs contest), the resolution path, and the return enum. It could be slightly more explicit about what triggers a 'contested' classification (e.g., conflicting values on the same slot), but overall it is sufficient for an agent to invoke and interpret the 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. The description adds extra meaning to authority and distortion_tolerance by explaining the inheritance behavior, and it clarifies the semantic of 'value' as the canonical NOW. Other parameters 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 description opens with a specific verb and resource: 'Assert a canonical fact — insert, confirm, or correct a slot.' It clearly defines the operation and its three modes, and distinguishes itself from the related resolver by naming memory_fact_resolve as the settlement path for contested writes.

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 provides a clear context for use — asserting or correcting a canonical slot — and gives an explicit alternative when a write comes back contested: 'check with the human, settle via memory_fact_resolve.' It does not, however, state when to prefer this over nearby siblings like memory_store, memory_supersede, or memory_set_add, so it falls short of full when/when-not 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?

With no annotations provided, the description carries the full behavioral burden. It discloses that memory/fact entries are hard-deleted with no audit trail, world/lesson slots are retired with audit rows, that retirement is undone via memory_graph_review, and that ANY matching criterion deletes. This is substantial beyond what the schema conveys.

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 dense but every sentence earns its place: primary action, scope-specific destructive behavior, alternatives, matching semantics, and return/error shape. It is front-loaded with the core purpose and contains no filler.

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

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

For an 8-parameter, four-scope destructive tool, the description covers scope behavior, conditional parameters, audit implications, undo path, alternatives, and return values. With an output schema present, no critical operational information 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%, but the description adds critical parameter interplay: scope='memory' requires at least one of text/substring/source/episode/tag and these OR-combine, while other scopes require entity. This is exactly the kind of conditional semantics an agent needs and cannot infer 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?

The description opens with 'Forget from one memory store,' naming a specific verb and resource. It then distinguishes hard-delete vs. retire semantics across scopes and explicitly contrasts with memory_fact_set and memory_supersede, making the tool's purpose clear relative to siblings.

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

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

It explicitly states when to use alternatives: for 'now wrong, keep history' use memory_fact_set or memory_supersede instead. It also gives scope-specific parameter requirements and contrasts memory_forget's OR-combining matches with memory_search's AND behavior, giving clear selection 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?

With no annotations, the description carries the full transparency burden. It responsibly discloses a non-obvious side effect ('Reading it gently reinforces it') and a special forgotten-state return ({found: false, faded: true}). It does not elaborate on invalid-id behavior or exact reinforcement, but for a one-parameter getter this is meaningful disclosure.

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

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

Two front-loaded sentences with no filler: the first defines the action and payload, the second captures the relevant side effect and edge case. Every sentence 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?

The definition covers purpose, parameter source, side effect, and the main stale-episode edge case, while the output schema can handle return shape details. It is enough for a low-complexity get-by-id tool; the slight gap is absence of routing to sibling search/recent tools, but that is more a usage-guidance concern.

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

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

The only parameter entry_id is already fully described in the schema (memory id from search results or source_entries), so the description adds little parameter-specific meaning. The phrase 'Dereference a memory id' reinforces that the id is a reference, but this is minor; baseline 3 applies.

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

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

The opening verb 'Dereference' plus object 'memory id' and result 'full stored episode plus consolidated_into' states a precise operation. It clearly identifies the tool as id-based retrieval rather than search or fact lookup, even without naming a 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?

The description implies the tool should be used when an entry_id is already available ('Dereference a memory id'), but it never names alternatives or says when not to use it (e.g., use memory_search without an id). Thus usage guidance is only implicit.

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

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

With no annotations, the description carries the behavioral burden. It discloses a non-obvious behavior: transitive/inverse edges arrive pre-derived and are marked derived: true with rule provenance. The word 'Read' plus the Returns line also signals a non-mutating query operation.

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

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

Three short sentences with no filler: the action is in the first sentence, the notable derived-edge behavior in the second, and the return contract in the third. Every sentence earns its place and is front-loaded.

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

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

Given a rich input schema, an output schema, and a return-shape overview in the description, the tool is adequately documented. A small gap is that the description does not explicitly mention depth/relation-filter behavior, though those are fully covered 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 the schema already documents all five parameters. The description does not add parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with the specific verb 'Read' and a concrete resource, 'an entity's graph neighborhood,' then enumerates what is included: nodes, typed edges, canonical facts, and paths. This clearly distinguishes it from sibling write/relate/search tools such as memory_graph_relate 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?

The description makes clear this is the read-neighborhood tool: use it when you need an entity's graph neighborhood with nodes, edges, and facts. It does not explicitly exclude alternatives or name a sibling, 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?

With no annotations provided, the description carries the full disclosure burden and does so well: it states auto-creation, alias resolution, confidence bumping on re-assertion, rejected-relation handling with fallbacks, and exactly what the return value or error looks like.

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, front-loaded with the core action, and every sentence adds value. The return format is cleanly separated, making it easy for an agent to parse.

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 lack of annotations, the description is remarkably complete: it covers accepted relations, fallback behavior, alternative tool, return contract, and error shape. An agent has enough context to invoke this tool correctly without opening 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 the baseline applies. The description reinforces behavioral facts like alias resolution and confidence bumps but does not add much parameter-level meaning beyond what the schema already provides.

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

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

The description opens with the specific verb and resource: "Assert a typed relation between two entities," with a concrete example. It clearly distinguishes this from relatives like memory_graph_unrelate and memory_relation_define by showing the assertion action and mentioning vocabulary growth only as a fallback.

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

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

The description gives clear context for using the tool: it asserts relations, auto-creates entities, and handles rejected relations. It explicitly names memory_relation_define as the alternative for expanding vocabulary, though it does not explicitly contrast with memory_graph_unrelate or other sibling tools.

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

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

With no annotations, the description carries the behavioral burden and does so well: it discloses that relate writes an edge and dismisses the pair, accept_junk deletes an artifact, restore_slot undoes a forget, and reject_entity keeps the entity. It stops short of stating irreversibility or side effects of every destructive action, but the per-action behavior is substantive.

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 long because the tool is a multi-action dispatcher with 11 operations, but every bullet earns its place with a compact one-line semantics. The purpose is front-loaded, and the action list is scannable 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?

For a complex, high-parameter tool with no annotations, the description is remarkably complete: it covers every action, notes the return shape ('per-action dict; {error} on bad input'), and relies on the existing output schema for return-value details. No critical calling context is left entirely to inference.

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 89%, so the baseline is 3. The description adds value on top by mapping actions to parameters, such as restore_slot needing store + src, and relate/dismiss_pair using src/dst. It clarifies which parameter combinations matter for which action.

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 clearly identifies a specific responsibility — working the graph review queue for deep-dream proposals requiring a verdict before graph mutation. Each action is explicitly named with a one-line purpose, which disambiguates this from direct graph-editing siblings like memory_graph_relate and memory_graph_unrelate.

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

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

The description gives clear context: this tool handles pending proposals/findings that need a verdict. It does not explicitly name alternatives or state when not to use it, but the action list and 'before they touch the graph' framing make the intended usage obvious.

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

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

With no annotations provided, the description carries the full burden, and it does so excellently. It discloses that the edge is not deleted but marked superseded, remains available for audit, exits memory_graph results, and can be revived by re-asserting the triple. This gives the agent a clear model of the tool's 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?

The description is compact and front-loaded, with the core action in the first two words. The dash and second sentence efficiently convey the audit and revival behavior without 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?

The tool is simple with three required string parameters, an output schema is present, and the description explains the essential behavioral outcomes: removal from active results, audit retention, and revival on re-assertion. It could additionally mention behavior when the triple does not exist, but this is a minor gap.

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

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

The input schema has 100% description coverage for src, relation, and dst. The description adds the concept of a 'triple,' which reinforces how the parameters combine, but it does not add detailed parameter semantics beyond what the schema already provides. The baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Retract a relation.' It clearly states the behavior: the edge is marked superseded, kept for audit, and removed from memory_graph results. It also distinguishes itself from related operations like memory_graph_relate by describing the retraction and revival 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?

The description gives clear context for when to use the tool: when a relation should be removed from active memory_graph results while preserving it for audit. It does not explicitly name alternatives such as memory_forget or memory_supersede, but the use case is unambiguous.

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

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

With no annotations provided, the description carries the full disclosure burden. It does well by stating it is a read operation, disclosing compaction behavior ('compaction thins chains past ~30d'), and describing the result contents and ordering. It does not mention auth, rate limits, or error behavior, but for a history read tool the key behavioral caveat (data loss via compaction) is clearly surfaced.

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 dense but well structured: a one-line summary, two clearly labeled modes with examples, and a concise return-format breakdown. The most important usage distinction is front-loaded, and every sentence contributes either mode semantics, ordering, or data-retention caveats.

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 dual-mode read tool with a moderate parameter set and no annotations, the description is complete: it explains both modes, the as_of semantics are already in the schema, returns are specified, ordering is explicit, and the compaction caveat is disclosed. An agent has enough context to invoke this tool correctly and interpret its results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the 'attribute' toggling behavior and explains the mode-dependent return object, but it does not add substantial meaning beyond what the schema already states for entity, attribute, and as_of. The extra context is mostly behavioral rather than parameter-specific.

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 opens with a specific verb and resource, 'Read an entity's past,' and then clearly differentiates the two modes (SLOT vs CHAIN) with concrete examples. This distinguishes it from sibling tools like memory_get or memory_search, which read current or searched facts rather than historical versions.

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

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

The description gives explicit mode-selection guidance: provide 'attribute' for SLOT mode and omit it for CHAIN mode, with a clear semantic purpose for each ('what did this used to be?' vs 'what led to X?'). It does not name sibling alternatives or state when not to use this tool, 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 no annotations, the description carries the full burden and does so thoroughly. It warns about polarity, explains that lessons describe their originating run rather than the current one, clarifies the re_verify flag for stale facts, and even documents the return shape. This is strong, non-obvious 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?

The description is dense but efficient: purpose, timing, interpretation caveats, and return format are each covered in a few sentences. It is front-loaded with the primary action and every sentence contributes useful guidance.

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

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

For a search tool with three parameters and no annotations, the description is complete enough. It covers when to call it, how to interpret results, the important re_verify caveat, and the returned entry fields. No critical operational gap is evident.

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 some operational meaning for the query parameter ('task at hand', 'described the way it would have been logged') but does not add meaning for top_k or verbose beyond their 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 description clearly states the tool searches learned lessons (procedural memory) by similarity to the task at hand. It is distinct enough from generic sibling searches by naming the specific resource type, though it does not explicitly name alternative sibling tools or exclusion criteria.

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

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

It gives explicit when-to-use guidance: 'Call at the START of a task' and explains what the search surfaces (what worked, what to avoid, user corrections). It does not explicitly state when not to use it or name alternative tools, 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?

With no annotations, the description must carry the behavioral burden, and it does by noting that logged outcomes feed Dream's next-session lessons and that the operation "needs Postgres." It also discloses the return shape. It does not discuss idempotency, permissions, or failure behavior, but for a simple logging write this is reasonable coverage.

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

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

The description is two sentences with no filler; the primary action and scope are front-loaded, followed by downstream behavior and a concise dependency/return note. 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?

The description covers what the tool records, why it matters, what it returns, and its Postgres dependency, while the schema covers all parameter semantics. It does not spell out preconditions such as an active episode, so for a moderate-complexity logging tool it is nearly complete but not exhaustive.

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

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

All six parameters already have descriptive schema entries, so the schema does the heavy lifting; the description adds no additional guidance beyond the return sample containing task and outcome. Baseline 3 applies because the coverage is 100% and the description neither harms nor enriches parameter understanding.

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

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

The opening line, "Record a procedural outcome — what worked, failed, or was corrected," names a specific action and resource and narrows the tool's scope to procedural outcomes rather than general facts. This clearly separates it from siblings like memory_store and memory_reinforce without restating the tool name.

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 supplies clear context for when to call it: after a procedural attempt, so that "Dream synthesises signals into lessons surfaced next session" and "logging stops repeated mistakes." It does not name alternative tools or state when not to use it, so it stops one step short of full routing guidance.

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

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

With no annotations, the description carries full responsibility. It discloses read-only status, the low_confidence failure signal, result caps with per-hop reservation rationale, edge preference behavior, the re_verify flag meaning, and pinned constraint facts. This goes far beyond what the schema conveys.

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 front-loaded with purpose and routing, then layers behavioral detail. It is dense but each sentence adds meaningful information; the only slight demerit is that the cap details could arguably live in the output schema or docs, though their inclusion does help an agent interpret results safely.

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

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

For a complex retrieval tool with no annotations and a nontrivial output shape, the description covers when to use, when not to, failure semantics, result structure, caps, and data-quality caveats. It also points to detailed docs for deeper reading. 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 baseline is 3. The tool description adds context about result caps that indirectly clarify top_k's role, but the schema already explains that top_k bounds only the seed search. The description doesn't need to compensate further.

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 opens with a precise verb+resource pairing: multi-hop retrieval over the knowledge graph for relational questions. It gives concrete example questions and explicitly contrasts itself with memory_search, making the tool's identity unmistakable even among 30+ siblings.

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

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

It states exactly when to use this tool (relational questions requiring link-following, which single-shot memory_search can't chain) and provides an explicit fallback rule: 'low_confidence: true' means no seed entity matched — fall back to memory_search. This is model guidance for tool selection.

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

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

With no annotations, the description carries the behavioral disclosure burden. It reveals key behaviors: newest-first ordering, timestamp-based rather than relevance-based ordering, and AND-combination of filters. It does not describe return-value details, but an output schema exists to 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?

Three tightly written sentences with no filler: behavior first, use cases second, filter semantics last. Every sentence contributes information an agent needs.

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

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

For an optional-parameter list tool, this is complete: it gives use cases, ordering semantics, and filter combination behavior. All parameters are self-documented in the schema, and an output schema exists for return-value details.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying that sources, episodes, and tags AND-combine, and by establishing the ordering semantics that affect how the n parameter is interpreted.

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 clearly states a specific verb and resource: 'List the N most recently stored memories, newest first.' It also distinguishes itself from relevance-based search by explicitly saying 'timestamp order, not relevance,' which separates it from sibling tools like 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?

The description gives concrete use cases: 'what did I just store?' and catching up at the start of a session. It does not explicitly name an alternative tool for relevance search, but 'not relevance' implies the contrast, so the guidance is clear but not fully 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?

No annotations are provided, so the description carries the full burden. It explains the behavior and effect (strengthening, resisting forgetting) and the required sequence. However, it does not disclose error behavior, idempotency, or whether repeated reinforcement has cumulative effects, which leaves some uncertainty.

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 two sentences, front-loaded with the core purpose and no unnecessary fluff. The closing 'Read first, then reinforce' slightly restates an earlier point, but it emphasizes the important ordering rule and keeps the whole description tight.

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

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

For a single-parameter tool with an output schema present, the description provides the essential purpose, the precondition, and the behavioral effect. It could mention edge cases like invalid entry_id or repeated calls, but nothing critical is missing for an agent deciding whether and how to use 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 coverage is 100%: the single parameter entry_id is already described as 'The id of the memory to strengthen.' The description adds the hint that the id likely comes from memory_get, but this is minor and the schema does the heavy lifting, 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?

The description clearly states the specific action ('Strengthen one memory'), the precondition ('after reading it via memory_get'), and the intent ('this mattered' signal that helps resist forgetting). This differentiates it from siblings like memory_get, memory_search, memory_store, and memory_forget.

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 says when to use the tool: after reading the memory via memory_get and finding it genuinely useful. The instruction 'Read first, then reinforce' provides a clear ordering rule. It doesn't spell out exclusions, but the precondition gives strong 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?

With no annotations, the description carries the burden of behavioral disclosure. It does convey that this is a 'deliberate, rare act' within a 'closed' vocabulary, implying persistence and caution. However, it does not state whether the operation is reversible, what system-wide effects it has, or whether it affects existing graph relations. The warning semantics in the schema are useful but separate from the description.

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 two sentences with no filler. The first sentence states the action and its gravity; the second sentence gives the usage rule. It is front-loaded and every phrase 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?

The description gives a strong rationale and selection criterion but omits side-effect details such as reversibility, effect on existing graph queries, or relation to sibling tools like memory_graph_relate. The output schema covers return values, so that absence is acceptable, but broader operational context is still somewhat thin.

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 each parameter, including optional soft type expectations and inverse_of, is already well described in the input schema. The description does not add parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific action: 'Add a relation to the closed graph vocabulary' and clarifies that this means defining a new relation type, not creating an edge. It is distinguishable from sibling tools like memory_graph_relate, though it does not explicitly name them. The 'define one' phrasing reinforces the vocabulary-level purpose.

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

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

The description gives a clear decision rule: 'Prefer the builtins; define one only when a recurring connection genuinely fits none of them.' This tells the agent when to use the tool and when to avoid it. However, the alternative is referred to as 'builtins' rather than naming a specific sibling tool or concrete exclusionary condition.

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

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

No annotations are present, so the description carries the full burden; it richly discloses ordering (cortex before entries), dedup/contested semantics, supersession handling, temporal events, pinned/quoted authority, and filter combination logic. This goes well beyond a generic search behavior and gives an agent real expectations about results.

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

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

Dense and front-loaded with the core purpose and usage timing first, then the output caveats. It is long, but nearly every clause carries a distinct behavior; the 'Returns' line is slightly redundant with the output schema and the dense formatting makes it less skimmable.

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

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

For a search tool with 12 parameters and no annotations, this is remarkably complete: it covers when to call, how to interpret results, filter semantics, and special output markers. An agent has enough to call it correctly and judge the results without needing sibling descriptions.

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

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

Schema coverage is 100%, so baseline is 3; the description adds cross-filter semantics (AND across kinds, OR within a list) and notes relevance floor and supersession behaviors. It doesn't re-explain each parameter but adds value beyond the schema where it matters.

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?

Clearly identifies a retrieval operation over memories with associative recall and canonical facts. However, it doesn't distinguish itself from the sibling memory_recall or memory_get, so an agent must infer the difference.

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

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

Gives explicit timing ('Call at task start or when context may apply') and a decision rule for low-confidence results. It doesn't name alternatives or exclusions, but the context is 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?

With no annotations, the description carries the full burden, and it does so by disclosing idempotency, renamability, and the effect on session recaps. It could add more detail about whether a custom title fully replaces the prior one or how the episode handle is resolved, but the core behavior is clear.

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, all informative, with no fluff. The action and timing are front-loaded, and the idempotency is stated compactly without 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?

Complete for a simple setter: it covers when to call, repeat-call behavior, and why it matters. The optional episode parameter and output schema fill remaining context, so 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?

Schema description coverage is 100%, so the schema already explains title and episode well; the description only adds usage context, not param-level detail. Baseline 3 is appropriate because 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 uses a specific imperative ('Name THIS session's auto-opened episode'), identifies the object being modified, and contrasts with generic defaults. It clearly differentiates from siblings like memory_episode_summary or memory_episode_start by targeting the session title specifically.

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

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

Explicitly says to call once at the start of work and that calling again renames, giving both timing and repeat behavior. It also explains why the call matters ('so session recaps read meaningfully'), which helps an agent decide when the tool is relevant.

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

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

No annotations are provided, so the description carries the safety and side-effect burden. It discloses the one-way scalar-to-set conversion, the protection of number-led scalars, and the 'contested' outcome with resolution path. It also states the exact return shape.

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

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

Four compact sentences with no filler; the purpose is front-loaded and each sentence carries distinct information: operation, conversion caveat, read route, and return shape.

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 does not need to explain return values, and it still gives the return shape. It covers when to use, edge cases, resolution steps, and a read alternative. There is no missing information an agent needs to invoke the tool safely.

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

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

The input schema already describes all three parameters with 100% coverage, so the baseline applies. The description adds meaningful context beyond the schema by explaining the set-slot concept, conversion behavior, and what happens to protected scalar members. It does not add much per-field format detail, but it clarifies how `member` may be interpreted.

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 operation: 'Add/confirm a member of a set-valued slot', and explicitly contrasts with scalar 'NOW value'. This distinguishes the tool from related memory tools such as memory_store and memory_set_remove. The edge-case behavior for number-led scalars adds clarity without ambiguity.

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?

Tells agents when it applies: set-valued slots with 'many concurrent values', and says it is not for 'one NOW value'. It names alternatives explicitly: read via memory_fact_get and settle contested adds via memory_fact_resolve. This is enough to route an agent to the correct sibling.

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

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

No annotations are present, so the description carries the full burden. It usefully discloses that an audit row is kept and that the return includes members_count, but it does not cover behavior when the member is absent, reversibility, or other edge cases.

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: purpose, audit behavior, read-after hint, and return shape all appear in a few short lines with no filler or repetition.

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

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

For a simple three-parameter mutation with full schema coverage and a stated return shape, the description is nearly sufficient. A note on missing-member behavior or an example would make it fully complete, but nothing essential is 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%, and each parameter already has a clear description such as 'The current member to retract' and 'The slot's attribute'. The tool description adds little parameter-specific meaning beyond the schema.

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

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

The description opens with an active verb and resource: 'Retract one current set member', which precisely states what the tool does. It distinguishes itself from siblings like memory_set_add and memory_fact_set, and the parenthetical 'audit row kept' adds an important clarifying detail.

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 intended use is clear: removing an existing member from a set. The instruction 'Read with memory_fact_get' names the natural follow-up tool, but it does not explicitly state when not to use this tool or directly contrast it with 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?

With no annotations, the description must carry the safety/behavior burden. It implies a pure read operation by describing 'vital signs' and statistics, but it never explicitly states that the tool does not modify memory. The listed metrics do add useful behavioral context about what the call reports.

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 well-structured: a front-loaded summary label, the specific metrics, then two concrete use cases. Every sentence earns its place and there is no redundant filler.

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

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

For a no-parameter, output-schema-backed diagnostic stat list, the description covers the main invocation purposes and the categories of returned information. Additional details like time window or persistence would be nice, but the output schema can supply those where needed.

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

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

The tool has zero parameters, so the input schema leaves nothing to explain. The baseline for no parameters is 4, and the description appropriately emphasizes what the response/statistics reveal rather than parameters that do not exist.

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 clearly defines the tool as a memory-bank statistics reader: it lists the exact metrics returned (occupancy vs capacity, hit rates, true-drop count, totals). This distinguishes it from content-focused siblings like memory_search or memory_get and states the diagnostic role rather than simply restating the name.

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

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

It gives explicit use cases: 'gauge how much has been remembered' and 'diagnose why retrieval feels off.' It does not name alternative tools or say when not to use it, but the context is clear enough for an agent to select this tool over the sibling lookup/management tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that near-duplicates are dropped rather than errored, with stored=False and reason="below_surprise_threshold", and it lists the return shape. This is unusually transparent for a storage tool.

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

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

The description is dense but every sentence earns its place: core action, usage policy, decision rules, edge behavior, and canonical alternative. The structure front-lodes the action and then layers policy and behavior logically.

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 that an output schema exists and all parameters are already documented, the description covers the remaining context an agent needs: when to use it, how to classify claims, what happens to near-duplicates, and which sibling to use for canonical facts. 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add much per-parameter detail beyond the schema, though it does clarify the intended semantic of 'text' as a single claim and mentions freshness_class for memory_fact_set. That is useful but not parameter-specific enough to push higher.

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 opens with a specific verb and resource: "Store one durable fact, decision, or observation." It clearly differentiates itself from the sibling memory_fact_set by saying "For canonical NOW use memory_fact_set", so an agent can distinguish this tool without needing to open schemas.

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

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

The description gives explicit usage policy: use proactively for anything worth keeping, one claim per call, and a clear decision framework (PERSIST vs CONTEXT ONLY vs RE-VERIFY vs ASK). It also names the alternative memory_fact_set for volatile values and for canonical NOW, which is strong when-to-use and when-not-to-use 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?

With no annotations provided, the description carries the full disclosure burden and does so thoroughly. It reveals that the old entry is kept, not deleted; that derived facts are flagged and never rewritten; that rows carry has_current_value; and that results are capped with truncation indicators.

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 front-loaded with the core action, then provides dense but purposeful detail about return semantics. Every sentence adds useful information about behavior, flagging, or truncation; there is no filler.

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

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

Given the tool's complexity, the description is remarkably complete: it covers matching behavior via the schema, old-entry retention, derived-flag semantics, has_current_value meaning, and truncation reporting. An agent has enough context to invoke this correctly and interpret its result.

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 parameters old_text and new_text are already fully documented in the schema. The tool description itself adds no parameter-specific meaning, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Mark a stored memory obsolete and record its replacement.' It clearly distinguishes supersede from siblings like memory_forget or memory_store by explaining the old entry is kept but flagged, and retrieval ranks the correction higher.

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 makes the usage context clear: use this when an existing memory is obsolete and a replacement should be recorded, with the old entry preserved for context. It does not explicitly name alternatives or when-not-to-use conditions, 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?

No annotations exist, so the description carries the full behavioral burden. It discloses identity scoping ('scoped to your credential/writer identity'), cost and latency ('free, instant'), and the operational consequence of hidden tools ('clients reject hidden-tool calls'). It also specifies exactly which capability groups each tier unlocks.

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

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

Two dense sentences front-load the purpose and then add only high-value details: tier contents, status behavior, and expansion warning. There is no filler or redundant restatement of the schema.

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

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

For a one-action tool with an output schema, this description is complete. It defines the tier model, the three action semantics, identity scoping, and the operational warning about hidden-tool calls. An agent can decide to expand, collapse, or check status without needing further documentation.

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

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

The schema has one enum parameter with 0% description coverage, so the description compensates by explaining 'expand' (move up the ladder) and 'status' ('reports the ladder'). 'Collapse' is left to inference from 'one tier at a time' and the minimal→core→full ordering, but the word and direction make it sufficiently clear.

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 the exact verb and resource: 'Adjust YOUR visible toolset, one tier at a time.' It enumerates tier contents and actions, making clear this is a toolset-management tool, not a memory-content operation like any sibling memory_* or document_* tool. The purpose is unambiguous and distinct.

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 an explicit precondition: 'Expand first: clients reject hidden-tool calls,' which tells the agent when to use this tool. It also explains that 'status reports the ladder' as a diagnostic use. It doesn't explicitly state when to collapse or name alternative tools, but no sibling tool is a substitute, so the context is clear.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does well by exposing that results are similarity-based, include age-decayed confidence, a stale flag, and source provenance, and that stale entries should be re-verified. It stops short of describing any potential side effects, but 'Search' makes the read-only nature reasonably clear.

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 well-organized: it states the core function, gives a practical use case, describes key result metadata, and ends with the return shape. Every sentence contributes value without unnecessary detail.

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

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

For a search tool with one required parameter and helpful defaults, the description is nearly complete. It covers the trigger condition, result shape, confidence decay, staleness handling, and citation fields. It could be even more complete by explicitly contrasting with sibling tools like memory_search, but this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already fully documents query, top_k, and verbose. The description adds useful context about result fields like source_url and source_quote, but it does not significantly deepen understanding of the parameters beyond what the schema provides.

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

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

The description states a specific action ('Search') and a clear resource ('current WORLD facts (sourced external knowledge)'). It distinguishes itself from generic memory search by emphasizing external world facts, though it does not explicitly name a sibling alternative.

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

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

The description gives a clear usage condition: use when a task depends on an external fact that training data may have stale. It provides context for when the tool is appropriate, but it does not state when not to use it or name an 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?

With no annotations provided, the description carries the full behavioral burden. It discloses the critical side-effect that 'a newer source supersedes an older value at the same slot' and reveals the action vocabulary returned (inserted, confirmed, superseded, rejected). This is meaningful write-semantics disclosure beyond the schema, though it does not cover every edge case such as rejection triggers.

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, front-loaded with the core purpose, and each sentence earns its place: what the tool is for, when to use it, what behavior to expect, and what it returns. There is no filler or redundant restatement of schema details.

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 tool with no annotations, the description provides the essential operating model: external world facts, separation from user facts, citation requirement, supersession behavior, and return shape. The output schema covers return details and the input schema covers parameter descriptions, so the remaining gap is mainly the lack of explicit alternative tool routing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic glue: 'with the citation' reinforces the role of source_url/source_quote, and the supersede rule gives meaning to retrieved_at and freshness_class. It doesn't restate individual field descriptions, which is appropriate given the schema already documents them.

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

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

The description states a specific verb and resource: 'Assert a canonical WORLD fact' sourced from EXTERNAL knowledge. It also clearly scopes the tool to external/world facts as opposed to user/project facts, which differentiates it from sibling memory tools. The listing of example knowledge types (versions, prices, role-holders, research findings) makes the purpose concrete.

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

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

The description gives clear usage context: route verified web/docs findings here, with a citation, for externally-sourced knowledge. It implicitly excludes user/project facts by saying this is 'kept separate' from them, but it does not explicitly name sibling alternatives or state a when-not-to-use rule.

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