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

The readOnlyHint annotation already establishes this is a safe read. The description adds one genuinely useful behavioral fact beyond the annotations: the data source (claude-mem) and the conditional 'if installed', implying the tool may yield nothing on an unconfigured system. It stops short of describing ordering, freshness windows, or what an empty result means.

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 short sentence with the source and the conditional caveat front-loaded; nothing is padded. It is efficient, though the brevity contributes to the gaps in purpose and parameter coverage rather than being a virtue in itself.

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

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

With an output schema present, return values need not be explained, so the main omissions are usage routing and parameter meaning. For a one-optional-parameter read tool this is minimally viable, but an agent still cannot tell how this differs from goldfish_recall.

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

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

Schema description coverage is 0% for the single 'limit' parameter, so the description carries the full burden and provides nothing. It never states that 'limit' bounds the number of summaries returned or what the default of 5 means in practice; 'recent' is the only sizing hint and it is vague.

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 phrase names the resource (session-compression summaries from claude-mem) but supplies no verb, leaving it ambiguous whether it lists, fetches, or filters them. It also does not distinguish itself from siblings like goldfish_recall or goldfish_search, which plausibly return similar memory 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?

The description gives no when-to-use guidance, no exclusions, and never names an alternative among the six siblings. The 'if installed' clause hints at a precondition but does not say when an agent should prefer this over goldfish_recall or goldfish_search.

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, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: entries are evidence-linked, explicitly 'not a diagnosis,' and meant to be revisited as they age — framing the reliability and intent of the data the agent receives.

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

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

Purpose is front-loaded in the opening sentence. A few sentences restate the discretionary nature of the call ('entirely optional,' 'at your own discretion,' 'nothing requires you to call this,' 'not a mandate'), which is mild redundancy, but the overall length is warranted for a tool whose entire value proposition is tonal/behavioral.

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

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

With an output schema present, return values need no explanation, and with zero parameters there is no input surface to fill. The description supplies purpose, provenance, usage judgment, and behavioral framing — everything an agent needs to decide whether and how to call 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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies.

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

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

The first sentence states a specific resource — a cumulative persona file aggregating insight notes into one document — and explicitly ties it to goldfish_reflect as the source of the underlying entries. An agent can distinguish this retrieval tool from goldfish_reflect (which generates the insights) without opening a schema.

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

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

It states the call is 'entirely optional' and offers concrete conditions for use (shape tone, catch a pattern worth mentioning), plus the caveat not to treat surfaces as a mandate. It lacks an explicit when-NOT-to-use or a direct comparison to siblings like goldfish_recall or goldfish_context, so it stops short of full routing guidance.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds essentially nothing beyond that — no note on result limits, ordering, or what happens on a name miss. With annotations carrying the safety profile, this is adequate but thin.

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

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

A single front-loaded sentence with no filler. It is arguably too terse for the ambiguity it needs to resolve, but nothing in it is wasted.

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

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

An output schema exists, so return values need not be described, and the read-only annotation covers safety. Still, with 0% parameter description coverage and an unresolved overlap with goldfish_search, the definition leaves real gaps for an agent.

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

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

Schema description coverage is 0%, so the description must explain the three parameters. It hints at 'name' and loosely at 'query' ('search/list'), but 'type' is never mentioned anywhere, leaving one of three parameters with zero 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?

States specific verbs (read, search, list) and a specific resource (curated memory notes), so the general purpose is clear. However, it does not differentiate itself from the sibling goldfish_search, and by using the word 'search' it actively blurs the boundary with that sibling.

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

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

It implies two modes — lookup 'by name' vs 'search/list' — which gives some usage signal. But it never says when to prefer this tool over goldfish_search or goldfish_context, leaving a genuine ambiguity for an agent choosing among 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 only grant readOnlyHint=true; the description adds substantial context beyond that — restricting to role='user' words, spanning full history via brain, and explicitly disclaiming that it does not diagnose, summarize, or conclude. This is exactly the 'what it does not do' information annotations cannot carry.

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

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

Front-loaded with the core scope and the non-conclusion disclaimer, then usage guidance. Slightly long and the downstream workflow caveat borders on instruction creep, but every sentence carries actionable content.

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

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

An output schema exists, so return-value explanation is unnecessary. Given the read-only annotations, the description covers scope, the focus/omit behavior, and the intended follow-up workflow, leaving no material gap for correct invocation.

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

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

Schema coverage is 0%, so the description must compensate. It fully explains `focus` (a single angle vs. default battery of frustration/habit/drive/goal), but does not describe `limit_per_query`, leaving one of two parameters undocumented. Strong partial compensation.

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

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

States a specific verb+resource — searches the user's own role='user' language across full transcript history to return cited evidence. It explicitly positions itself against siblings by noting it behaves 'same as goldfish_search' in returning excerpts, while previewing the downstream goldfish_remember step.

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

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

Gives explicit when-to-use (behavioral/preference pattern evidence), when to pass `focus` (one specific angle) vs. omit it (default battery), and even prescribes downstream handling: write with goldfish_remember as tentative pattern-noticing and mention rarely. Nothing is left to inference.

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

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

No annotations, so the description carries the full burden; it does disclose the durability/lifecycle semantics (insights are tentative and should be revisited/pruned, unlike settled user facts) and points to goldfish_reflect for provenance. It does not cover write behavior such as deduplication/overwrite or permission prerequisites, leaving a gap for a mutation tool.

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

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

Front-loaded with the core action and the type enumeration, then layered guidance. Dense and purposeful, though the final paragraph on insight/user distinction is somewhat verbose relative to the value it adds.

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?

Output schema exists so return values need no explanation, and the description handles routing and the trickiest parameter value (`type`) well. The remaining gap is the absence of any semantics for the other three required parameters on a write tool.

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

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

Schema coverage is 0% with four required params, so the description must compensate. It supplies the meaningful value set for `type` and explains the insight-vs-user distinction, but says nothing about `name`, `content`, or `description`, which remain undocumented in both description and schema.

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

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

States a specific verb+resource ('Write a curated, durable memory note') and immediately names the categorization scheme (user/feedback/project/reference/insight). It also positions the tool against non-siblings (brain for raw transcript, claude-mem for summaries), so an agent can distinguish it from surrounding memory tools.

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 ('facts worth carrying into future sessions') and when-not-to-use with named alternatives ('not raw transcript — brain', 'not session summaries — claude-mem'), plus a quality bar ('hand-picked, still-true facts'). This is textbook routing guidance.

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

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

Annotations only declare readOnlyHint=true, so the description's guarantee that every result is a citation (file, line span, sha256) verifiable via the underlying brain-mcp toolset — never synthesized or paraphrased — is a real behavioral contract beyond the safety hint. It does not mention ranking, ordering, or pagination behavior, keeping it short of a 5.

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

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

Two short sentences, front-loaded with the core action; the citation guarantee follows immediately. Nothing is padded, though the trailing clause about the brain-mcp toolset is slightly redundant with the opening mention.

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

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

An output schema exists, so return structure need not be explained, and the citation claim partially covers result semantics. However, the absence of sibling routing and of any documentation for agent/limit leaves an agent under-equipped for a 3-parameter tool in a crowded family.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning and it does not. The agent filter and the limit (default 10) parameters are entirely undocumented in both schema and description; only the obvious 'query' string is inferable.

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?

Names a specific verb (Search) and resource (full AI conversation history) and scopes it to sources like Claude Code and Codex via brain-mcp. It does not differentiate from siblings such as goldfish_recall or goldfish_context, so an agent cannot tell from the description alone which of the family 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?

No when-to-use guidance and no exclusions are given. With six siblings in the same family (recall, context, remember, reflect, persona, status) the description offers nothing about which situations select search over recall or 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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the safety profile is covered. The description adds only the scope fact (three tiers) and says nothing about cost, freshness, or whether the check probes live backends versus returning cached health.

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

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

A single front-loaded sentence with no filler – appropriately sized for a trivial no-argument status call, though it is essentially a noun phrase rather than a sentence with an action verb.

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

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

An output schema exists, so return-value detail belongs there, and with no parameters the only burden is stating what the call reports – which it does (health across three memory tiers). It stops just short of explaining what 'health' means or why an agent should check 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 tool takes zero parameters, so the baseline of 4 applies; there is no argument semantics for the description to clarify or omit.

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?

Names a specific resource (health/status) and its scope (all three memory tiers), which no sibling covers – goldfish_search, goldfish_remember, etc. are all distinct operations. It is distinguishable from siblings, though it never explicitly contrasts itself with them.

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

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

No guidance on when to call this versus alternatives such as goldfish_context or goldfish_recall, nor any stated trigger (e.g., diagnostics before recovery). The agent must infer the use case entirely from the name.

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