Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@thebrain-mcp search my brain for thoughts about RAG"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for TheBrain 15, built on its local API.
It gives an agent semantic operations over your brain: search by meaning, read a neighbourhood of the graph, and write a decomposed piece of material into the brain as a whole connected structure. It is not a mirror of the API — 17 tools instead of 48 endpoints.
The point is not "save this text". The point is that when you hand an agent an article, it reads it, breaks it into meanings, works out where each one belongs in the graph you already have, what to link it to, and what each note should say.
Published on npm as
thebrain-mcp-server— npm considers the shorter name too close to an unrelated existing package. The installed command is stillthebrain-mcp.
TheBrain 15 running, with the local API enabled
Node.js 22 or newer
An API key: Settings → User → Local API Key
Related MCP server: thebrain-mcp-server
claude mcp add thebrain -e THEBRAIN_API_KEY=your-key -- npx -y thebrain-mcp-server{
"mcpServers": {
"thebrain": {
"command": "npx",
"args": ["-y", "thebrain-mcp-server"],
"env": { "THEBRAIN_API_KEY": "your-key" }
}
}
}TheBrain's own search matches prefixes: OT finds OTGP, while a synonym or a
typo finds nothing. To search by meaning, the server builds a local vector index.
The embeddings package is not part of the install: it weighs around 380 MB, plus 113 MB for the model itself on first run. Install it separately, and only if you want it:
npm install -g @huggingface/transformersThen, from your client: brain_index with action: "rebuild". Indexing a
10,000-thought brain takes about a minute; later runs only recompute what changed.
The server works without the package. brain_search falls back to a fan-out
of prefix queries over the synonyms the agent supplies, and says plainly that
recall is lower.
Everything is local: neither your brain's contents nor your queries are sent anywhere.
Variable | Default | Purpose |
| — | Required |
|
| Local API address |
|
| Where indexes are stored |
|
| Allow deleting thoughts |
|
| Embedding model |
|
| Weight precision |
|
| API request timeout |
Changing the model or the precision makes an existing index unusable — the server will say so and ask for a rebuild.
Reading
Tool | What it does |
| Brains, which one is open, whether the index is ready |
| A thought, its graph and its note in one call |
| Search by meaning |
| Walk the graph several hops out |
| The brain's vocabulary |
| What changed, in plain language |
| Index status, build and refresh |
Writing
Tool | What it does |
| A thought together with its note, type and tags |
| Name, label, type, colours |
| Replace or extend a note |
| Connect two thoughts, with a label |
| Attach and detach tags |
| Attach a link, without duplicates |
| Open a thought on the user's screen |
| Delete, with human confirmation |
| Write a whole structure in one call |
brain_ingestThe main tool for filling a brain. The agent breaks material into thoughts, wires them together through temporary identifiers, and the whole thing lands in one call:
{
"brainId": "…",
"thoughts": [
{ "tempId": "art", "name": "Article on RAG", "parent": "<uuid of an existing thought>" },
{ "tempId": "embed", "name": "Embeddings", "parent": "art", "note": "…" },
{ "tempId": "store", "name": "Vector store", "parent": "art" }
],
"links": [
{ "from": "embed", "to": "store", "name": "is written into" }
]
}The order of thoughts in the input does not matter — dependencies resolve themselves. Running the same plan twice duplicates nothing. Bad plans (a cycle, a reference to nowhere) are rejected before the first write.
The server provides the mechanism — deterministic operations. The methodology (how finely to split meanings, when to attach to something that already exists, what belongs in a note) lives separately, in Claude Code skills. They are plain markdown files, so you can adjust them to your own way of working without rebuilding the server.
Skill | When it fires |
| "put this article in my brain", "break this down and record it" |
| "what do I know about X", "have we discussed this already?" |
| "clean up my brain", "find duplicates" |
| "what did I add this week", "what have I been working on" |
Install them as symlinks, so edits in the repository take effect immediately:
mkdir -p ~/.claude/skills
for d in skills/*/; do
ln -sfn "$PWD/$d" ~/.claude/skills/"$(basename "$d")"
doneOr copy them, if you do not want the link to the repository. For a single
project, use .claude/skills in its root instead of ~/.claude/skills.
Skills are picked up when a session starts — an already running session needs a
restart (claude --continue keeps the conversation).
Off by default. Even with THEBRAIN_ALLOW_DESTRUCTIVE=1 it requires human
consent: through a confirmation form if the client supports one, otherwise
through a second call with an explicit flag. The agent cannot make this decision
for you.
npm install
npm test # unit tests, no live TheBrain needed
npm run buildContract tests against a live API:
THEBRAIN_API_KEY=… npm test # read-only
THEBRAIN_API_KEY=… THEBRAIN_TEST_BRAIN_ID=<uuid> npm test # + writesThe write tests require a separate, throwaway brain and refuse to touch any brain with more than 500 thoughts.
ARCHITECTURE.md — how the server is built and why: layer
boundaries, the mechanism/policy split, error philosophy, the semantic layer,
and the measurements behind each decision.
docs/api-map.md — the local API's behaviour, including the
undocumented parts, verified against a live instance.
docs/stack-evaluation.md — why TypeScript, with
numbers.
CONTRIBUTING.md — how to work on this.
MIT
Opens a thought in the user's TheBrain app on screen. Call it to show the person a result — for instance a structure you have just created, so they can see it in the graph.
| Name | Required | Description | Default |
|---|---|---|---|
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. | |
| thoughtId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly conveys a display action ('opens ... on screen') and implies no side effects via 'show the person a result.' It doesn't discuss edge cases, but for a simple UI-activation tool this is adequate.
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, front-loaded with the action, and every word earns its place. No redundancy or 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 simple tool with no output schema, the description covers what it does, when to use it, and gives a concrete example. It doesn't discuss errors or prerequisites, but those are likely unnecessary for a basic UI-opening action.
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 description adds no parameter information. The schema covers brainId with a helpful instruction, but thoughtId is completely undocumented. With 50% schema description coverage, the description should have compensated by explaining thoughtId, but it doesn't.
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 action with a clear resource: 'Opens a thought in the user's TheBrain app on screen.' It also provides a concrete use case ('show the person a result') that distinguishes it from sibling tools like brain_get_thought or brain_create_thought.
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 provides explicit context on when to call the tool: 'Call it to show the person a result — for instance a structure you have just created.' While it doesn't explicitly name alternatives or exclusions, the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Appends text to the end of a note without erasing anything. The main way to accumulate material on a thought. If no note exists yet, one is created.
| Name | Required | Description | Default |
|---|---|---|---|
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. | |
| markdown | Yes | What to append, in Markdown. | |
| thoughtId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the full burden. It discloses non-destructive behavior and auto-creation of a note when none exists. This is sufficient for a simple append operation, though it doesn't mention return values or side effects beyond creation.
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, front-loaded with the core action and outcome. Every phrase adds value; 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 3-param, no-output-schema tool, the description covers the key behavior, creation semantics, and non-destructiveness. It could mention when not to use (if replacing note) or return behavior, but 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 provides descriptions for brainId and markdown, but thoughtId is undocumented. The description adds general context about accumulating material but not parameter-specific semantics. With 67% coverage, it's adequate but not exceptional.
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?
Clearly states the action (appends text) and result (to end of a note without erasing anything), and positions it as the main way to accumulate material. Distinguishes from likely sibling brain_set_note by emphasizing non-destructive accumulation.
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 identifies when this tool is the main choice ('main way to accumulate material on a thought'), and implies alternatives by stressing that it does not erase. It doesn't name specific alternatives like brain_set_note, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attaches a link to a thought. Checks first whether the same URL is already attached and avoids duplicates. Leave name empty to take the title from the page.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Page address. | |
| name | No | Attachment name; empty means use the page title. | |
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. | |
| thoughtId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses two useful behaviors beyond the name: duplicate-URL avoidance and the name-empty fallback to page title. However, since there are no annotations, it does not cover mutation side effects, permissions, error behavior, or return value, leaving a transparency gap for a write operation.
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 two sentences, front-loaded with the main action, and every clause adds useful information. There is no redundancy or 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?
Core behavior and the duplicate check are explained, but the description does not mention the return value, what happens on duplicate (reject vs. silently skip), or any prerequisites like the thought/brain existing. With no output schema, these missing operational details reduce completeness.
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 75%, covering url, name, and brainId with meaningful descriptions. The tool description adds no new parameter meaning beyond what the schema already states (e.g., name empty behavior is already in the schema), and thoughtId remains 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?
The description uses a specific verb ('Attaches') and resource ('a link to a thought'), making the action clear. It also adds scope by mentioning duplicate-avoidance, which distinguishes it somewhat from generic linking tools, though it does not explicitly contrast with sibling tools like brain_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives such as brain_link or brain_ingest. It provides a behavioral note about duplicates and a naming hint, but no when-to-use or when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a thought and sets its note, type and tags in the same call. Call it when adding something new. Always supply parentId — a thought with no links gets lost in the graph. Search first: a suitable thought may already exist, in which case extending it is the better move.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Thought title. Short and to the point. | |
| note | No | Note body in Markdown. | |
| label | No | Short caption under the title. | |
| tagIds | No | Tag identifiers from brain_list_types_and_tags. | |
| typeId | No | Type identifier from brain_list_types_and_tags. | |
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. | |
| parentId | No | What to attach it to. Without this the thought is left orphaned. | |
| relation | No | How the new thought relates to that one. Child by default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a critical behavioral consequence: 'Always supply parentId — a thought with no links gets lost in the graph.' This warns about orphaned thoughts, which is beyond the schema's 'Without this the thought is left orphaned.' It does not mention return values or failure modes, but the core mutation behavior is clear.
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 four short sentences, each earning its place: purpose, when-to-use, critical warning, and pre-check advice. It is front-loaded with the verb and resource, with no redundant wording.
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 tool with 8 parameters, no annotations, and no output schema, the description is quite complete. It covers when to use, the essential parentId caveat, and the search-first behavior. It does not explain return values, but the schema is rich enough that this is not a significant gap.
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 baseline is 3. The description adds extra semantic value by elevating parentId to 'Always supply' even though schema marks it not required, and by contextualizing the search-first workflow for tagIds/typeId. This goes beyond the schema descriptions.
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 clearly states the tool's function: 'Creates a thought and sets its note, type and tags in the same call.' It distinguishes from siblings like brain_update_thought (which modifies existing thoughts) and brain_set_note (which only sets a note) by emphasizing the 'same call' combined operation.
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 provides explicit guidance: 'Call it when adding something new' and 'Search first: a suitable thought may already exist, in which case extending it is the better move.' This tells the agent when to use this tool versus alternatives like updating an existing thought, and implies using brain_search first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently deletes a thought along with its note and links. There is no undo. Requires human confirmation. Do not call it to tidy up on your own initiative — only when the user explicitly asked for a deletion.
| Name | Required | Description | Default |
|---|---|---|---|
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. | |
| confirm | No | Set to true only after a human has confirmed the deletion. Do not decide this on their behalf. | |
| thoughtId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden: it discloses permanence, no undo, cascading deletion of note and links, and the need for human confirmation. This is strong behavioral transparency for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences front-load the destructive action and include all critical caveats—no undo, human confirmation, and usage restriction—with zero 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 destructive delete tool with no output schema, the description covers scope, irreversibility, confirmation requirement, and appropriate invocation context. It is complete for safe and correct use.
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 schema already describes brainId and confirm well. The description does not add parameter-specific meaning, and thoughtId remains undocumented, so 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?
The description clearly states 'Permanently deletes a thought along with its note and links,' using a specific verb and resource. This distinguishes it from sibling tools like brain_update_thought or brain_get_thought.
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 'Do not call it to tidy up on your own initiative — only when the user explicitly asked for a deletion,' giving clear when-to-use and when-not-to-use guidance. It also underscores required human confirmation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A thought in full: note, parents, children, jumps, tags, type and attachments in one call. The main way to understand a thought's context. Call it when you need to know what a thought is about and how it connects, before changing or extending it.
| Name | Required | Description | Default |
|---|---|---|---|
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. | |
| thoughtId | Yes | Thought identifier. | |
| includeSiblings | No | Include siblings under the same parent. Off by default — there can be many. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It indirectly signals non-destructive behavior by framing the call as a pre-change understanding step and adds a specific behavioral note about includeSiblings being off by default due to potentially large result sets. It does not explicitly state 'read-only' or error handling, but the key context is present.
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 two sentences long, front-loading the core function and then providing usage context. Every word earns its place with no fluff or repetition.
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 there is no output schema, the description effectively enumerates the return fields (note, parents, children, jumps, tags, type, attachments), which covers the essential return shape. It also hints at potential large sibling sets. It lacks error-case details but is otherwise complete for a 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 100%, and each parameter has a descriptive role, including the helpful 'Take it from brain_list — never guess it' for brainId. The description adds no extra parameter detail beyond the schema, so the baseline of 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?
The description clearly states the tool retrieves a full thought including note, parents, children, jumps, tags, type, and attachments in a single call. It also positions itself as the primary means to understand a thought's context, distinguishing it from sibling tools like brain_search or brain_traverse.
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 provides clear guidance on when to use the tool: 'Call it when you need to know what a thought is about and how it connects, before changing or extending it.' This implies a read-before-write pattern but does not explicitly name alternative tools or exclusion criteria, so it stops short of full usage differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manages the semantic index: status, build, refresh. Call with action=status when brain_search complains the index is missing; with action=rebuild to build it for the first time or after changing the model; with action=sync to pull in changes (fast, new material only). The first build on a large brain takes minutes.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | status — look only; rebuild — build from scratch; sync — catch up. | |
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavior itself. It does mention a performance caveat ('The first build on a large brain takes minutes'), implies that rebuild is a full rebuild and sync is incremental, and indicates status is a read-only check. However, it does not explicitly state that rebuild destroys the existing index or that actions may have side effects (e.g., resource usage). The transparency is good 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?
The description is three concise sentences, front-loaded with the tool's purpose and then giving actionable usage guidance. There is no filler; every sentence earns its place. It is appropriately sized for a two-parameter 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 tool with two parameters, an enum, and no output schema, the description covers the key contexts: when to use each action, what they do, and timing expectations. It lacks mention of return values, but that is not critical for a management tool. The description is nearly complete for an agent to select and 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%: both action and brainId are already described in the schema (action enum values and 'never guess it' for brainId). The description adds context for when to use each action but does not provide new parameter-level semantics beyond what the schema already offers. Baseline 3 is appropriate here since the schema carries the parameter burden.
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 clearly states the tool's function: 'Manages the semantic index: status, build, refresh.' It uses a specific verb ('manages') and resource ('semantic index'), and immediately lists the three supported actions, distinguishing it from any sibling tool that does not manage the index. This is a precise, high-clarity purpose statement.
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 provides explicit usage scenarios for each action: 'Call with action=status when brain_search complains the index is missing; with action=rebuild to build it for the first time or after changing the model; with action=sync to pull in changes (fast, new material only).' It also warns about build duration on large brains. This is exemplary when-to-use guidance, though it doesn't contrast with alternative tools since none exist for this specific task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes a whole structure of thoughts, links, notes and tags in a single call. Call it once you have decomposed some material (an article, a document, a discussion) into several connected thoughts — creating them one by one at that volume is slow and breaks halfway. Thoughts reference each other by tempId, arbitrary labels you invent yourself; the server substitutes real identifiers. A parent may be either a tempId from this batch or the UUID of an existing thought, which is how a new branch grafts onto what the brain already holds. Search with brain_search first: some of the thoughts may already exist, and linking to them beats creating duplicates.
| Name | Required | Description | Default |
|---|---|---|---|
| links | No | Extra links on top of the hierarchy. These are what turn a set of thoughts into a graph — use them freely and label them. | |
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. | |
| thoughts | Yes | The batch's thoughts. Order does not matter; dependencies resolve themselves. | |
| deduplicate | No | Skip creating a thought when the same parent already has a child with that name. On by default, which makes re-running a batch safe. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the tempId mechanism ('the server substitutes real identifiers'), how a parent can be a tempId or an existing UUID ('how a new branch grafts onto what the brain already holds'), and the schema adds deduplication-on-by-default (making re-runs safe), order independence, and maxItems 200. These are non-obvious behaviors an agent must know.
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 three tightly scoped paragraphs: the first states purpose and when to use, the second explains the tempId/parent mechanism, and the third offers search-first guidance. Every sentence earns its place—there is no repetition of schema details or filler. The front-loaded verb and resource make the tool's purpose immediately clear.
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 the tool's complexity (bulk write with tempIds, links, tags, deduplication, and no output schema), the description provides complete context for selection and invocation. It covers the purpose, prerequisites (brainId from brain_list is stated in the schema), the tempId workflow, the deduplication safety, and the recommended search-first sequence. No essential guidance 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%, but the description adds substantial meaning beyond the schema. For example, it defines tempId as 'arbitrary labels you invent yourself', explains the parent field's dual nature (tempId or existing UUID) in the context of grafting, and clarifies that links are 'extra links on top of the hierarchy.' The deduplicate parameter's default behavior is also described, enabling correct invocation choices.
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 opens with a specific verb and resource: 'Writes a whole structure of thoughts, links, notes and tags in a single call.' It clearly distinguishes itself from the one-by-one siblings by emphasizing batch scope and explicitly contrasts with creating thoughts individually ('creating them one by one at that volume is slow and breaks halfway'). This leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: 'Call it once you have decomposed some material...' and warns against using the alternative (one-by-one creation). It also provides a concrete 'search first' rule: 'Search with brain_search first: some of the thoughts may already exist, and linking to them beats creating duplicates.' This names the alternative tool and states the precondition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Links two thoughts. Call it when you spot a meaningful relationship between existing thoughts — links are what make a brain a graph rather than a list. Label the link via name: "motivates", "solved by", "contradicts".
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Link label: how exactly one relates to the other. | |
| toId | Yes | Target thought. | |
| fromId | Yes | Source thought. | |
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. | |
| relation | No | How the target relates to the source. Defaults to jump — a sideways link that leaves the hierarchy alone. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It fails to mention side effects, idempotency, permission requirements, or behavior on duplicate links. It is implied to be a mutating operation but does not explicitly state this or describe the response.
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 two sentences, front-loaded with the core action. The second sentence provides usage context and examples with no wasted words. Every sentence earns its place.
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 the tool's moderate complexity (5 params, 1 enum) and the absence of annotations and output schema, the description is fairly complete. It covers purpose, when to use, and example link labels, but it omits behavioral details like whether links are directed, return values, or prerequisites (e.g., existing thoughts). The schema covers all parameters, so the description adds sufficient context overall.
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?
Although schema coverage is 100% and the baseline is 3, the description adds value by giving concrete example labels for the 'name' parameter ('motivates', 'solved by', 'contradicts') and implicitly explains the from/to relationship via 'links two thoughts'. It does not explain the 'relation' enum, but the schema does.
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 opens with a specific verb and resource: 'Links two thoughts.' This clearly distinguishes it from sibling tools like brain_create_thought or brain_update_thought. It also explains the conceptual role of links in building a graph, further clarifying its unique purpose.
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 explicitly states when to call it: 'Call it when you spot a meaningful relationship between existing thoughts.' It provides clear invocation context, though it does not explicitly mention when not to use it or name alternative tools for creating thoughts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the user's brains and which one is currently open in the app. Call this first in any session: every other tool needs a brainId and guessing one is not allowed. Also shows whether the semantic index is ready.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the output content (brains, current open, semantic index readiness) and implies a read-only operation via verbs like 'lists' and 'shows.' It doesn't explicitly state side-effect-freeness, but the nature of the operation makes it clear.
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 two sentences, front-loaded with the core action, followed by usage guidance and an additional output detail. Every sentence earns its place; there is no filler or redundancy.
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 zero-parameter tool with no output schema, the description provides sufficient context: what it lists, why to call it first, and what additional state it reveals. It is complete for guiding an agent's initial action and integrates well with the sibling tool set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific information, but none is needed because the schema is empty and fully covered.
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: 'Lists the user's brains and which one is currently open in the app.' This clearly distinguishes it from siblings like brain_list_types_and_tags by focusing on the brains themselves and the open state.
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 explicitly says 'Call this first in any session' and explains why: 'every other tool needs a brainId and guessing one is not allowed.' This gives clear when-to-use guidance and positions the tool as the required entry point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The brain's vocabulary: which thought types and tags exist. Call it before creating thoughts so you use this brain's established conventions instead of inventing new ones.
| Name | Required | Description | Default |
|---|---|---|---|
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It implicitly indicates a read operation by saying 'list' and provides a rationale for use. While it doesn't spell out 'read-only' or side-effect-free behavior, the phrasing is clear enough to imply no mutation.
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, front-loaded with the purpose, and a clear directive. Every word earns its place; no fluff or redundancy.
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 it has a single well-documented parameter, no output schema, and no nested objects, the description fully covers what the tool does, when to use it, and why. It is complete for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description 'Take it from brain_list — never guess it' is already excellent. The tool description reinforces the meaning by referring to 'this brain,' adding context on how the brainId parameter selects the vocabulary. Slight extra value from the 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?
The description clearly states it lists thought types and tags ('which thought types and tags exist') and frames it as the brain's vocabulary. This is a specific verb+resource combination that distinguishes it from siblings like brain_create_thought or brain_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?
Explicitly instructs to call this tool 'before creating thoughts' to follow established conventions. This gives a clear usage context, but it does not mention alternatives or explicit when-not scenarios, so it falls just 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.
What changed in the brain over a period, in plain language. Call it for digests ("what did I add this week") and to understand what work was in progress before continuing it.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Defaults to 100. | |
| since | No | ISO timestamp to start from. Defaults to the last seven days. | |
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that output is in 'plain language' and focuses on changes over a period, which implies a read-only operation. However, it does not specify what types of changes are included (e.g., creations, edits, deletions) or the exact format of the response, leaving some ambiguity. This is adequate but not rich.
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 only two sentences long, with the purpose front-loaded in the first sentence and usage examples in the second. Every sentence earns its place, and there is no redundant or extraneous wording.
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 the tool's simplicity (3 parameters, no output schema), the description is fairly complete. It explains the tool's purpose and gives concrete usage scenarios. However, it does not detail the return structure or edge cases (e.g., empty results), so it's not a perfect 5, but it is well-suited for an agent to select and invoke the 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 description coverage is 100%, so the schema already fully documents all three parameters. The description adds no additional parameter-specific information beyond what the schema provides. Baseline for high coverage is 3, and the description does not improve on that.
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 clearly states the tool's function: 'What changed in the brain over a period, in plain language.' It uses a specific verb (changed) and resource (brain), and the mention of digests and work in progress differentiates it from sibling tools like search or get_thought. The purpose is immediately identifiable and distinguishes from alternatives.
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 explicit use cases: 'Call it for digests' and 'to understand what work was in progress before continuing it.' This provides clear context for when to use the tool. However, it does not mention when not to use it or name specific alternative tools, so it falls short of the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds thoughts by meaning. Call it when looking for something by description rather than exact title — for instance to check whether a thought on this topic already exists. Always pass variants: several phrasings of the same concept (synonyms, translation, a broader and a narrower term). They raise recall noticeably, and if the semantic index is not built they are all that works.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Defaults to 15. | |
| query | Yes | What you are looking for, in your own words. | |
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. | |
| variants | No | Other phrasings of the same concept: synonyms, a translation into the second language, a broader and a narrower term. Three to six of them. | |
| includeAuxiliary | No | Include types and tags in results. By default only ordinary thoughts. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a key behavioral trait: 'if the semantic index is not built they are all that works', revealing a dependency on the index and a fallback limitation. It also notes that variants 'raise recall noticeably', providing insight into search behavior. However, it could add detail on result ranking or pagination, but the core behavioral trait is covered.
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 compact—three sentences—with the core purpose front-loaded. Each sentence adds distinct value: purpose, usage context, and behavioral instruction. There is no redundancy or 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?
Given no output schema and 5 parameters, the description provides the essential context for a search tool: what it does, when to use it, and a critical caveat about the index. It also references usage of variants as a prerequisite for best results. The limit and includeAuxiliary parameters are documented in the schema, so the description need not repeat them. Slight lack of return-format detail is acceptable without an output 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 100%, so baseline is 3. The description adds value beyond the schema by explaining the purpose and composition of variants: 'several phrasings of the same concept (synonyms, translation, a broader and a narrower term)' and their impact ('raise recall noticeably'). This enriches the schema's parameter descriptions.
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 opens with 'Finds thoughts by meaning', a specific verb+resource statement. It further distinguishes itself by contrasting with exact title lookup ('rather than exact title'), which clearly separates it from siblings like brain_get_thought.
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 explicitly states when to call it: 'Call it when looking for something by description rather than exact title' and gives a concrete example ('check whether a thought on this topic already exists'). It also provides directive usage guidance: 'Always pass variants' with explanation, making the usage context very clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replaces a thought's note entirely. The previous text is lost — to add rather than replace, call brain_append_note. Read an existing note with brain_get_thought before overwriting it.
| Name | Required | Description | Default |
|---|---|---|---|
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. | |
| markdown | Yes | The complete new note body, in Markdown. | |
| thoughtId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosure. It explicitly warns 'previous text is lost,' highlighting the destructive nature. It also advises reading the existing note first, which is useful safety context. However, it doesn't mention behavior for nonexistent thoughts or return values, leaving some gaps.
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 two sentences, front-loaded with the primary action, and every sentence earns its place: the replacement semantics, the alternative tool, and a safety caution. No waste.
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 setter with three parameters and no output schema, the description covers purpose, usage, and the key destructive behavior. It omits details like return values or handling of nonexistent thoughts, but these are less critical for this tool. Overall quite 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?
The schema already describes brainId and markdown, with thoughtId lacking a description. The description adds little parameter-specific detail beyond reinforcing that markdown is the complete replacement. With 67% schema coverage, this is adequate but not enhanced.
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 the tool 'Replaces a thought's note entirely.' This is a specific verb+resource combination that clearly distinguishes it from siblings like brain_append_note, which adds rather than replaces.
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 explicitly says 'to add rather than replace, call brain_append_note' and advises reading the existing note with brain_get_thought before overwriting. This provides clear when-to-use guidance and names alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attaches and removes a thought's tags. Tags are separate thoughts of a special kind; take their identifiers from brain_list_types_and_tags, and create a new tag via brain_create_thought. A single call can both add and remove.
| Name | Required | Description | Default |
|---|---|---|---|
| add | No | Tag identifiers to attach. | |
| remove | No | Tag identifiers to remove. | |
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. | |
| thoughtId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a notable behavior—that both add and remove can happen in one call—and explains the special nature of tags. However, it does not mention potential side effects, error handling for invalid IDs, or whether operations are idempotent, leaving significant behavioral gaps.
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 three sentences, each earning its place. It front-loads the primary action, then provides essential context about tags and the combined add/remove capability, with no filler or redundancy.
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 the core workflow: attaching/removing tags, sourcing tag IDs, and creating tags. However, it omits details about the required thoughtId parameter (e.g., where to get it), how to handle cases where both add and remove are empty, and any return behavior. These gaps make it incomplete for a tool with no output schema and no annotations.
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 75% (add, remove, brainId have descriptions; thoughtId does not). The description adds semantic value beyond the schema by explaining that tags are separate thoughts and that identifiers come from brain_list_types_and_tags, enriching the 'add' and 'remove' parameter meanings. However, thoughtId remains undocumented in both schema and description, preventing a higher score.
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 clearly states the tool 'attaches and removes a thought's tags', using a specific verb and resource. It distinguishes itself from sibling tools by explaining that tags are special thoughts and directing users to brain_list_types_and_tags for identifiers and brain_create_thought for creating tags, which clarifies its unique role.
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 clear usage context by explaining the prerequisite steps: obtaining tag identifiers from brain_list_types_and_tags and creating new tags via brain_create_thought. It also notes that a single call can both add and remove, but it does not explicitly describe when not to use this tool compared to alternatives like brain_update_thought, 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.
Walks the graph several hops out from a thought. Call it when you need to see the whole neighbourhood: which region of the brain adjoins a topic, where new material should slot in, what already sits nearby. Viewing a thought shows one hop only.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Hops. Defaults to 2. | |
| follow | No | Which link kinds to follow. All of them by default. | |
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. | |
| maxNodes | No | Safety valve. Defaults to 150. | |
| thoughtId | Yes | Where to start. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It implies a read-only 'walk/view' operation and describes multi-hop behavior, but it does not explicitly state that it makes no modifications, mentions no permissions or side effects, and does not describe return format or performance costs.
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 three sentences, front-loaded with the primary action, then usage guidance, then a contrast. Every sentence earns its place; no filler or redundancy.
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 purpose and usage are clear, and all parameters are documented in the schema. However, with no output schema, the description remains vague about what the tool actually returns; 'whole neighbourhood' is evocative but not precise about the data shape, which is a notable gap for an agent invoking it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the baseline is 3. The tool description does not add parameter details, but the schema already sufficiently explains depth, follow, maxNodes, and the identifiers, so no extra compensation is needed.
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 clearly states the tool's function: it walks the graph plusieurs hops out from a thought, making it a traversal tool. It distinguishes itself from siblings by contrasting 'viewing a thought shows one hop only', so the agent knows this tool is for multi-hop exploration.
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 explicitly instructs 'Call it when you need to see the whole neighbourhood', providing a clear when-to-use directive. It also contrasts with the single-hop viewing alternative, giving a practical exclusion and implicit alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes a thought's properties: title, caption, type, colours. Call it to rename or reclassify. It does not touch the note — use brain_set_note or brain_append_note for that.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New title. | |
| label | No | Caption; null clears it. | |
| typeId | No | Type; null removes the type. | |
| brainId | Yes | Brain identifier. Take it from brain_list — never guess it. | |
| thoughtId | Yes | Which thought to change. | |
| backgroundColor | No | Background colour. | |
| foregroundColor | No | Text colour, for example #ff7145. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the burden and does add useful context by clarifying that only the thought's own properties are modified and the note is untouched. However, it does not disclose whether the update is partial (only provided fields) or full, nor any error/return behavior, which would be relevant for a mutation without annotations.
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 three short sentences, each earning its place: purpose, use case, and exclusion/alternative. It is front-loaded with the core action and avoids redundancy.
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 the tool has 7 parameters and no output schema, the description provides enough to select and invoke correctly, and it even points to alternatives for note editing. It lacks explicit partial-update semantics, but the schema descriptions cover null-clearing behavior. Overall it is sufficient without over-explaining.
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 covers all 7 parameters with descriptions such as 'New title' and 'Caption; null clears it.' The description's mention of 'title, caption, type, colours' is a high-level summary that doesn't map directly to the property names 'name' and 'label', but the schema already disambiguates. Baseline 3 is appropriate since schema coverage is 100%.
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 opens with a specific verb ('Changes') and identifies the resource ('a thought's properties'), explicitly listing which properties are affected (title, caption, type, colours). It further distinguishes itself from sibling note-editing tools by clarifying it does not touch the note, which clearly separates it from brain_set_note and brain_append_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit use cases: 'Call it to rename or reclassify.' It also provides an explicit exclusion and alternative: 'It does not touch the note — use brain_set_note or brain_append_note for that.' This satisfies the when/when-not/alternatives requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every tool targets a distinct operation: search vs traverse vs get are clearly different (semantic lookup, graph walk, single-thought detail), and create_thought vs ingest are separated by single vs batch. Even similar tools like set_note and append_note are explicitly differentiated by replace vs append semantics.
All tools use the brain_ prefix with snake_case and descriptive verbs, but a few (brain_activate, brain_list, brain_index) omit an object while the majority follow verb_noun. This is a minor deviation, not a chaotic mix.
17 tools is slightly above the usual sweet spot but each one addresses a meaningful capability of the graph system (thoughts, notes, links, tags, index, batch ingest). No tool feels redundant; the count is justified by the domain's scope.
The surface covers the core lifecycle: list brains, search/get/traverse, create/update/delete thoughts, edit notes, link, tag, attach URLs, and manage the index. Obvious gaps include no explicit unlink or reparent operation, but these can be worked around via update_thought and the graph structure.
MCP server for querying BrainKB, a knowledge base for neuroscience knowledge graphs.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Personal knowledge graph as an AI memory layer over MCP - read, save, and link your memories.
FastMCP server for TheBrain API — AI access to a personal knowledge graph, Tollbooth-monetized
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/yBookoff/thebrain-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server