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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the write/safety profile is covered. The description adds where the note lands (capture folder) and that frontmatter is generated, but says nothing about duplicate-title handling or whether an existing file of the same name is overwritten or rejected.

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

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

Three short sentences with zero filler: what it writes, the destination, when to use it, when not to. Purpose and destination are front-loaded before the exclusion.

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 could have stated what the caller gets back (created path/link or confirmation), and it says nothing about duplicate handling for a non-idempotent writer. Everything else an agent needs to select and call the tool is 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 description coverage is 80%, so the schema already documents title, body, topics and project. The description's use-case list ('plans, decisions, ideas... logs') loosely maps onto the kind enum, but it adds no syntax, format, or constraint detail beyond what the schema provides. Baseline 3 fits.

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 (write/create) and resource (a new note) plus the destination (the vault's capture folder) and the extra behavior (graph-ready frontmatter). It explicitly differentiates itself from the sibling brain_remember for the one-line-fact case.

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 concrete when-to-use triggers ('plans, decisions, ideas, meeting notes, or session logs the owner wants to keep') and an explicit exclusion with the alternative named ('Not for one-line facts (use brain_remember)'). An agent can route between the two without opening either schema.

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/openWorld=false, so the description need not restate safety. It adds genuinely useful behavioral context: hybrid retrieval (keywords + meaning + reranker), that paraphrases work, and that the reply self-reports coverage as good/thin/none. It does not describe truncation/pagination behavior, but that is largely covered by budget_chars in the schema.

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

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

Three sentences, front-loaded with the core behavior and formatted so routing, phrasing and output expectations read in order. Slightly dense but every sentence carries information; no filler.

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

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

With no output schema, the description still tells the agent what comes back (relevant sections with source note ids) and how to interpret confidence (coverage: good/thin/none), and it explains the retrieval mode so the agent knows how to compose the query. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully adds to the question parameter by specifying how to phrase it ('plain words', paraphrases okay, still include specific nouns/ids/dates). That guidance goes beyond the schema's 'question or topic, in plain words with specific nouns'.

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 and resource ('returns the most relevant sections from across the vault for a question, with source note ids') and explicitly contrasts itself with the sibling brain_search. An agent can identify the tool's distinct role without opening either 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?

Gives a clear when-to-use ('before brain_search when you need to answer or reason about something the owner may have written down') and an ordering relative to the alternative. It never states a when-not or explains exactly what brain_search does differently, 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?

Beyond the destructiveHint=true annotation, it discloses the soft-delete semantics (nothing is erased, the file lands in .trash/ which is never indexed) and that the result returns a restore path. It also enumerates the eligibility restrictions, which the annotations do not convey.

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

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

Two tight sentences, front-loaded with the action and mechanism, followed by the recovery and eligibility caveats. No filler.

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

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

For a single-parameter mutation with no output schema, the description covers the operation, reversibility, return value (restore path) and eligibility limits. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% for the single 'note' parameter, and the description adds no syntax or format detail beyond it. Baseline 3 applies when the schema fully documents the parameter.

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 (remove/move) and resource (note in Notes/ or Captures/) plus the exact mechanism (moving into .trash/). It also names the scope boundary — generated notes and the memory file cannot be deleted — which distinguishes it from sibling write/move 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?

Gives a clear when-not condition: generated notes and the memory file are ineligible, and the target folders are restricted to Notes/ or Captures/. It does not name an alternative for relocating rather than deleting (e.g., brain_move), so the alternative-selection guidance is implicit rather than explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so safety is partly covered. The description adds valuable behavior beyond them: the exactly-once precondition on old_text (a concrete failure mode), the heading-level replacement rule ('up to the next heading of the same or higher level; the heading itself stays'), and explicit exclusions. It omits any permission/auth requirements, hence not 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?

Three tight sentences, front-loaded with purpose before the operational rules. Every clause carries information (scope, modes, preconditions, exclusions) with no filler.

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

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

For a 6-param mutation tool with no output schema and annotations already covering the safety profile, the description covers modes, preconditions, and exclusions. It doesn't state what happens on precondition failure (e.g., ambiguous old_text) or any return shape, but nothing critical for invocation 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 83%, so baseline is 3, and the description clearly exceeds it by explaining mode exclusivity and mode-specific semantics: old_text must occur exactly once, new_text may be empty, section replaces content up to the next same-or-higher heading while keeping the heading, and append adds at the end.

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 ('Change part of a note') and immediately scopes it to Notes/ or Captures/ and distinguishes it from a full rewrite, which implicitly separates it from brain_write. An agent can tell it does partial edits, not whole-note replacement, without opening the 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 gives explicit usage rules: 'Give exactly one of' three mutually exclusive modes, and states what cannot be edited (generated notes, the memory file). It doesn't name a sibling tool directly, but the 'without rewriting it' framing routes the agent away from brain_write.

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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower. The description adds genuine behavioral context beyond that: it explains that a concept input resolves to every project touching that concept, which tells the agent how the tool behaves for non-note inputs. It says nothing about result ordering, the limit's effect, or truncation.

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

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

Three short sentences, no filler, with the core capability in the first clause. The concept example and the use-case line each add distinct information rather than restating the opening.

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 usefully lists the returned relationship categories, so the agent knows roughly what to expect. It omits how the limit behaves and whether results are paged or ordered, which is the main remaining gap for a two-parameter read 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 50%: 'note' is documented but 'limit' has no schema description, and the description never mentions limit either. It does reinforce that the note argument accepts hubs and concept names, mildly extending the schema's own wording. With half the parameters undocumented, this is adequate but not compensating for the gap.

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

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

The description names a concrete retrieval target and enumerates exactly what comes back: outgoing links, backlinks, and topic-sharing notes. That is far more specific than a name restatement and clearly separates it from reading tools like brain_read. It stops short of naming which sibling to prefer when the agent wants a broader search (e.g. brain_search), so it lands at 4 rather than 5.

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?

'Use it to hop sideways between projects' states the intended context of use, and the OAuth example shows the concept-input scenario concretely. There are no exclusions or named alternatives, so it gives clear context but no negative 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 already declare this is a safe, idempotent, closed read, so the description is free to add behavioral meaning beyond safety: the bundle is a persona/working-context payload meant to be adopted, and passing `topic` changes the payload composition. It doesn't state format, size, or latency of the full bundle, but the added context is substantive.

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

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

Front-loaded with the imperative invocation rule, then the return contents, then the optional narrowing parameter. Four tight sentences with no filler.

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

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

With no output schema, the description carries the burden of describing what comes back, and it enumerates the payload well (identity, preferences, feedback rules, projects, recent activity). It omits payload size/format expectations, which is the only real gap for a bundle of this scope.

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 schema already says "Omit for the full bundle," so 3 would be the baseline. The description earns above baseline by explaining the tradeoff the parameter actually controls — a smaller bundle containing only the memory notes that apply — which clarifies the filtering effect on returned content.

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 (Returns) and enumerates the exact resource contents: owner identity, preferences and feedback rules, projects, recent activity. This is distinctly different from read/search siblings like brain_search or brain_read, so an agent can route to it without opening schemas.

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

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

"Call this FIRST in every conversation" gives a clear, strong usage condition, and the description explains when to narrow with `topic`. It stops short of naming alternatives or a when-not condition (e.g., what to use for later queries in the same conversation), so it isn't fully explicit about the sibling choice.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description earns credit by adding two traits the annotations don't carry: a non-overwrite guarantee and a side effect where broken links are reported. That is meaningful mutation context beyond the 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?

Two sentences, zero filler, and the scope/behavior come before the example. Every clause carries information an agent can act on.

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?

There is no output schema, so the description usefully covers the observable result (refused overwrites, reported dangling links). What is missing is smaller: no indication of what happens if the destination directory does not exist or what the tool returns on success.

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

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

Schema description coverage is 100% and both parameters have examples in the schema ('Notes/Harbor Ledger.md' and note id/title/[[wikilink]]). The description adds no path syntax, length limit, or wikilink-vs-path resolution details, so the baseline of 3 applies.

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

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

States a specific pair of verbs (move/rename) against a specific resource (a hand-written note) and scopes it to Notes/ and Captures/, with a concrete example of promoting a capture into Notes/. It never names the siblings it must be distinguished from (brain_edit, brain_write, brain_capture), so the separation is inferable rather than explicit.

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 'promote a capture into Notes/' example implies a usage context, but there is no explicit when-to-use versus brain_edit/brain_write, no stated prerequisites, and no conditions under which the tool should not be used. Usage is suggested, not specified.

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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower; the description still adds real value by disclosing the aggregate return shape and the dual behavior of listing all projects when the name is omitted. It does not mention rate limits, result caps, or pagination, so it is not exhaustive.

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

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

Two dense sentences, zero filler, with the aggregation scope front-loaded and the list-all fallback stated last where it belongs.

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 usefully enumerates the returned sections and covers the zero-argument listing mode, which is what an agent needs to call it correctly. The one gap is the unexplained recent_days window, which affects how results are scoped.

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 only 50%: 'project' is documented in the schema, but 'recent_days' carries no description and the tool description never names it or explains the 30-day default / 1-365 range. 'What changed recently' hints at the recency window but does not compensate for the undocumented parameter.

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 and resource ('One-call briefing on a project') and enumerates what the briefing contains (notes by type, progress, decisions, recent changes), which implicitly separates it from single-purpose siblings like brain_read or brain_recent. It never names an alternative sibling explicitly, so it stops short of a 5.

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?

'Call this before discussing any project' is an explicit, actionable when-to-use trigger, and the omit-the-name mode is spelled out. There is no when-not guidance or named alternative for narrower needs (e.g. when brain_search is preferable), so it is clear context without 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds useful return content details—frontmatter metadata, topics, and links—that go beyond what annotations provide, though it omits error behavior and response format specifics.

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 tightly written sentences with zero waste. The purpose is front-loaded, and the optional section behavior is noted without unnecessary elaboration.

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

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

For a simple read tool with no output schema, the description covers the core return content (frontmatter, topics, links) and the section option. It could mention missing-note behavior or response format, but nothing critical is absent for an agent 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?

Schema description coverage is 100%, so the schema fully documents all three parameters. The description echoes the note and section concepts but adds no syntax or format details beyond what the schema already provides, making the baseline 3 appropriate.

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

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

The description states a specific verb ('Return') and resource ('one note in full or one section') by note id, title, or wikilink target. It clearly distinguishes reading a single note from broader tools like brain_search, but does not explicitly name any sibling alternative.

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

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

Usage is implied: use this when you have a note identifier and want the full note or a section. However, there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives like brain_search for discovery.

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, closed-world behavior, so safety is covered. The description adds genuinely non-obvious behavior: results are ordered newest-first and hubs/concepts are suppressed unless include_structural is set, which materially changes what comes back.

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

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

Three tight sentences with the core scope (what, window, ordering) front-loaded, followed by use-case framing and the structural-exclusion caveat. No filler or restatement of the tool name.

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 list tool with annotations covering the safety profile and no output schema, the description covers scope, ordering, and the key filtering caveat. The remaining gap is the undocumented 'limit' and 'project' parameters, which an agent must infer from the schema alone.

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 carries the burden. It gives real meaning to 'days' (the N-day window) and 'include_structural' (which entity types are excluded), but says nothing about 'limit' or the 'project' filter, leaving half the parameters undocumented.

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 and resource ('Notes modified in the last N days, newest first'), which clearly separates it from a general query tool. It does not, however, explicitly name a sibling such as brain_search to route the agent away from a broader search.

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

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

The description gives concrete usage contexts via example questions ('what am I working on', 'what did I do last week'), which tells the agent when this tool is the right pick. It stops short of stating when NOT to use it or naming the alternative tool for filtered/full-history queries.

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 establish write/non-destructive/non-idempotent, but the description adds behavior not visible in structured fields: near-duplicates are refused by default, force overrides that refusal, and the fact propagates to brain_identity immediately. These are substantive operational traits (dedup semantics, side-effect timing) that an agent cannot infer from the schema or 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?

Five short sentences, all load-bearing: action, content to include, override mechanism, and exclusion. The core action is front-loaded in the first clause and nothing is repeated from the schema or title.

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 5-parameter mutation tool with no output schema, the description covers purpose, required content guidance, duplicate handling, and scope limits. No output schema exists, so return-value explanation is not needed, and the annotations carry the safety profile.

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 only 40% (only force and category are documented), so the description must compensate. It does: 'Include why it matters and how to apply it' explains the why and how_to_apply fields, and the enumeration of fact kinds maps onto the category enum. It adds real meaning beyond the schema, though it never explains the 2000-character limit or the fact minLength constraint.

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 ('Append one durable fact about the owner to their memory file') and enumerates what counts as such a fact (preference, correction, project constraint, reference), which mirrors the category enum. The 'durable fact' framing plus the explicit exclusion of 'session trivia' effectively separates it from capture-style siblings without needing to name 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?

Gives a positive use case (durable facts), an explicit exclusion ('Do not store session trivia'), and a procedural alternative for the duplicate case ('pass force=true to store anyway'). It stops short of naming or routing to sibling tools for adjacent operations, so it is clear context rather than full when/when-not/alternative 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 cover the safety profile (readOnly, idempotent, closed-world), and the description adds genuinely useful behavior beyond that: hybrid keyword+semantic retrieval with spelling correction, ranked results with snippets, and a self-reported coverage statement. It doesn't mention result volume limits or truncation 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?

Three tight sentences, front-loaded with the core purpose and search semantics, then the return shape. The parenthetical is dense but each clause carries information; nothing is padding.

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

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

With no output schema, the description steps in to describe the return payload (ranked hits, snippets, note ids) and the search semantics. It is adequate for a 6-param search tool, though it leaves filter semantics and the limit ceiling undocumented.

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 67% and the description only gestures at 'optional filters' without explaining type, topic, project, since, or the limit cap of 50. In particular the type enum with 12 values is left entirely to the schema, so the description adds little beyond 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?

States a specific verb (search) and resource (every note) with scope (full-text, optional filters), and it distinguishes itself from brain_recent by saying 'every note' rather than recency-based listing. It also names brain_read as the downstream consumer of returned note ids.

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?

Explains accepted input styles ('keywords or a short question both work') and what to do with the results (note ids for brain_read), which gives clear context for use. It stops short of naming when to prefer a sibling like brain_recent or brain_graph, so it lacks 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?

Annotations declare destructiveHint=true and idempotentHint=true; the description adds real value by disclosing the path constraint and the overwrite=true condition that triggers replacement. Does not mention permission requirements or what a failed overwrite returns, but covers the destructive surface adequately.

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

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

Three sentences, front-loaded with the create/replace action, then constraints and the sibling differentiation. No filler.

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

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

For a 9-param mutation with destructive and idempotent annotations and a rich schema, the description covers scope, the hub behavior, the overwrite path, and the sibling boundary. It leaves return-value and permission specifics unstated, but the schema and annotations carry those.

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

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

Schema coverage is 89%, so the schema already documents all nine parameters including the overwrite and type semantics. Description reinforces the overwrite condition but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States specific verb (create/replace), resource (note), and the constrained location (under Notes/ or Captures/). Explicitly distinguishes from sibling brain_capture by noting who sets the type, and rules out generated vault notes.

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?

Names the alternative (brain_capture) and the condition selecting this tool: hand-written hubs, guides, runbooks. Also states an explicit exclusion ('Generated notes elsewhere in the vault cannot be written').

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