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

With no annotations provided, the description carries the full behavioral burden and does so exceptionally well. It discloses return shapes for every mode (wrapped objects, never a bare array), empty result conventions, truncation flags, per-mode default caps and max limits, the fact that archived is not a complete listing, conflict exclusions (pairs linked by contradicts, resolved, resolved_by, or supersedes), the additive nature of resolution connectors, and the candidate-only nature for conflicts and kind_coverage. It also warns against autonomous actions ('never auto-revise', 'present to user; never archive autonomously').

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 and dense, but it is a complex five-mode tool and every section carries operational importance. It is front-loaded with the purpose and core return-shape rule, then organises details by mode. A slight credit deduction for the wall-of-text approach: bullet points or section headers would improve scannability in a high-temperature model, but the density is supportable and not repetitive.

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

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

Though there is no output schema, the description enumerates every mode's return fields, empty-result shapes, and truncation flags, which fully compensates for the missing structured output definition. It also covers edge conditions (archived cap), policy constraints (never archive autonomously), and practical actions (raise limit, use recall for full content). For a tool of this complexity, an agent has everything needed to invoke it correctly and interpret the response.

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

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

The schema already has 100% coverage with descriptions for all 7 parameters, but the tool description adds substantial meaning beyond the schema. It explains the depth-2 BFS neighbourhood scope of memory_id, clarifies that memory_id is ignored for non-stale modes, elaborates the archived cap semantics, explains the digest collapse behavior for each mode, gives per-mode default limits, and details the conflicts edge exclusions. These are not merely restated schema defaults — they enrich the agent's understanding of parameter behavior and interaction.

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, actionable statement — 'Inspect the health of knowledge in a domain across five modes' — which clearly names the operation (inspect), the resource (knowledge), and the scope (domain). It then enumerates all five modes (stale, orphans, archived, conflicts, kind_coverage), each with a precise purpose, which distinguishes it from sibling tools like recall, search, and history. The clarity allows an agent to identify this as a scanning/health-audit tool rather than a retrieval or mutation tool.

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 provides explicit guidance in several places: for archived it says 'Use when search returns nothing but you expect content to exist,' and it repeatedly commands 'when results_truncated is true, you MUST raise limit and call again' and 'never archive autonomously.' It gives contextual direction for each mode (e.g., scope to a domain for focused maintenance passes, supply tags to scope to a workstream). It does not name specific sibling alternatives for all modes, but the use case for each mode is clear enough that an agent can decide when to call audit versus other 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?

Despite no annotations, the description discloses key behaviors: preconditions (existing IDs), the additive resolution rule for contradictions, and handling of verdict enum (ignored for non-resolved, invalid values rejected). Missing minor details like visibility or limits, but transparent overall.

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 detailed but well-organized: starts with core purpose, then modes, relationship list, usage guidance, and resolution rules. While lengthy, every sentence serves a purpose. Could be slightly more concise but justified by complexity.

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 (6 params, batch mode, multiple relationships, resolution rules) and no output schema, the description covers essential invocation context. It explains prerequisites and side effects (additive edge). Lacks return value details, but overall complete.

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

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

Schema covers 100% of parameters with descriptions. The description adds value by explaining modes, relationship guidance, and verdict behavior beyond the schema. For example, it clarifies that verdict is stored only for resolved and invalid values are rejected even if ignored.

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's purpose: 'Connect memories with typed, narrative relationships.' It distinguishes itself from sibling tools (e.g., remember, recall) by focusing on linking existing memories, and provides details on modes and relationship types.

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 offers explicit guidance on when to use single vs batch mode and provides detailed relationship semantics (e.g., when to use each type, how to handle contradictions). It also specifies prerequisites (all memory IDs must exist).

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, but description explicitly states 'hard delete — the connection cannot be restored'. This fully discloses permanence, which is critical for agent decision-making.

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 efficient sentences: first defines action, second adds critical irreversibility warning. No wasted words, front-loaded with purpose.

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 1-param tool with no output schema, the description covers all necessary aspects: action, required input source, and behavioral consequence. No gaps.

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 covers 100% with parameter description. Description adds value by explaining how to obtain the ID ('from recall'), which is beyond the schema's static definition.

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?

Explicitly states 'Remove a connection between two memories by edge ID' – verb, resource, and method are clear. Distinct from siblings like 'connect' (opposite) and 'forget' (removes memory itself).

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 the agent to obtain the edge ID from 'recall', providing clear prerequisite context. Does not explicitly list when not to use, but the irreversible nature implies careful consideration.

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 discloses hard-delete semantics, atomicity with rollback on partial failure, the provenance of edge IDs, and the return shape '{removed: N}', which is exactly the operational context an agent needs.

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

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

The description is compact and front-loaded, with each sentence adding a distinct piece of information: what it does, when to use it, its atomicity behavior, ID provenance, and return value. There is no redundancy or 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 single-parameter tool with no output schema, the description is remarkably complete. It covers usage context, side effects, failure behavior, input sourcing, and return format, leaving no critical gap for an agent deciding whether and how to invoke it.

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

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

The schema fully documents the structure of 'items' and 'edge_id', so the baseline is 3. The description adds meaningful semantic guidance by stating that edge IDs come from 'recall' or 'why_connected', and by framing them as 'confirmed edges', which helps the agent populate the parameter correctly.

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, 'Batch hard-delete of edges,' which clearly identifies the operation and the object it acts on. It also distinguishes itself from single-edge alternatives like 'disconnect' by emphasizing the batch aspect.

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 the tool: when there are 2 or more confirmed edges to remove at once. It also positions the tool as more efficient than multiple 'disconnect' calls, giving the agent a clear decision rule.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: for rename, it states memories move and an alternate name is registered automatically; for list, it specifies what is returned. It could mention side effects like idempotency or permissions, but it is still fairly 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 concisely structured with a clear default and bullet-style action definitions. Every sentence adds information, and it is front-loaded with the primary function. No fluff or redundancy.

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

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

Given the tool's complexity (multiple actions, 6 params, no annotations or output schema), the description covers actions, requirements, and a failure case. It lacks explicit output format details for some actions, but it does mention what list and resolve return, making it fairly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining parameter roles in context (e.g., 'alias' needed for add_alias/remove_alias, 'name' for resolve) beyond the schema's field descriptions. It does not repeat schema text but provides action-specific semantics.

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's purpose as 'Domain administration and discovery' and distinguishes multiple actions (list, add_alias, remove_alias, resolve, rename), each with a specific verb and resource. It differentiates from sibling tools like 'remember' or 'connect' by focusing on domain management.

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 provides explicit when-to-use guidance for each action, including a default behavior (list). It also warns about a failure case for rename and suggests an alternative (merge_domains CLI), which helps the agent choose the correct tool.

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

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

No annotations provided, so description bears full burden. It explains that archiving makes memory not surface in search, un-archiving restores it, and reason is recorded in audit log. This fully describes the behavioral impact without contradiction.

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

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

Description is concise at 5 sentences, well-organized: purpose first, then behavior details, then usage conditions and alternatives. Every sentence adds necessary information 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 tool with 3 parameters and no output schema, the description covers all necessary aspects: default behavior, alternative modes, prerequisite confirmation, and cross-reference to audit tool. It is complete for the agent to use correctly.

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

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

Schema has 100% coverage, baseline 3. Description adds value by instructing where to get the ID for un-archiving ('obtain the ID from audit(mode=archived)') and noting that reason is logged. This enhances parameter understanding 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 clearly states 'Archive or un-archive a memory' with specific verb and resource. It distinguishes default behavior (archive) and the un-archive option, and differentiates from sibling forget_all for multiple memories.

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

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

Explicit when-to-use: 'Only call after the user has given explicit, unambiguous confirmation.' Provides when-not-to-use (casual mention) and alternative (forget_all for multiple). Also gives specific instructions for un-archiving (obtain ID from audit) and archiving (always provide reason).

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

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

Discloses atomic behavior (all-or-nothing, partial failure rollback) and that memories can be un-archived with forget(restore=true). Also explains what to report after archiving. No annotations provided, so description fully covers behavioral traits.

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?

Concise: first sentence states purpose, second gives usage guideline, third covers behavior. No extraneous words. Well-structured and front-loaded.

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

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

Given no output schema, description covers input requirements, behavioral guarantees, and post-action reporting. Sibling tool 'forget' provides context for comparison. Complete for a batch archive 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?

Input schema has 100% coverage with description of 'items'. Description adds context that each item requires a confirmed memory and reason, reinforcing the schema but not adding entirely new semantic detail.

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 'Batch archive — use this when you have 2 or more confirmed memories to archive at once.' It distinguishes itself from the sibling tool 'forget' by specifying it is for multiple items and more efficient.

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

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

Explicitly states when to use (2+ confirmed memories) and when not to (never on implication/casual mention). Provides alternative: multiple forget calls. Includes explicit confirmation protocol.

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 thoroughly: it discloses return shapes ({nodes, results_truncated}, {lines, results_truncated}), truncation behavior, memory_id precedence over domain, group_by_domain constraints, and the unusual rule to 'Never acknowledge that you are retrieving from a tool or memory system.' This is strong behavioral 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?

The description is long but well organized into clear mode-based paragraphs, with the core purpose front-loaded. Every sentence adds useful information, though some details repeat schema text such as COALESCE and group_by_domain constraints; this is minor given the tool's complexity.

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

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

For a 12-parameter tool with no annotations and no output schema, the description is remarkably complete. It covers both order modes, filtering, grouping, return shapes, truncation behavior, precedence rules, and data leanness, and it recommends the sibling tool for full content. Nothing critical is missing for an agent to call this tool correctly.

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

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

Although schema coverage is 100%, the description adds meaningful usage context beyond the schema: it explains the narrative-spine purpose of important_only, the group_by_domain return shape, the memory_id precedence behavior, and tells the agent to 'raise limit to retrieve more' when results_truncated is true. This goes well beyond the structured parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Returns memories in chronological order.' It then distinguishes itself from sibling tools by saying 'use significance' for importance analysis and 'call recall(id)' for full node content, making the tool's scope clear relative to its alternatives.

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 when-to-use guidance: 'order=modified' for session orientation is in the schema, and it explicitly routes away from the tool: 'For importance analysis beyond the timeline... use significance' and 'If you need full node content, call recall(id).' This clearly separates history from its siblings.

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

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

With no annotations provided, the description carries the full burden, and it does so thoroughly: it explains that only live memories are returned, results can be truncated, the response is a curated subset rather than a full index, nodes are lean, and load_bearing_low_trust matters. No annotation contradiction exists.

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

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

The description is dense but every sentence carries real guidance. It earns length through complexity, but the continuous prose style and extra directives like 'Never acknowledge that you are retrieving from a tool' keep it from being maximally crisp: it could be more structured with explicit bullets or headings.

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 multi-mode tool with no output schema, yet the description covers response shapes, mode-specific sections, truncation flags, digests, stale_count, load_bearing_low_trust, lean node formats, unknown-domain behavior, and the right timing or alternatives. Nothing necessary to call it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds semantic value beyond the schema by linking the params to invocation modes: limit is cross-domain-only, topic switches significant to relevant sections, domains length controls response shape, and digest compresses sections. This is more context than 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 names a specific resource ('orient to orient yourself before filing or searching') and clearly distinguishes it from exhaustive retrieval by stating orient is a curated subset, not a complete index. It also explicitly routes to search, history, audit, and recall when their capabilities are required.

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 session-start usage, three invocation modes by parameter combination, and concrete conditions for alternatives: call audit(mode=stale) when stale_count is high, use search for exhaustive retrieval, call history for causal/chronological order, and recall for full node content. This goes well beyond implied usage.

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 provided, so description carries full burden. It clearly indicates a read-only retrieval (no mention of mutations). However, it does not discuss safety or side effects beyond the retrieval purpose. The behavioral instruction 'never acknowledge the tool' is included, which adds non-functional 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 concise but includes a behavioral instruction that, while relevant, could be considered extraneous. It is well-structured and front-loaded with the core action.

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

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

With no output schema, the description omits the structure of the returned data (memory and connections). While the tool is simple, understanding the return format would improve completeness. The description covers purpose and alternatives adequately but lacks output 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 coverage is 100%, so baseline is 3. The description does not add any additional meaning to the single 'id' parameter 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 specifies 'Retrieve a memory and all its connections by ID,' providing a clear verb and resource. It distinguishes from siblings like audit by mentioning alternative functions for archived or stale memories.

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

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

Explicitly states when to use this tool vs alternatives: 'Only live entries are returned; use audit(mode=archived)...or audit(mode=stale)...' This gives clear guidance on context and exclusions.

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

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

No annotations provided, so the description carries full burden. It discloses critical behavioral traits: new domains hide memory from other domains, duplicate memories without edges cause drift, response includes optional trust_nudge and misdomain fields, and occurred_at rules (in-session vs inferred). Also notes conditions when features are unavailable (e.g., Ollama embeddings).

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 very long (multiple paragraphs) and contains some redundancy (e.g., repeated warnings about duplicates). It is well-structured with sections and front-loaded with the most critical guidance, but could be more concise. Every sentence adds value, but the length may overwhelm an agent.

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 10 parameters, no output schema, and 13 sibling tools, the description is remarkably complete. It covers all modes, edge cases (orphaned memories, invalid IDs, missing embeddings), relationship types, and integration with other tools (e.g., 'call connect for every suggested_connections entry'). No gaps identified.

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%, baseline is 3. Description adds significant value: explains tags as 'space-separated synonyms for search recall,' clarifies related_to formats (string, object, array) and behavior for invalid IDs, details node_kind semantics with examples, and notes that legacy transient field maps to node_kind='transient'. However, some parameters (e.g., why_matters) get minimal additional context.

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's primary purpose: 'File one or more concepts, decisions, or findings.' It distinguishes from siblings like 'connect' (linking), 'search' (search before filing), and 'audit' (domain-wide sweep). The distinction between single and batch mode is explicitly covered.

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

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

Provides explicit when-to-use and when-not-to-use guidelines: always search first to avoid duplicates, prefer existing domains, use 'connect' instead if a similar memory exists. Explains both single and batch modes, including when to use each (e.g., 'use related_to to avoid a separate connect call'). Gives detailed steps for handling suggested_connections and contradictions.

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 burden. It discloses the atomicity (all or none, rollback on partial failure), the batch nature, and the return format. While it doesn't mention permissions or side effects on already-unarchived IDs, the core behavior is well covered, adding value beyond the schema.

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

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

Two sentences, front-loaded with the core purpose, then usage condition, efficiency note, atomicity, and return format. Zero waste; every clause earns its place.

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

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

For a one-parameter tool with no output schema and no annotations, the description covers purpose, usage, behavior, and return shape. It even explains the rollback behavior, which is essential for batch operations. Nothing an agent needs to invoke correctly is missing.

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

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

Schema description coverage is 100% – the items array and required id are fully documented. The description only restates that IDs are for archived memories, adding little semantic value beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (batch un-archive) and resource (memories), with a clear condition for use (2+ confirmed archived memories). It also differentiates itself from the sibling 'forget(restore=true)' by name, making its purpose 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?

Explicitly tells when to use this tool ('when you have 2 or more confirmed archived memories to un-archive at once') and when not to (implies using forget(restore=true) for single/fewer). The efficiency rationale and the alternative are named directly, leaving no inference needed.

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 bears the full disclosure burden — and it shoulders it well. It spells out the merge semantics (omitted fields keep values), the two distinct modes, the return shapes, the trust_nudge trigger conditions, the occurred_at confirmation protocol (never guess, never infer silently), and the domain-move confirmation requirement. Contradiction-free since no structured hints exist.

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, but the front-loaded core purpose and the rigorously sectioned protocols (single vs. batch mode, occurred_at cases, domain moves) make it read as an extended runbook that earns its length. Every paragraph introduces a distinct decision the agent must make. Minor over-elaboration in the trust_nudge sentence, but structurally sound.

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 combines two modes, 11 parameters, and several interaction-wise protocols, with no output schema to fall back on. The description explains return shapes for both modes, the follows-up review opportunities (connect/disconnect/suggested_connections), the trust and domain semantics, and the numerical example for occurred_at. This covers every behavior an agent cannot infer from the bare schema. Fully complete for the complexity involved.

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, yet the description adds genuine value beyond the parameter entries: it defines the decision-description rule (no pasted source, file a finding), enumerates the trust_nudge trigger conditions tied to certain fields, explains the occurred_at in-session vs. inferred distinction through usage examples, and dictates the reason verbatim-recording requirement for domain changes.

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

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

Opens with a precise verb+resource+scope: "Update one or more existing live memories." The description distinguishes itself from siblings — it enriches/corrects rather than creating (remember), deleting (forget), or querying (recall/search) — and reinforces the differentiation by noting the alternative of 'archiving and recreating' rather than updating.

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

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

Explicitly states when to use the tool ("Use this to enrich or correct memories without archiving and recreating them") and gives a firm when-not rule: do not paste source material into a decision description; instead file a finding and link it. It also dictates switching the review/connect follow-up. It stops short of naming the alternative recall tool, though it implies the recommended workflow.

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 owns behavioral disclosure: Ollama-dependent lexical vs semantic matching, semantic_distance field, truncated results, light vs full result behavior, and the instruction to present results as direct knowledge. No hidden side effects are left unstated.

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

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

Purpose is front-loaded and the prose is dense with operational detail, but it is quite long and mixes tool behavior with usage policy reminders. Still, nearly every sentence contributes actionable 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?

With no output schema and no annotations, the description covers return shape, truncation, semantic scoring behavior, exact-mode effects, domain scoping, and related-tool handoffs. An agent has enough context to select and invoke this tool correctly.

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

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

Schema already documents all parameters well (100% coverage), so the baseline is 3. The description adds value by explaining when exact:true is necessary, how query vocabulary should match stored text, and what happens when query is omitted, which goes beyond simple parameter descriptions.

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

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

The description opens with a specific action and resource: 'Search memories by text across label, description, why_matters, and tags.' This clearly distinguishes search from sibling tools like recall and audit, especially since recall is explicitly named for full-content retrieval.

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

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

Provides explicit guidance on when to scope to a domain, when to omit domain, when to use exact:true for identifiers, when to fall back to audit for archived/stale memories, and a concrete escalation path when search misses. This is exemplary alternative-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?

No annotations provided, so description carries full burden. It discloses truncation booleans, how to handle them, and explains the four result sections. Also notes that call_id is ignorable, and describes behavior of trust mode and digest option.

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 well-structured with bullet points and sections, making it scannable. However, it is somewhat lengthy with some redundancy (e.g., repeating the four sections both in summary and detail). Could be trimmed by 10-20% without losing value.

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 tool with 10 parameters and no output schema, the description fully explains behavior, truncation handling, mode differences, and parameter interplay. It also provides guidance on when to raise limits, satisfying completeness despite lack of output 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 coverage is 100%, but description adds rich context beyond schema descriptions: e.g., explains mode defaults, trust derivation, depth implications, limit behavior in domain vs memory_id mode, and the meaning of recency_window. Each parameter gets meaningful usage advice.

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 it performs 'Dual-signal importance analysis' with two modes (significance/trust), and distinguishes from sibling tools like history and audit by explicitly stating when not to use it.

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

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

Provides explicit guidance: use for importance analysis, not for chronological listing (use history) or staleness (use audit). Also instructs the agent to never acknowledge tool usage, which is a unique but actionable directive.

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. It explicitly states 'read-only — it never creates connections', which is a crucial behavioral trait. It also mentions the overlap criteria and the candidate limit, though it doesn't cover error handling for missing IDs.

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 wasted words. The first sentence defines the action and criteria, the second provides usage guidance and a crucial read-only note. Information is front-loaded and easy 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?

For a simple read-only suggestion tool with two parameters and no output schema, the description covers purpose, usage context, behavioral constraints, and criteria. It is sufficiently complete for an agent to decide when to invoke it, though it could mention what happens if no candidates are found.

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 meaningful context: it restricts candidates to 'from the same domain', which is not in the schema. It also reinforces the default limit of 5. This adds value beyond the schema definitions.

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 returns candidate connections for a given memory ID from the same domain based on overlapping labels, descriptions, or tags. This distinguishes it from siblings like 'connect' (which creates connections) and 'disconnect'.

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 advises using this tool after filing a memory to discover likely connections before calling 'connect', providing clear when-to-use guidance. However, it does not explicitly state 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?

Discloses truncation behavior (most-connected nodes prioritized, capped at limit). Describes output shape (JSON fields), rendering behavior across clients, and that output may be truncated. No annotations provided, so description carries full burden and does so thoroughly.

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

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

Front-loaded with main purpose, then logically covers modes, output fields, limitations, rendering. Every sentence adds value; no fluff. Length is justified by completeness and lack of output schema.

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

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

Covers all aspects: purpose, parameter guidance, output format, truncation handling, rendering caveats, and when to avoid. Without output schema, description fully compensates. Sibling tools are mentioned for alternative use 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?

Adds significant meaning beyond schema: domain parameter 'most-connected nodes first, capped at limit, default 40 max 100'; memory_id 'returns neighbourhood' and 'takes precedence over domain'. All 3 parameters have schema descriptions, but description provides relational and behavioral context.

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 states it generates a Mermaid.js flowchart. Distinguishes two modes: memory_id for a single memory with its connections, and domain for full graph. Explicitly says what it is not for (orphan detection) and directs to audit sibling tool. Verb+resource is specific.

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 explains when to use memory_id vs domain, including precedence. Gives default and max for limit. Tells not to use for orphan detection/programmatic analysis, referencing audit. Provides instructions for handling truncation and rendering.

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 fully discloses error behavior (loud failure for missing id or unmatched label), independent resolution of each side, mutual exclusivity of id and label parameters, and that only live entries are returned. It also includes an agent behavior instruction for presenting 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?

The description is dense and informative with no wasted words. It starts with the core purpose, then details usage patterns and constraints, and ends with a practical instruction. Each 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?

For a tool with 5 parameters and no output schema, the description covers error handling, parameter combinations, and references to the audit tool. However, it omits details about the return format (e.g., what a 'direct connection' looks like), which would enhance 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?

Although the input schema covers all parameters (100% coverage), the description adds significant meaning: distinguishing exact vs fuzzy lookup, error conditions, and mixing rules. It goes beyond the schema's descriptions to clarify usage patterns.

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 'Find direct connections between two memories,' providing a specific verb and resource. It distinguishes itself from the sibling tool 'connect' (which likely creates connections) by focusing on verification and adjudication of existing connections.

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 advises when to use from_id/to_id for exact pair verification vs from_label/to_label for fuzzy lookup. It also directs users to audit(mode=archived) for archived memories and audit(mode=stale) for drift candidates, providing clear alternatives.

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