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

Annotations only carry the generic safety flags (readOnly=false, destructive=false, idempotent=false, openWorld=false), and the description adds far richer behavior: approval semantics for publishing, the rule never to paste conversation text, the requirement to report exactly what went where, the NAME_REQUIRED and UNAVAILABLE recovery paths, and the anti-hallucination instruction to never fill in a missing hub state from memory. This is substantive context an agent could not infer from the structured fields.

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 purpose and the brain_folder exclusion are front-loaded before any action detail, and the action bullets are dense but each maps to a real operation. It is nonetheless a long wall of prose with some redundancy in the opening paragraph ('Nothing personal is shared... apart from the user's personal memory'), and the hub-placement and membership bullets are tangled together.

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 explained, and the description instead covers result handling (NAME_REQUIRED prompt-and-retry, UNAVAILABLE fallback). It documents almost every action's required inputs and the key policy constraints. The remaining gaps — the unmentioned source_refs parameter and the unexplained type enum meanings — are minor but real for a tool this complex.

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% across 18 parameters, so the description carries the full explanatory burden, and it largely delivers: it binds parameters to actions (publish + type + summary + details, attach + path, invite + member + role + projects, retract + checkpoint_id, set_name + name) and explains fields like details, context, supersedes, workspace and hub. It earns a 4 rather than 5 because 'source_refs' is never mentioned by name, and the nested context keys (addresses, evidence) are described without clarifying their placement 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?

The opening line names a specific resource and scope — 'Team project brains: decisions and progress shared with teammates' AIs, per project' — and immediately draws the boundary against the sibling brain_folder ('Not for the user's own memory or their other PCs'). The action list further pins down what the tool does per operation. It stops short of distinguishing itself from the remaining siblings (brain_recall, brain_remember, brain_context, brain_forget), though the 'user's own memory' exclusion implicitly covers 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?

It states when to publish ('only when the user asks', with literal trigger phrases), that the request itself is the approval so the agent should not re-ask, and the one exclusion (ask only if the project is ambiguous). It also routes adjacent needs elsewhere — files go to Slack/drives/GitHub via those tools, personal memory goes to brain_folder — which is explicit when-not/alternatives 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 annotations (readOnly/idempotent/non-destructive/openWorld=false), it discloses ordering semantics (recent makes results newest-first instead of word-overlap ranked), the size cap on output, and that each result carries a date and source. It also discloses that around re-ranks without dropping anything, a non-obvious behavioral trait.

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 sentence and each paragraph maps to a parameter decision, so most sentences earn their place. It is nonetheless long and drifts into loosely ordered asides (Korean examples, an empirical measurement) that could be tightened.

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 needn't be described, and usage guidance is thorough. However, for an 11-parameter tool with zero schema descriptions, six parameters (as_of, limit, policy, scopes, max_chars, knowledge_cutoff) are silently undocumented, leaving an agent guessing on budget and scope control.

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% across 11 parameters, so the description must carry the load. It gives rich semantics for recent, since, about_assistant and around (with format examples like '2026-09-01..2026-09-30'), but as_of, limit, policy, scopes, max_chars and knowledge_cutoff are left entirely unexplained in both schema and description.

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: retrieve a bounded text packet of past memories to answer from, and names its scope as the default memory call. It explicitly contrasts itself with brain_recall for 'structured rows, ids or one thing's history', so an agent can disambiguate from the closest sibling 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?

Explicitly says to use it 'whenever a request may depend on earlier conversations, facts, preferences, decisions or work', then gives condition-by-condition guidance for recent/since/about_assistant/around with quoted example utterances. It even names a when-NOT case for around ('do not set it for when something HAPPENED'), with measured evidence.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), it discloses real side effects: `path="share"` opens Postgres to the LAN/Tailscale, may trigger a one-time firewall prompt, and returns a connection_code containing a password with an explicit warning not to post it publicly. It also flags that export files contain the entire memory (secrets masked) and that share_existing uploads to the sync folder.

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 and the team exclusion are front-loaded, then usage follows mode-by-mode, which is the right order. It is still long and repetitively framed around quoted user utterances, but almost every sentence adds a distinct operational rule rather than restating the schema.

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 five-parameter tool with no schema descriptions but a present output schema, the description covers every parameter, the side effects of each mode, the privacy caveats, and the sibling boundary. Nothing an agent needs to invoke 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 0%, so the description carries the full burden and does so: `path` is defined across its value space (a named sync folder, `"local"` for on-PC Postgres, `"share"`, or a pasted gmt1./gm1. code), and reindex, export_to, import_from, and share_existing each get a concrete meaning, trigger, and effect.

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 opening states the resource (the user's personal memory folder and which PCs share it), and the second paragraph explicitly excludes the sibling case: 'Not for teams: project brains shared with teammates are brain_checkpoint.' However, the tool is an omnibus of modes (folder config, share, code redemption, export/import, reindex) that the name 'brain_folder' does not signal, so an agent must read the whole description to learn the full scope.

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?

Nearly every mode is gated on an explicit trigger: call with `path` when the user names a folder, use `path="share"` when the user asks other PCs to connect, use `path=<the code>` when any Graph-MIND code is pasted, and 'Set it only when the user has explicitly agreed' for share_existing. It also names the alternative (brain_checkpoint) and pre-empts a question ('never ask the user which kind it is').

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 mark this destructive/non-read-only/idempotent, and the description goes well beyond them by specifying deletion scope (this PC, search indexes, shared memory, other PCs), that the deletion exchange itself is not saved, and that app chat history is separate. It does not, however, describe failure behavior or what happens if ids match nothing.

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?

Longer than most definitions, but front-loaded with the purpose and each block (examples, two-call protocol, deletion scope) earns its place. Slightly more verbose than strictly necessary, but no filler sentences.

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 is unnecessary; the description instead supplies everything an agent needs to safely drive a destructive, two-step deletion — trigger conditions, privacy constraints, and blast radius. Nothing material 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 0%, so the description carries the load, and it does: query must use general words and never repeat a secret the user typed; ids must be exactly the user-selected ones from the prior call. The mutual exclusivity/two-phase usage of the two optional params is implied clearly though not spelled out formally.

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 ('Delete what the user wants gone from memory') and grounds it in three concrete example utterances spanning languages. An agent can immediately distinguish this from brain_remember/brain_recall.

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 an explicit two-call protocol: first query with general words, then a second call with the selected ids 'and only those.' It also states the required interaction pattern (show masked previews, ask the user which to delete, never quote the original).

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, non-destructive), and the description adds genuinely new behavioral context: result ordering, how replaced entries are marked, how the current one is identified, similarity-vs-history recall behavior, and default list order ('busiest first'). This is exactly the value-beyond-annotations the dimension rewards.

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-loads the core distinction, then uses focused paragraphs per parameter cluster. Slightly long, and the cross-reference to brain_context for shared params offloads meaning elsewhere, but every sentence carries signal.

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-format explanation is not required, and the description still characterizes the shape ('structured rows, not a ready context'). Given 10 params at 0% coverage, a few params (as_of, scopes, knowledge_cutoff) remain unexplained, but the recall-behavior model is otherwise well conveyed.

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% across 10 params, so the description must carry the burden and largely does: it explains entity semantics (every memory about one thing, oldest first, replaced entries marked), the no-query/no-entity default behavior, and defers recent/since/about_assistant/around to brain_context. It does not cover as_of, limit, scopes, or knowledge_cutoff, leaving several params undocumented anywhere.

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?

Opens with a precise definition of what the tool returns ('raw lookup: matching memories and turns as structured rows, not a ready context') and explicitly contrasts it with the sibling brain_context. An agent can distinguish it from every named sibling 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?

Explicitly states when to use brain_context (answering questions from the past) versus brain_recall (inspecting/listing ids and fields, one thing's history, store overview), and names concrete downstream uses like before brain_forget or supersedes_memory_id. No inference required.

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 write/non-idempotent/non-destructive; the description adds the substantive mutation semantics — a later value with the same `about`+`attribute` replaces the earlier one, recall surfaces both old and new, and the attribute name must be stable ('last_trip', not 'last_trip_paris') or replacement silently fails. It also discloses the user-facing contract ('Save silently', never announce the save). This is exactly the non-obvious behavior an agent could not infer from the structured fields, and it is consistent with destructiveHint=false.

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 organized into short paragraphs, each carrying distinct content (what to save, how changeable facts work, when to trigger, how to behave). It is long for a single tool and repeats the silent-save instruction twice, but the length is largely justified by the 20-parameter surface and supersession subtlety.

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?

Annotations are present and an output schema exists, so return values need no explanation and the behavioral half is well covered. However, for a 20-parameter tool the description leaves the majority of parameters unexplained (notably `scope`, `retention`, `title`, `tags`), leaving an agent guessing on invocation details that materially affect where and how the memory lands.

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% across 20 parameters, so the description carries the full burden and only partially meets it: it meaningfully explains `content`, `about`, `attribute`, `entities`, `effective_at`, `supersedes_memory_id` and `memory_type`. Critical parameters such as `scope`, `title`, `tags`, `retention`, `memory_class`, `modality` and the object-typed `attributes` are left entirely undefined, and `attributes` vs `attribute` is a real confusion hazard the text does not disambiguate.

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 and resource ('Save what the user just told you, in their own words') and makes the scope concrete by contrasting with recall's behavior ('recall shows both: the value now and what it was before'). It never names a sibling to route away from, so it is clear but not sibling-differentiating in the way a 5 requires.

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 unusually explicit: 'Call this proactively,' 'Use it the moment the user mentions anything about their life, work, plans...', plus the exclusion-by-behavior 'Do not ask whether to save it and do not wait to be told "remember this".' It lacks any named alternative or 'do not use this when' exclusion (e.g. vs brain_checkpoint or brain_forget), which keeps it short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the 'empty unless a code folder is being watched (automatic-capture.json, code_workspaces)' caveat is a non-obvious precondition an agent must know to interpret empty results correctly. Return format is left to the output 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?

Front-loads the core purpose, then follows with examples and a caveat. Three sentences with little waste. Minor redundancy between the filter list and the example questions, but overall tight and well-ordered.

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. The description supplies the essential usage framing and the empty-results precondition, making it largely complete for a read-only query tool. The only shortfall is the undocumented limit/max_diff_chars parameters.

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 param burden. It compensates well for six of eight params by naming the filter concepts (project, file, symbol, kind) and explicitly calling out happened_from/happened_to with ISO format. However, limit and max_diff_chars are never mentioned, leaving two parameters unexplained.

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: 'Code changes the capture service recorded, with diff excerpts,' making clear it returns recorded code changes rather than memory items. This cleanly distinguishes it from every sibling (brain_remember, brain_recall, etc.), all of which are memory tools. An agent can identify its domain 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?

Provides concrete example questions ('what did I change in auth.py last week?', 'when did the parser change?') that map directly to use cases, plus a critical precondition: results are empty unless a code folder is being watched. It doesn't explicitly name an alternative sibling, but the sibling set is a different domain, so routing guidance is effectively implicit.

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