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

Despite annotations already marking destructiveHint=true, the description adds crucial nuance: it defaults to deprecation to preserve an audit trail, and only purges records when hard_delete=true. This meaningfully explains what gets changed or destroyed and under what condition.

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

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

Two sentences with no filler. The core action and target scope are front-loaded, followed by targeting modes and the key behavioral caveat about hard_delete. 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 destructive tool with 5 parameters and no output schema, the description covers the essential operational details: what it removes, how to target memories, the default non-destructive behavior, and how to override it. The audit-trail rationale also helps the agent anticipate consequences. No critical invocation information is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by grouping the parameters into three targeting modes (ID, file_path, query), implying they are alternative ways to select memories, and by clarifying the default soft-delete behavior versus hard_delete=true. This exceeds the schema's per-parameter descriptions.

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

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

The description uses specific verbs ('Remove or deprecate') with a clear resource ('specific memories from Local Brain') and immediately explains the targeting options (ID, file path, search query). This distinguishes it from sibling tools like brain_prune by emphasizing targeted, individual-memory operations.

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 clearly communicates when to use this tool: to forget specific memories by ID, path, or query. It doesn't explicitly contrast with brain_prune or list exclusions, so it stops short of a full when-to-use/when-not-to-use guide, but the context is clear.

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

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

Beyond the annotations (which only show non-read-only, non-idempotent, non-destructive), the description discloses automatic behaviors: 'multi-agent attribution, quality evaluation, deduplication, contradiction detection, and supersession tracking.' This tells the agent that the store is not a simple write and that the system will process, reconcile, and potentially supersede existing memories. This is exactly the kind of behavioral context the description should add.

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

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

The description is compact and well-structured: one sentence defines the tool's scope, one sentence lists its automatic behaviors, and two examples illustrate ideal input. Every sentence earns its place, and the most important information comes first.

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 9 parameters but only 1 required, full schema coverage, and no output schema, the description covers the core write intent and automatic post-processing behaviors well. It doesn't describe return values or failure modes, but the absence of an output schema lowers the burden. The main gap is not explaining how this relates to sibling tools like brain_validate or brain_trace, but the description is otherwise sufficient for correct use.

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 covers all parameters at 100% with descriptions, so the baseline is 3. The description adds value by showing examples of high-quality lesson strings ('Never use RS256 in dev', 'JWT refresh token expires in 7d; rotate on each use') and advising 'Be specific and actionable,' which clarifies the expected semantic quality of the required lesson parameter. This pushes it above baseline.

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

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

The description immediately states a specific action and resource: 'Store a new durable lesson, architecture decision, bug root-cause, or team convention.' It clearly enumerates the kinds of content accepted and gives concrete examples, making the tool's role unmistakable and naturally distinct from siblings like brain_recall, brain_prune, and brain_forget.

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

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

The description provides clear context: use this tool when you want to persist a lesson or decision. It lists valid content categories and gives examples of good lessons, which helps the agent judge appropriateness. It does not explicitly name alternatives or state when not to use the tool, so it falls slightly short of a 5.

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

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

The description discloses the mutating nature by saying 'clean up' and 'remove,' matching the destructiveHint annotation. It also adds useful context beyond the annotations by explaining the optional git-diff invalidation pass that detects modified/deleted files.

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

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

The description is compact and front-loaded: it states the core purpose in the first sentence and provides the key usage trigger in the second. Every sentence earns its place with no redundant detail.

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

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

Given the tool's low complexity (2 optional parameters, no output schema) and the destructiveHint annotation, the description is complete enough for an agent to invoke it correctly. It covers what is removed, when to run it, and the optional invalidation behavior.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds modest context by elaborating on the invalidation pass as git-diff based, but it does not substantially expand parameter meaning beyond what the schema provides.

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

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

The description clearly states a specific verb ('clean up'), resource ('memories'), and scope ('stale or deprecated'). It does not explicitly differentiate from sibling brain_forget, but the stale/deprecated framing and git invalidation context make the role reasonably distinct.

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

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

The description gives explicit timing guidance: 'Run this after major refactors.' It explains the benefit of preventing outdated context from polluting recalls, but it does not explicitly state when to prefer brain_forget or other alternatives.

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 provide read-only, idempotent, and non-destructive hints, so the description correctly avoids repeating them. It adds meaningful behavioral detail beyond those hints: deterministic ranking, validation boost and contradiction penalties, token-capped output, and file/package scoping.

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

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

The description is compact and front-loaded: the first sentence states the core purpose, and the second sentence adds ranking and output constraints. There is no filler, repetition of schema details, or redundant annotation restatement.

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

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

For a search tool with full schema coverage and strong safety annotations, the description covers purpose, memory sources, scoping, ranking behavior, and output size limit. It does not describe the exact return shape, but the absence of an output schema is partially mitigated by the explicit statement of what is returned and the token cap.

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

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

Schema description coverage is 100%, so every parameter already has a meaningful description, default, or enum. The description's mention of 'current file and package scope' reinforces the file_path parameter, but it does not add significant new semantics beyond what the schema already documents.

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

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

The description clearly identifies an action ('semantically search') and a resource ('local codebase memory'), and it specifies the kinds of content returned: lessons, bug fixes, architecture decisions, and conventions. It distinguishes itself from write/delete siblings like brain_learn and brain_forget, but it does not explicitly contrast with potentially similar siblings like brain_trace or brain_status.

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

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

The description gives clear context for when the tool applies: retrieving relevant memories across agents, from git history and AI sessions, scoped to the current file/package. It does not explicitly name alternatives or provide when-not-to-use conditions, but the retrieval intent is clear enough to guide selection among the memory-management siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is clear. The description adds value by disclosing exactly what information is returned, including database storage path, contradicting none of 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?

A single sentence that front-loads the core purpose ('Get system diagnostics...') and then efficiently lists the specific return categories. Every element earns its place, with no filler or repetition.

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

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

For a simple, parameterless, read-only status tool with no output schema, the description adequately covers what the agent needs to know: the diagnostic scope and each returned data category. The annotations cover side-effect safety, so nothing critical is missing.

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

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

The tool has zero parameters and the schema properties are empty, so schema description coverage is effectively 100%. Per the rubric, a zero-parameter tool receives a baseline of 4; the description appropriately adds no parameter details.

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

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

The description states a specific verb ('Get') and a clear resource ('system diagnostics, memory statistics, multi-agent breakdown, and validation health'). It also enumerates concrete return contents, making the tool's purpose unmistakable and distinct from the action-oriented sibling names like brain_prune, brain_learn, and brain_validate.

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

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

The description implies when to use the tool: whenever an agent needs system-level diagnostics or memory/validation health. However, it does not explicitly contrast this with brain_validate, which could plausibly overlap with 'validation counts' and 'contradiction flags.' No exclusions or alternative routing are given.

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

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

Annotations already indicate a read-only, idempotent, non-destructive operation. The description adds meaningful behavioral context: it returns results in chronological order and includes confidence and status flags, and it emphasizes that results span all agents. 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?

Two concise sentences with no fluff. The primary action and scope appear first, followed by a clear summary of what is returned and in what order. 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?

For a simple single-parameter read tool with full schema coverage and no output schema, the description covers the key return contents, ordering, and scope. Minor gaps like pagination or a note on how far back the history reaches are not critical for this simple 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?

The input schema fully documents the only parameter, file_path, including an example format. The description does not need to add much, and it does not add new semantic detail 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 clearly states a specific verb ('Show'), a specific resource ('memory entries associated with a specific file'), and a scope ('across all agents'). It conveys what the tool does and what distinguishes it, though it does not explicitly name a sibling alternative to differentiate from.

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

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

The description implies when to use the tool: when you need the full memory/history for a particular file, including fixes, architecture decisions, bugs, and agent attribution. It does not explicitly state when not to use it or which sibling tool to prefer instead.

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 show this is a mutating, non-idempotent operation, and the description properly discloses the side effects: incrementing the validation count, recording the validating agent, and boosting confidence. This goes beyond the annotations and gives an agent a clear picture of the mutation.

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

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

The description is two sentences with no filler. It front-loads the primary action and then lists the side effects succinctly, making efficient use of the space.

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

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

For a simple two-parameter mutation with no output schema, the description covers the main behavior and side effects sufficiently. It leaves out explicit alternative routing and edge-case behavior, but those are minor given the tool's low 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?

The input schema already describes both parameters fully (id and optional agent), with 100% schema description coverage. The description adds light context by mapping 'records the validating agent' to the agent parameter, but it does not substantially enrich parameter understanding.

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

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

The description clearly identifies the action ('Validate'), the resource ('an existing memory'), and the context ('current session'). It also lists concrete effects, making the tool's role distinct among siblings, though it does not explicitly name any sibling to differentiate from.

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

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

The description implies the tool is for confirming that a memory was helpful, but it provides no explicit guidance on when to use this tool versus brain_recall, brain_learn, brain_forget, or other siblings. No alternatives or exclusion conditions are mentioned.

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