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

The description adds substantial behavior beyond the readOnly/idempotent annotations: it returns an empty bundle rather than erroring, answer=true may send data to a provider and 'may leave the machine,' and it is local/free by default. It also explains include_history semantics and priority ordering, none of which contradict the annotations.

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

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

The description is front-loaded with purpose and usage, then systematically covers parameters. It is longer than typical one-liners, but every sentence adds necessary nuance for an 8-parameter tool; slight length keeps it from a perfect conciseness score.

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

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

With no output schema, the description fully explains the return shape: mandatory policy, curated memory, evidence sections with citations, and the optional generated answer. It also covers defaults, edge cases like empty results, and external side effects, making it complete for an agent to select and invoke 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?

Even though schema coverage is 100%, the description enriches every parameter: answer's default and provider-call implication, mode being ignored when answer is false, limit capping supporting evidence, include_history adding superseded evidence, agent attribution, token_budget bounding size, and project_path omission rules. This is far 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 a specific verb and resource: 'recall one bounded bundle of everything local memory knows about a task.' It also explicitly distinguishes itself from search_memory and search_evidence, making it clear this is the broad default recall tool rather than a store-specific 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 states this is 'the default recall tool and the right first call' when the correct store is unknown, and notes that search_memory and search_evidence each cover only one store. It also provides clear guidance on when to omit project_path, including the pinned-project exception.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds materially: local disk read, machine-wide scope, no project_path, the pinned vs generated zone split, content_hash/revision id, and the status summary behavior. No contradiction with 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?

Although longer than average, every sentence earns its place: it front-loads READ-ONLY, then explains what/why/when, alternative tools, parameter semantics, and return behavior in a logical flow. There is no filler 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?

The description covers purpose, usage timing, return values (with and without a section), alternatives, and limitations (not a search tool). Given the simplicity of the input schema and lack of output schema, the description fully compensates and leaves no relevant question unanswered.

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

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

Schema coverage is 100% for the single parameter, but the description goes beyond by explaining each enum value (about, preferences, working-principles, active-projects, canonical-memory) and the behavior when omitted. This adds clarity beyond the bare 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 uses a specific verb ('read') and a clearly defined resource ('machine-wide canonical memory'), and explicitly distinguishes itself from sibling tools by stating 'Not a search tool' and pointing to search_memory/ask_memory. It also contrasts with mutation tools (pin_memory vs edit_memory), so the agent knows exactly what this 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?

Provides explicit when-to-use guidance: 'Call it before asking the user something they may already have told another agent.' It also gives clear exclusions and alternatives: 'use search_memory or ask_memory to look something up' and 'To change what it returns, use pin_memory rather than edit_memory.'

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

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

While annotations already declare readOnlyHint=true, the description goes well beyond by explaining that this is a local disk read over already-harvested evidence, that docmancer's own generated integration copies are excluded to avoid manufacturing agreement, and that recurrence is only a signal, not proof of correctness. It also discloses the empty-return behavior, adding substantial epistemic nuance beyond 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?

Every sentence earns its place: purpose, operational mode, exclusion rule, epistemic caveat, alternative guidance, parameter clarification, and return behavior. It is front-loaded with the most important purpose and remains tight despite its length.

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 prepares an agent to select and invoke the tool: it defines the return shape, the empty case, the project_path semantics, and the intended use context. An output schema exists, but the description still explains the function's behavior comprehensively enough even without relying on 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 provides 100% coverage of the only parameter, project_path, with a thorough description that the tool description simply echoes. The description adds no new parameter-level insight beyond the schema, so a 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 opens with a specific verb and resource: 'list the memories that recur across two or more independent agent harnesses.' This clearly states what the tool does and distinguishes it from common memory cousins like search_memory or canonical_memory. It also adds a title-equivalent phrase and notes the local disk nature.

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 versus an alternative: 'Use search_evidence to look something specific up instead.' It also clarifies that this tool takes no query and returns the whole recurring set, and gives project_path omission guidance. This makes selection straightforward.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: 'Local disk read with no side effects,' 'Read-only across all three,' and explains that installing hooks and refreshing context are human-only. It also discloses return shape and diagnostic signal: 'A stale or absent revision on one row is the signal to look for.' No contradiction with 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 is dense but every sentence earns its place: purpose, safety, usage guidance, sibling differentiation, parameter explanation, return value, and diagnostic hint. It is front-loaded with 'READ-ONLY' and the core purpose, followed by succinct supporting 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?

Given the tool's moderate complexity, the description covers all necessary aspects: purpose, safety, parameter semantics, return format, sibling differentiation, and practical diagnostic guidance. An output schema exists, and the description still summarizes the return value, so the agent has a complete picture without needing to inspect structured fields.

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

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

Schema coverage is 100% and the description repeats the schema's parameter description nearly verbatim ('project_path project root whose memory tree the operation applies to. Omit it to use the machine-wide tree, and always omit it when this server was started pinned to a project.'). It adds no new semantic information 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 states a specific action and resource: 'show, per agent, whether context is actually reaching it, listing each supported agent's integration mode, hook installation status, and the revision and hash of the last context bundle.' It also distinguishes itself from sibling tools: context_status answers what the current context revision contains and context_projection renders the actual text one agent would receive.

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 when to use: 'use it to diagnose why one agent seems to be missing context that another has.' It also provides alternatives by naming context_status and context_projection and clarifying they are different questions, plus notes that installing hooks and refreshing context are deliberately human-only operations.

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

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

The description fully discloses side effects: 'READ-ONLY', 'Local disk read that renders without writing, refreshing, or delivering anything', and 'safe to preview repeatedly'. This goes beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by explaining what is NOT done and the practical implication of safety. No 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 well-structured and front-loaded with the safety and purpose, then usage context, then parameter walkthrough. It is longer than strictly minimal but every sentence contributes either to distinguishing the tool or to parameter semantics. Slightly verbose, but appropriate for the tool's complexity and sibling set.

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 the tool's purpose, safety profile, relationship to two sibling tools, human-only alternatives, all parameters, the return object ('rendered projection text and the revision it was built from'), and project scope handling. Given the tool's moderate complexity and minimal schema/annotations, this is fully complete.

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

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

Even though schema description coverage is 100%, the description adds meaningful behavioral detail for token_budget ('raising it returns more content and lowering it truncates by priority'), project_path ('always omit it when this server was started pinned to a project'), and clarifies agent as the required target. These nuances are not present in the 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 uses a precise verb+resource ('render the actual bounded context text one named agent would receive') and explicitly distinguishes itself from sibling tools by stating what context_status and context_delivery do differently. It clearly identifies this as the 'show-me-the-content' 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?

It provides explicit when-to-use guidance ('check what an agent will actually see before installing or debugging an integration') and when-not-to-use guidance by noting that refresh/rollback/adopt/retire are human-only CLI/local-web operations. It also names the alternative tools for revision freshness and delivery status, making the decision matrix 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description aligns with them ('READ-ONLY', 'Local disk read with no side effects'). It adds extra context: the tool returns an object with specific fields, and explicitly says no MCP tool can change what it reports. This goes beyond the bare annotations and gives a clear behavioral model.

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 densely packed and every clause adds information, but it runs long as one paragraph. It front-loads READ-ONLY and the core function, then proceeds logically through usage, alternatives, constraints, and return value. It could be slightly trimmed, but there is no filler 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?

For a read-only status tool with no output schema, the description covers purpose, usage context, sibling relationships, human-only mutation boundary, parameter semantics, and the return shape (revision, scope, freshness, exclusions, cluster metadata). This is fully adequate for an agent to select and invoke the 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?

The schema has 100% description coverage for the single parameter project_path, and the description restates the exact same guidance (omit to use machine-wide, omit when pinned). Since the schema already fully explains the parameter, the description adds no new semantic value here, keeping the score at the baseline for full coverage.

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

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

The description uses a specific verb ('inspect') and names the resource ('the consolidated Context itself'), then lists exactly what it reports: revision id, freshness, excluded sources, and cluster metadata. It also distinguishes itself from sibling tools by naming context_delivery and context_projection, making its purpose unmistakable.

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 it: 'use it to decide whether the context an agent is working from is stale or is missing something on purpose.' It also gives alternatives by comparing with context_delivery and context_projection, and states that refresh/rollback/adopt/retire are human-only, so this tool is not for mutations.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: the log is append-only, 'nothing here can be rewritten and the record is trustworthy,' and results are newest-first. This goes beyond annotations without contradicting them.

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

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

The description is a single dense paragraph but front-loaded with the core purpose. Each sentence adds information (filters, return format, ordering). It could be split for readability, but every sentence earns its place with no fluff.

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 the tool's purpose, usage context, parameter semantics, and return format ('a list of entries with the operation, timestamp, affected file, revision ids, and a readable diff'). It also disambiguates from sibling tools. It is complete for a read-only history tool with an output schema present.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description adds meaningful context beyond the schema, such as explaining that file_id restricts to one file's history, operation enum values, and project_path behavior (including the instruction to always omit it when pinned to a project).

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: 'show the append-only history of how memory changed over time, with a human-readable diff per entry.' It distinguishes itself from sibling tools by explicitly contrasting with 'search_memory or read_memory for what a file says now,' clarifying that this is history, not content.

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 clearly states when to use the tool ('to answer when and how a memory changed, or to recover text that an edit replaced') and provides explicit alternatives ('use search_memory or read_memory for what a file says now'). It also gives detailed parameter usage guidance, including how to filter and when to omit project_path.

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

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

The description goes well beyond the annotations (readOnlyHint=false, idempotentHint=false) by disclosing concrete side effects: 'Writes to local disk and appends to the change timeline,' original untouched, copy gets its own history, and the exact failure behavior on second call. This adds valuable context about mutations, safety (expected_hash), and project pinning behavior.

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

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

Although longer than typical, every sentence earns its place. The structure is logical: core action, side effects, usage alternatives, idempotency warning, parameter explanations, project_path nuance, and return value. No redundancy or filler; information is dense but well-organized.

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

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

With no output schema, the description correctly specifies the return object ('address, path, content_hash, and revision id'). It also covers critical context such as project_path behavior, expected_hash safety, the divergence behavior, and failure mode, making it fully complete for a mutation tool of this complexity.

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

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

Schema coverage is 100% with detailed descriptions for each parameter, so the baseline is 3. The description adds meaning by noting new_relative_path 'must not already exist' and explaining expected_hash as a guard against copying unseen revisions, providing slightly 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 opens with a specific verb and resource: 'copy one curated memory file to a new path under a new stable identity.' It clearly distinguishes from siblings by stating 'Use move_memory instead when the original should not survive,' and reinforces the copy semantics by explaining divergence and independent histories.

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 ('Use it to fork an existing memory into a variant') and when not to ('Use move_memory instead when the original should not survive'). Also provides operational guidance on project_path omission and warns against non-idempotent double calls, giving clear 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?

The description discloses safety behavior beyond annotations: guarded write with stale expected_hash fails safely, appends to change timeline, and preserves frontmatter/address/history. There is no contradiction with annotations; readOnlyHint=false aligns with 'MUTATING', and destructiveHint=false is consistent with the guarded, preserving nature.

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 adds value—scope, safety guard, exclusions, parameter rundown, and return value. It is well-structured with a clear opening and parameter list.

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, the description explains the return object and failure mode. It also covers project_path semantics and when to omit, making the tool fully understandable for 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?

With 100% schema coverage, the description adds nuance by tying expected_hash to 'the read that produced text' and explaining the complete-replacement semantics. While most info is also in the schema, this contextual linkage provides extra meaning.

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

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

The description uses a specific verb 'replace' and clearly states the scope: 'the body of one existing curated memory file while preserving its frontmatter, address, and history.' It distinguishes from siblings by explicitly saying 'Not for creating a new file: use write_memory' and 'Not for canonical memory... use pin_memory there.'

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 explicit when-to-use context: 'Read the file first to obtain the hash' and exclusions for pin_memory and write_memory. It also gives project_path guidance for pinned servers, making alternatives and prerequisites 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds meaningful behavioral context: it is local-only, takes no parameters, clarifies that an empty index means the user hasn't run docmancer setup, and describes the return object (path and counts). This goes beyond the bare 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 is compact yet information-dense, opening with the core purpose and then covering usage guidance, exclusions, and return shape without redundancy. Every sentence earns its place, and the structure front-loads the most important 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 no-parameter tool with no output schema, this description fully equips the agent: it explains what the tool does, when to call it, what it returns, and how it differs from related tools. No critical gaps remain, and the lack of an output schema is compensated by the explicit mention of return contents.

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 and the schema covers 100% of them (none). The description explicitly reaffirms 'takes no parameters', so the agent can be confident no arguments are needed. Per the rubric, no-parameter tools receive a baseline of 4.

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 read-only diagnostic for the local evidence index used by search_evidence, specifying that it reports presence, population, path, and source/section counts. It explicitly distinguishes itself from context_status and context_delivery, ensuring no ambiguity about its role.

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

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

It gives an explicit when-to-use instruction: 'Call it first when search_evidence returns nothing, to tell an empty index apart from a genuine miss.' It also states when not to use it and names the correct alternatives (context_status, context_delivery), making tool selection 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?

Beyond the annotations (destructiveHint=true), the description discloses on-disk writes, timeline appends, address stability, and path breakage. It also explains the expected_hash guard with a safety guarantee: 'a stale hash fails without changing anything.' This is rich, 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 every clause earns its place, covering why, how, safety, and relationships to siblings. It is well-structured with a clear flow from action to implications to parameter guidance, and ends with return-value notes.

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 explicitly states the return shape: 'an object with the unchanged address, the new path, and the new revision id.' It also addresses the mutating/destructive nature, safety guard, and all relevant usage contexts, making it fully self-contained.

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%, giving a baseline of 3. The description adds meaningful context to new_relative_path ('renaming is just a move within the same directory') and clarifies the hash's role from read_memory, enhancing the schema's static 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 'move or rename one curated memory file', a specific verb and resource. It further distinguishes from siblings by explicitly pointing to edit_memory for content changes and duplicate_memory for copying, so the agent instantly knows which tool to pick.

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

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

It clearly states when to use this tool (move/rename) and provides explicit alternatives: 'use edit_memory to change content, or duplicate_memory to copy rather than move.' It also gives practical guidance on project_path usage and omission rules.

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

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

Beyond the idempotentHint and destructiveHint annotations, the description reveals machine-wide disk persistence, the reconciliation survival property, the meaning of idempotency, and the return value shape. There is no contradiction with the annotations; instead, it adds substantial 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?

Despite being lengthy, every sentence contributes essential information: action, persistence semantics, reconciliation behavior, usage guidance, idempotency, reversal, parameter details, and return value. There is no redundancy or filler; the structure is front-loaded and logical.

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 is comprehensive for a mutating tool with subtle reconciliation implications. It covers the purpose, the critical survival property, when to use it, how to undo it, parameter semantics, and the return value. Since there is no output schema, the return-value note is essential and provided clearly.

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 schema already covers 100% of parameters, the description adds the key semantic that the text 'should read as a standalone statement because it is stored verbatim', which is not present in the schema. This elevates the parameter guidance beyond the baseline.

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

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

The description opens with 'pin one durable line into a canonical memory section', clearly stating the action and resource. It explicitly distinguishes from edit_memory and write_memory by specifying that this tool is for corrections, standing preferences, or facts the reconciler got wrong, giving it a clear purpose among 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 provides explicit when-to-use guidance ('for any correction, standing preference, or fact the reconciler got wrong or left out') and when-not-to-use alternatives ('use this, not edit_memory or write_memory'). It also mentions unpin_memory for reversal and canonical_memory for inspection, offering complete usage context.

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

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

Beyond annotations, it discloses local disk read with no side effects, and the ambiguous-match behavior that returns all candidate addresses instead of guessing. It also states the return shape including candidates list.

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 adds value, starting with 'READ-ONLY' and the core action, then addressing ambiguity, related tools, parameters, and return value. No fluff.

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 covers return values (body, frontmatter, address, content_hash, revision id, or candidates list). It also covers parameter nuances, relationship to sibling tools, and side effects, making it complete for the tool's complexity.

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 contextual meaning: address can be docmancer URI, relative path, or exact title, and project_path clarifies machine-wide vs. pinned project usage. This exceeds the 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 reads one curated memory file in full, resolved by stable address, relative path, or exact title. It distinguishes itself from sibling tools by explicitly directing to search_memory for unknown targets.

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 search_memory first when the target file is unknown, and notes this tool is the way to obtain content_hash for edit/move/duplicate/trash operations. This gives clear when-to-use and context.

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

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

The description richly discloses behavior beyond the annotations: it is mutating (writes to disk, appends to timeline), tokens are single-use and tree-scoped, failure modes are non-destructive (spent/foreign token fails without changing anything), and it returns an object with address, path, and revision id. This far exceeds the minimal annotation information.

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 key action ('MUTATING: undo a trash_memory call') and then provides focused, necessary details in a logical order. Every sentence adds value, and the parameter explanations are concise yet comprehensive.

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 mutating restore operation with no output schema, the description covers the full lifecycle: what it does, side effects, failure modes, parameter semantics, and return value. It is complete enough for an agent to invoke correctly and anticipate outcomes.

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?

While the schema already covers both parameters, the description adds crucial semantics: restore_token must be the exact token from a prior trash_memory call, and project_path carries a special omission rule when the server is pinned. This clarifies usage beyond the 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 specific action: 'undo a trash_memory call by restoring one curated memory file from its restore token.' It names the exact resource (curated memory file) and distinguishes itself from siblings by being the inverse of trash_memory.

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 frames the tool as undoing a trash_memory call, making the trigger condition clear. It also provides guidance on when to omit project_path (pinned server case) and notes that there is no way to browse trash from MCP, helping the agent decide whether this is the right tool.

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

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds valuable context: fully local execution, no network calls, returns [] when no docs indexed, and describes the return structure (excerpt, source document, relevance score). This goes well beyond the annotation hints and clarifies operational behavior.

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

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

The description is compact and front-loaded with 'READ-ONLY'. Four sentences cover purpose, local behavior, usage boundaries, and parameters/return value without redundancy. 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?

Given the tool's simple read-only nature, the description fully covers what it does, when to use it, its behavioral constraints (local-only, empty result), parameters, and output shape. An output schema exists, so the return format summary is supplementary but not 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% and both parameters have descriptions. The description adds a little context (e.g., 'natural-language text', 'default 8') but largely paraphrases the schema. Baseline 3 is appropriate since the schema carries the parameter 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 searches the local documentation index, with a specific verb ('search') and resource ('local documentation index'). It also distinguishes from siblings by explicitly noting it's for version-specific library/vendor behavior and not for user/project data, directing to search_memory, search_evidence, or ask_memory.

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 usage context: 'Use it for version-specific library or vendor behaviour' and clearly excludes user/project queries, naming alternative tools. This is strong when-to-use/when-not-to-use guidance that goes beyond mere inference.

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

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

The description adds substantial behavioral context beyond the annotations: it runs entirely locally with no network call or cost, returns [] when nothing matches, and describes the return object fields including record_uri. It also explains the semantic difference between raw evidence and curated memory. These details are not in the annotations and align with the readOnly/idempotent hints.

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

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

The description is front-loaded with the READ-ONLY label and core purpose, then efficiently covers scope, alternatives, parameters, and return format. Every sentence adds value and there is no repetition or fluff. Despite being long, it remains structured and scannable.

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 (4 parameters, 1 required, output schema, and sibling tools), the description is complete. It explains the source index, local execution, parameter semantics, return object fields, and empty-result behavior. With the annotations also provided, an agent has everything needed to invoke it correctly.

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

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

Although schema coverage is 100%, the description goes slightly beyond by specifying the default limit of 8, clarifying that include_history adds 'superseded' evidence, and expand_relations adds 'items linked to a direct match.' It also describes the expected return structure, which helps an agent understand parameter effects. Baseline was 3, but the added clarification justifies a 4.

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 'semantic search over the raw evidence index' and specifies that it searches memory, instruction, and rule files harvested by docmancer. It distinguishes the tool from siblings by explicitly contrasting with search_memory and ask_memory, making the purpose and resource 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 says 'Not for curated memory you or an agent deliberately wrote: that lives in a separate tree, so use search_memory for it, or ask_memory to get both at once.' This provides clear when-to-use and when-not-to-use guidance and names specific alternatives, making it easy for an agent to select 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?

Annotations already declare readOnly, idempotent, and non-destructive, but the description adds valuable behavioral details: local disk read, no embedding call, no cost, excludes archived/trashed files, and returns [] instead of an error. These go beyond the structured annotations and help the agent predict runtime behavior accurately.

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 with information but every sentence serves a purpose. It is front-loaded with the core purpose ('READ-ONLY: lexical search...') and logically flows through scope, exclusions, return behavior, parameter details, and return format. No wasted words for a tool this nuanced.

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 (3 params, output schema, multiple siblings), the description is fully self-contained. It covers purpose, filtering, empty-result semantics, sibling distinctions, parameter interpretation, return object fields, and the next step (read_memory). Nothing important is left 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 100% with descriptions for all three parameters, and the description enriches each: query is natural-language text, limit has default 8 and cap 50, project_path explains the machine-wide vs project-pinned behavior. This adds meaningful semantics beyond the raw 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 the tool performs 'lexical search over the curated memory tree' and specifies what that includes (decisions, constraints, conventions). It explicitly differentiates from siblings by noting it is 'Not the same store as search_evidence' and directs to ask_memory for a combined store, making the 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?

Provides explicit usage guidance: when to use this tool (lexical search over curated memory), when not to use it (search_evidence for raw files), and the alternative for both plus policy (ask_memory). Also explains the 'returns []' behavior, giving clear context for interpreting results.

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

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

Goes well beyond the destructiveHint annotation by disclosing reversibility, the restore_token mechanism, disk writes, timeline appends, and the safe-failure behavior on stale hashes. It also explains that nothing is erased, which is critical for a destructive operation.

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

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

The description is dense but each clause adds a distinct fact: identity, effect, guard, return value, and alternative. The most critical warning (reversible/destructive) is front-loaded, and there is no filler or repetition of schema fields.

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

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

Given no output schema, the description fully specifies the return shape (address + restore_token) and the failure condition (stale hash). It also covers the write side effects and the conditional project_path behavior, making it self-sufficient for a destructive operation.

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 covers all three parameters, but the description enriches them: expected_hash is tied to a prior read_memory call and stale-failure semantics, project_path's omit-when-pinned rule is explicit, and address aliases are contextualized. The description adds meaning beyond the schema's basic type info.

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 clear verb-object-effect: 'move one curated memory file to trash so it stops being read or recalled.' It differentiates from siblings by explicitly naming restore_memory and write_memory as alternatives, making the tool's unique role unmistakable.

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 prefer write_memory's status='archived' instead of trashing, and frames conditions for omitting project_path when pinned to a project. The expected_hash guard is presented as a safety precondition, providing concrete guidance for correct 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?

Beyond the destructiveHint annotation, the description discloses that deletion is permanent with no undo or restore token, writes machine-wide to local disk, takes no project_path, uses case-insensitive matching, and fails without changes when nothing matches. It also explains that only pinned lines are affected, providing rich behavioral context beyond structured hints.

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

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

The description opens with a clear MUTATING and DESTRUCTIVE warning, then states the core action, and follows with crucial caveats about matching, failure behavior, scope, parameters, and return value. Every sentence carries important information without redundancy, making it well-structured and appropriately sized.

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 the destructive nature, exact matching semantics, failure behavior, scope limitations, and the return object shape. Since there is no output schema, explaining the return format is particularly valuable. Combined with the annotations and input schema, the description fully equips an agent to select and safely invoke 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?

The input schema already fully documents the parameters, but the description adds essential clarification: text must be a case-insensitive substring, not a whole line and not a pattern. It also enumerates the allowed sections and reiterates the canonical-memory exclusion, supplementing the schema's 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's function: permanently removing pinned lines from a canonical memory section via case-insensitive substring match. It also distinguishes itself from siblings by noting that only pinned lines are removable and that generated content is handled by reconciliation, 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?

The description provides explicit usage guidance: read the section with canonical_memory first to avoid unintended matches, warns that a substring can match multiple lines, and clarifies that generated content should not be modified with this tool. It also notes that no-match failures are safe, enabling dry runs, and implicitly contrasts with alternatives by explaining what it cannot do.

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

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

Beyond annotations, it discloses 'Writes to local disk and appends to the change timeline; never silently clobbers, because the expect guard decides whether an existing file may be replaced.' It also explains the canonical-memory regeneration pitfall and the return object, adding meaningful behavioral context without contradicting 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 is dense but front-loaded with the mutation warning and core purpose, then flows into usage guidance, alternatives, and parameter explanations. Every section carries unique information; the length is justified for a 12-parameter 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?

Despite lacking an output schema, the description names return fields ('stable address, new content_hash, and revision id'), explains the guard behavior, warns about canonical memory, and covers all parameter groups. It is sufficiently complete for a complex write operation with no 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%, so baseline is 3. The description adds value by explaining the expect guard mechanics ('absent' default, content_hash for guarded update), requiring the Markdown suffix on relative_path, and offering the project_path caveat about machine-wide vs pinned-project usage. This goes beyond schema paraphrasing.

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 'MUTATING: create or update one curated memory file in the memory tree', giving a specific verb, resource, and scope. It also distinguishes itself from siblings by explicitly contrasting with pin_memory and edit_memory.

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 it to record a durable decision, constraint, or convention.' It also states when not to use it ('Not for correcting the reconciled canonical memory... use pin_memory') and when to prefer edit_memory, meeting the full when/when-not/alternatives bar.

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