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

The description is consistent with the annotations (write, non-destructive, non-idempotent) and adds useful context: notes land in the capture folder with generated frontmatter, and the reply lists named-but-unlinked notes. With annotations already declaring the safety profile and no output schema, this is helpful but thin — it does not warn about duplicate titles despite idempotentHint=false, nor explain overwrite or failure 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: what it does, when to use it, when not to. The scoping constraint is front-loaded and no sentence 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?

No output schema exists, and the description only partially covers the return value (naming the 'existing notes named without linking' detail). For a 5-parameter write tool that creates files, it lacks any mention of naming collisions, folder resolution, or what happens when the capture folder 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 80%, so the schema already documents body, title, topics, and project. The description adds no per-parameter guidance beyond the general 'graph-ready frontmatter' framing, and the 'kind' enum is left to the schema's enum and default. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Write a new note into the vault's capture folder') plus the distinguishing trait of graph-ready frontmatter. It explicitly separates itself from brain_remember, which is also in the sibling list.

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 concrete use cases (plans, decisions, ideas, meeting notes, session logs) and an explicit exclusion with the alternative: 'Not for one-line facts (use brain_remember).' 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?

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?

Goes well beyond the destructiveHint=true annotation: it explains that old_text must occur exactly once, that new_text may be empty, that section replacement spans up to the next same-or-higher heading while the heading itself survives, and that generated notes/memory are off limits. It even discloses return behavior (the reply lists existing notes the new text names without linking).

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: scope first, then the three mutually exclusive modes, then the exclusions and reply note. No redundancy and nothing buried.

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?

Six parameters with one required, no output schema, and the description covers modes, exclusions, and return summary well. Minor gaps remain: what happens when old_text matches zero or multiple times (error vs no-op) and whether the target note must already exist.

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 documents 83% of parameters, but the critical mutual-exclusivity rule ('Give exactly one of...') exists nowhere in the schema, and neither does the section boundary semantics or the permission for an empty new_text. These are exactly the constraints an agent needs to avoid a wrong invocation.

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 ('Change part of a note') plus a hard scope restriction (only under Notes/ or Captures/), and the phrase 'without rewriting it' implicitly separates it from brain_write. It never names a sibling, so the differentiation 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?

Gives crisp positive selection rules ('Give exactly one of: old_text + new_text, section + content, or append') and negative ones ('Generated notes and the memory file cannot be edited'). It stops short of routing to alternatives, e.g. pointing at brain_write for full rewrites or brain_read to inspect before editing.

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, so the bar is lower; the description still adds non-obvious behavior: default is current truth, a bare date resolves to end-of-day, history is ordered oldest-first and includes replacements/expiry. It omits pagination/limit behavior and result shape, keeping it at 4.

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?

One dense paragraph, front-loaded with the default behavior, then each mode in the order an agent would consider them. Every clause 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?

For a read-only, no-required-param list tool with no output schema, the description covers the query modes and the id linkage to brain_remember's `replaces`, which is the crucial cross-tool detail. Only the `category` enum and limit semantics are left unreconciled.

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 67%, and the description adds real semantics the schema lacks (e.g. a bare date means end of that day, history includes not-yet-valid versions). However, `limit` and especially the `category` enum are never explained in the description, leaving a 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?

States a specific resource (facts recorded via brain_remember) plus the temporal dimension (when each was true), and names the sibling that creates them. An agent can distinguish this from brain_search/brain_read without opening any 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?

Explicitly explains the default mode (facts true now) and the condition that selects each alternative mode: as_of for point-in-time, history for all versions, subject for narrowing, query for keyword filtering. It stops short of naming a sibling alternative (e.g. when to prefer brain_search over this), so 4 rather than 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 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?

Beyond the readOnly and idempotent annotations, the description discloses that the bundle should be adopted as persona and working context, that captured facts are current-only, and that passing topic returns a smaller bundle with only applicable memory notes. These are meaningful behavioral traits not captured by annotations or 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?

The description is front-loaded with the critical instruction to call it first, then explains returns, usage posture, sibling distinction, and parameter effect. Every sentence is useful and appropriately sized for a one-parameter startup 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?

For a simple, optional-parameter, read-only tool with annotations and no output schema, the description covers purpose, expected return content, ordering requirement, persona adoption, historical-facts alternative, and topic behavior. Nothing essential 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 schema already documents topic and the omit-for-full-bundle behavior. The description adds useful semantic detail by clarifying that topic is a few words about the conversation and that it narrows the result to applicable memory notes.

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

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

The description specifies a clear verb and resource: load the owner's identity and standing context. It enumerates the returned content (owner identity, preferences, feedback rules, projects, recent activity) and explicitly distinguishes itself from brain_facts by noting that brain_facts holds historical facts.

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 a direct usage rule: 'Call this FIRST in every conversation.' It also states when to use the optional topic parameter and implies the alternative for historical facts by naming brain_facts.

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?

Strong disclosure of non-obvious behavior that annotations cannot express: near-duplicates are refused, apparent changes are held back pending confirmation, superseded facts remain in the file as history but leave brain_identity, and new facts take effect immediately. However it does not describe what a call returns (e.g. the new fact's id), which an agent needs for later `replaces` calls; the hint that ids appear as heading stamps is indirect.

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 first clause, and nearly every sentence carries a rule or condition. It is dense to the point of being a wall of rules, with parameter guidance interleaved rather than grouped, which slightly hurts scanning.

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

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

Covers the full write-path behavior for a 10-parameter, non-idempotent mutation with no output schema: dedupe, history retention, temporal bounds, and override. The one gap is the response shape and how to obtain a fact id, which matters because `replaces` depends 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?

Adds genuine meaning beyond the 70%-covered schema: the `replaces` value format and its history-preservation effect, the subject+attribute pairing that makes later facts self-replacing, and the temporal semantics of valid_from/valid_until. Even the undocumented `why` and `how_to_apply` fields are given intent.

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?

Specific verb and resource ('Append one durable fact about the owner to their memory file') plus an enumeration of the kinds of facts it accepts, which pins down scope precisely. It does not name a sibling to route against (e.g. brain_capture vs brain_write), so differentiation is implied rather than stated.

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 conditions for each mode of use: pass `replaces` when superseding an earlier fact, use subject/attribute for single-valued facts, `valid_until` for temporary facts, `valid_from` for backdating. It also gives an explicit exclusion ('Do not store session trivia') and explains the force override 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?

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 already declare destructiveHint and idempotentHint, so the safety bar is lower; the description still adds real context beyond them: the path-root restriction, that overwrite replaces an existing note, and the non-obvious return behavior (existing notes named without linking, with no output schema to convey it). It doesn't spell out what is lost on overwrite (frontmatter/body replacement), which is the one gap.

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 create/replace action and followed by usage, differentiation, and return behavior in four tight sentences. Every sentence carries information; the hub sentence is slightly dense but not wasteful.

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-parameter mutation tool with no output schema, the description covers the path constraint, overwrite semantics, type/hub behavior, and partial return information. Remaining details (order, topics, summary) are handled by high schema coverage, 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?

Schema coverage is 89%, so the baseline is 3, but the description adds meaning the schema lacks: the 'hub' type's semantics (groups notes whose frontmatter project matches its title) and the overwrite replace behavior. It says less about order, topics, and summary, but those are documented in 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?

States the specific verb and resource ('Create a note at a path... or replace one with overwrite=true') and scopes it to Notes/ or Captures/. It explicitly distinguishes itself from brain_capture by noting the caller sets the type, so an agent can choose between the two without opening the 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?

Gives positive usage ('use it for hubs, guides and runbooks maintained by hand'), names the alternative it supersedes (brain_capture) with the differentiating condition, and states an exclusion ('Generated notes elsewhere in the vault cannot be written'). When/when-not/alternative are all present.

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