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

Goes well beyond the annotations: describes permission model (owner vs publisher for `retract`, owner for `remove_member`), that several actions return a `command` the user must run in a terminal, error protocols (UNAVAILABLE = hub unreachable, never fill in from memory; NAME_REQUIRED = ask then retry), and an integrity rule against overstating git stage. Minor ambiguity remains around `destructiveHint:false` given `retract` and `remove_member`, and nothing explains the read actions' cost or pagination.

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 approval rule are front-loaded, which is right, but the body is a dense wall of prose with irregular indentation rather than scannable structure; for a 15-action dispatcher some length is justified, yet several clauses (hub topology, invite-command detail) could be tightened or grouped per action.

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

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

Given 15 actions, 18 parameters, an output schema and partial annotations, the description is nearly complete: it covers approval semantics, error states, permission boundaries and where projects are hosted. What is left thin is the return shape of the multi-step flows (invite/host command sequences) and how the actions relate when chained.

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 6% (one parameter documented), so the description must carry the load and largely does: workspace, project, path, type, summary, details, supersedes, checkpoint_id, member, role, projects, hub, code, name and instructions are each tied to specific actions via `action` + param notation, and `context`'s untyped object is expanded into named sub-fields. Some overlap is left unresolved, notably `source_refs` versus `context.evidence`, and the action-parameter pairings remain inferential.

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 concrete verb-and-resource statement: project brains holding "decisions and progress shared with teammates' AIs, per project," and explicitly excludes the sibling: "Not for the user's own memory or their other PCs: that is brain_folder." The only weakness is that the tool multiplexes 15 actions, so a single purpose line cannot cover them all — but the core identity is unambiguous.

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

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

Gives explicit when-to-use and when-not-to-act rules: "Publish only when the user asks ('공유해', ...): that request is the approval, so do not ask again; ask only if the project is ambiguous," plus `create_project` "only when the user names one," and timeline usage keyed to a concrete user question ("누가 어디까지 했어?"). It also routes work that does not belong here to other tools (files stay in Slack/drives/GitHub, invite/host return terminal commands).

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 needs no restating. The description adds real behavioral detail beyond that: results come newest-first vs. by word overlap, `around` ranks but drops nothing, `about_assistant` searches by meaning, and each item carries date and source. However, it leaves the size-cap interaction (`max_chars`) and the `policy=auto` skip behavior to the schema, so it is strong but 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?

Front-loaded well: the core purpose and the sibling routing come first. But the body is long and uneven, padding with multilingual example strings and a measured ablation statistic (2 of 11 questions) that informs implementation choices rather than the calling decision, so some sentences do not earn their space.

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

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

The description covers trigger conditions, return shape, the follow-up path (open an item via brain_recall when it is cut off), and the key false-negative failure mode. An output schema exists, so return structure need not be restated in full. Minor gap: the `policy`, `limit`, and `scopes` knobs and their interaction are not addressed in prose.

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 64%, and the description compensates for the four undocumented flags: `recent`, `since`, `about_assistant`, and `around` each get concrete trigger phrases and, for `around`, the expected value syntax ('2026-09-01..2026-09-30'). `as_of`, `limit`, `scopes`, `max_chars`, and `knowledge_cutoff` are left entirely to 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?

Opens with a concrete verb and resource ('answer from the user's past: one bounded text packet'), names the return field (`context`), and positions itself as 'the default memory call.' It explicitly contrasts with brain_recall for structured rows, ids, or one thing's history, so the agent can discriminate it from its 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?

Gives the selection rule (use whenever a request may depend on earlier conversations, facts, preferences, decisions, work), names the alternative tool and its condition (brain_recall for structured rows/ids/history), and adds a case-specific negative instruction: do not set `around` for when something happened, with a stated reason. Nearly every branch is decided for the agent.

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 the safety profile (non-read-only, non-destructive, idempotent, closed-world); the description adds substantial context beyond that: config changes are returned as a `command` for the user to run in a terminal (a deliberate prompt-injection defense), firewall approval may be needed, connection codes contain a password, export files hold the entire memory with secrets masked. No behavior contradicts the annotations — writes like reindex/export justify readOnlyHint=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?

Purpose and the not-for-teams exclusion are front-loaded, and nearly every paragraph maps to a distinct mode, so little is filler. It is nevertheless very long for one tool, with some repeated emphasis ("Only when the user asks" / "Set it only when the user has explicitly agreed") 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?

An output schema exists, so return values need not be enumerated, yet the description still flags the key return artifacts (`command`, `connection_code`) and what they contain. For a six-parameter, multi-mode tool with mutation and sharing side effects, nothing an agent needs in order 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 0%, so the description carries the full burden, and it does: path (folder / "local" / "share" / a pasted code), share_existing, reindex, export_to, import_from, and project's scoping effect on export_to are all explained with intent and safety conditions. The only minor gap is whether `project` also constrains import_from.

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 specific verb-and-resource framing: where the user's personal memory lives and which PCs share it. It explicitly names the sibling it is not for ("Not for teams: project brains shared with teammates are brain_checkpoint"), so an agent can route correctly 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?

It enumerates the selection conditions for each mode: bare call to report current state, path=<folder> when the user names a folder, path="local", path="share" for other PCs, path=<code> for pasted codes, share_existing only on explicit agreement, reindex for a backlog. Alternatives and exclusions are stated rather than inferred.

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 already establish the read-only, idempotent, non-destructive profile, and the description layers on real behavior: `source` returns following turns in full and in order with two preceding turns included, `entity` returns oldest-first with replaced entries marked and the current one picked out. It doesn't state what happens on an empty match or how rows are shaped, but the remaining gaps are minor given annotation coverage.

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 one-line summary, then organizes remaining text by parameter with backticked anchors, so it is scannable despite length. Some phrasing ("when it is cut off, or the answer is likely in the rest of that exchange") is more verbose than needed, but nothing is 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?

An output schema exists, so return shape needn't be described, and the description covers the modes an agent must choose between plus ordering semantics for the two most important ones. The unanswered parameters and the reliance on brain_context's description for shared parameters keep it short of complete.

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?

With only 36% schema coverage and 11 parameters, the description carries heavy burden. It gives rich semantics for `source`, `entity` and `limit` (in the source context), but `query`, `as_of`, `knowledge_cutoff` and `about_assistant` are never explained, and four parameters are deferred wholesale via "mean the same as in brain_context" — a cross-reference that requires the sibling's description to be in context.

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 characterization ("Raw lookup: the matching memories and turns as structured rows, not a ready context") that names both the verb and the resource, and immediately contrasts it with brain_context's packet output. An agent can distinguish it from every 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?

Explicit routing guidance: "To answer the user's question from their past, use brain_context instead" versus "Use brain_recall to inspect or list" with three concrete inspection cases (ids before brain_forget, one thing's history, store inventory). It also tells exactly when to escalate from a brain_context packet via `source`.

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 annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false): it discloses that a later value with the same `about`/`attribute` REPLACES the earlier one, that recall surfaces both current and prior values, that saving is silent with no user-facing confirmation, and that decisions should be stored with a reason. These are exactly the non-obvious behaviors an agent would otherwise get wrong.

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 directive, then logically grouped into identity/supersession, triggering, and silence rules. It is long for a tool description and repeats the 'use the same attribute names' point twice, but nearly every sentence carries operational guidance rather than 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?

An output schema exists, so return values need no explanation, and the description covers the calling contract, supersession model and the required `content` field. The main gap is the absence of any guidance on `scope` (project vs global) and on when the optional metadata params matter, which for a 20-param tool is a real but secondary omission.

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 60%, so the description must carry weight, and it does for the semantically tricky params: it explains `about`/`attribute` pairing, the snake_case naming convention with a failure example ('last_trip', not 'last_trip_paris'), `content` as verbatim user text, plus `entities`, `effective_at`, `supersedes_memory_id` and `memory_type`. It leaves roughly a third of the 20 params (scope, tags, modality, retention, confidence, importance, memory_class, related_memory_ids) undocumented, though the schema marks most of those 'optional; usually left empty'.

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 specific verb+resource+scope: 'Save what the user just told you, in their own words,' which immediately separates it from brain_recall, brain_forget and brain_context. The proactive-call directive further pins down its role in the sibling set.

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

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

Explicit when-to-use with concrete trigger examples ('I had kimchi fried rice today', 'my dog is called Kongi'), explicit when-not ('do not wait to be told remember this'), and an explicit anti-pattern ('do not ask whether to save it'). No alternative tool is named, but the routing conditions are unambiguous.

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 and closed-world, so the safety profile is covered. The description adds real context beyond that: results carry diff excerpts, results are silently empty without a watched code folder, and it names the config artifacts (automatic-capture.json, code_workspaces) that control that 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?

Front-loads what the tool returns, then the filter axes, then the caveat about watched folders. Dense but every clause carries information; slightly long for a single paragraph, with the caveat tucked at the end where it is easiest to miss.

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

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

With an output schema present, the description need not explain return fields, and it correctly focuses on filtering, diff excerpting, and the empty-result precondition. Nothing essential for a correct call is missing, though the default limit/max_diff_chars tradeoffs are only in the schema.

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 63%; the description supplies meaning for the undocumented parameters by naming the filter set (project, happened_from/happened_to as ISO, file, symbol, kind) and tying them to example queries. limit and max_diff_chars are left to their schema text, which already documents them.

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: code changes recorded by the capture service, with diff excerpts, plus the filter axes (project, time range, file, symbol, kind). This is clearly distinct from the brain_* sibling tools, so an agent can select it 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?

Gives two concrete example questions ('what did I change in auth.py last week?', 'when did the parser change?') that map directly onto the filters, and states the precondition that results are empty unless a code folder is being watched. It does not name any alternative tool to prefer or avoid, but no sibling overlaps this domain.

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