ThreadMind MCP is a git-friendly memory server that stores AI session context as a tree of Markdown thread summaries, and this schema exposes 11 tools for managing projects, threads, summaries, context, setup files and stats.
Manage projects: project_create (title, optional systemContext, solo/team mode), project_list, project_switch by projectId.
Manage threads: thread_create (title, optional parentId) to branch a child thread, thread_list to show the tree, thread_switch to change the active thread, thread_rebase to move a thread and its descendants under a new parent, thread_delete to remove a thread and all descendants.
Work with summaries: summary_update to write/replace a thread's markdown summary content (optionally targeting a specific threadId).
Load context: context_get to assemble the active thread's context by walking up the parent chain — intended at the start of every session.
Set up clients: threadmind_init to generate instruction files for claude, cursor or generic clients (default: all).
Check value: stats_show to report token savings statistics for the active project.
Note: compared with the README, this schema omits thread_status and thread_merge, and several documented parameters (summary_update sections/paths/replaceSection, context_get maxTokens, thread_switch maxTokens, AGENTS.md/"agents" client target, thread_create branch linking).
Integrates with Git repositories by storing thread summaries as Markdown files in the repository, linking threads to branches and commits, activating threads based on the checked-out branch, and warning when code described by a summary has changed since the recorded commit.
Click on "Deploy 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., "@thread-mind-mcp Create a thread for auth system under main, summarizing what we discussed."
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.
Branches for your AI's memory: a git-friendly tree of thread summaries.
ThreadMind is a Model Context Protocol (MCP) server that gives AI coding sessions a memory: a tree of threads, each holding a short summary of what was decided about one topic, stored as Markdown in your repository. Start a fresh session and the active thread's context — its decisions and those of its ancestors — replaces a history that had grown to tens of thousands of tokens.
Documentation | npm | GitHub
With AI coding assistants, conversations grow long: every request carries the whole history, until the client compacts it or you start over — and starting over loses what was decided. ThreadMind keeps what matters:
Summaries in sections — Decisions, Constraints, State, Open questions, Next steps
Inheritance through the tree — a thread's context is its summary plus its ancestors' decisions and constraints; sibling branches stay out
Branching exploration — try approaches in separate threads, merge the winner's conclusions into the parent, keep the reason an approach was abandoned
Git-aware — a thread created on a feature branch becomes active whenever that branch is checked out, and summaries warn when the code they describe has changed
Team collaboration — thread files are committed with the code and reviewed in pull requests
ThreadMind can't shrink a conversation in progress: your client decides what it sends. The savings come when you start over:
Before /clear: the conversation carries ~48,000 tokens of history
After /clear: the session starts with the thread's context, ~1,100 tokens
main
├── auth
│ └── auth-ui ← active context = main + auth (decisions, constraints) + auth-ui
└── dashboard dashboard stays outWith the Claude Code plugin, the context reloads automatically after /clear and after compaction, and stats_show measures both sizes on your own sessions.
Related MCP server: RelayPlane
/plugin marketplace add mahmoud-nb/thread-mind-mcp
/plugin install thread-mind@thread-mindThe plugin installs the server and adds:
a SessionStart hook that loads the active thread's context at startup, after /clear and after compaction (nothing happens in repositories without a ThreadMind project)
a SessionEnd hook that records how large the conversation grew, read from its transcript, for stats_show
commands: /thread-mind:context, /thread-mind:tree, /thread-mind:create, /thread-mind:switch, /thread-mind:summary, /thread-mind:merge, /thread-mind:stats
If you configured ThreadMind manually before, remove that configuration so Claude Code doesn't run two servers.
No installation required — run directly with npx:
npx thread-mind-mcpOr install globally:
npm install -g thread-mind-mcpAdd to your Claude Code MCP settings (~/.claude/settings.json or project .claude/settings.json):
macOS / Linux:
{
"mcpServers": {
"thread-mind": {
"command": "npx",
"args": ["-y", "thread-mind-mcp"]
}
}
}Windows:
{
"mcpServers": {
"thread-mind": {
"type": "stdio",
"command": "cmd",
"args": ["/c", "npx", "thread-mind-mcp"],
"env": {}
}
}
}On Windows,
npxmust be wrapped withcmd /cbecausenpxis a.cmdwrapper and cannot be spawned directly by the MCP stdio transport.
Windows + Volta:
If you use Volta as your Node.js version manager, use volta run to ensure the correct Node.js version is resolved when Claude Code spawns the MCP subprocess:
{
"mcpServers": {
"thread-mind": {
"type": "stdio",
"command": "cmd",
"args": ["/c", "volta", "run", "npx", "-y", "thread-mind-mcp"],
"env": {}
}
}
}Or via CLI: claude mcp add thread-mind-mcp --scope project -- cmd /c volta run npx -y thread-mind-mcp
ThreadMind uses the stdio transport, compatible with any MCP client. Use the same configuration above for your platform.
ThreadMind stores its data in .threadmind/ at the root of your workspace, found in this order:
The THREADMIND_ROOT environment variable, if set
The workspace roots advertised by the MCP client (a root that already contains .threadmind/ wins)
The directory the server was started from
A client that starts servers outside your project without advertising roots (for example a desktop chat app with no project folder) needs THREADMIND_ROOT:
{
"mcpServers": {
"thread-mind": {
"command": "npx",
"args": ["-y", "thread-mind-mcp"],
"env": { "THREADMIND_ROOT": "/path/to/your/project" }
}
}
}The server sends its usage instructions when the client connects (MCP server instructions): Claude Code needs no setup file. For agents that don't read them, run threadmind_init to generate an AGENTS.md file, read by Codex, Cursor, GitHub Copilot and others.
Concept | Description |
Project | A workspace containing a thread tree. Has a title, system context, and mode (solo/team). |
Thread | A node in the tree representing a discussion topic. Stores a markdown summary, and may be linked to a git branch, done or abandoned. |
Summary | What was decided in a thread, in sections: Decisions, Constraints, State, Open questions, Next steps. |
Context | The active thread's summary plus its ancestors' decisions and constraints — what the AI loads. |
Session | Each client session has its own active thread; new sessions start from the checked-out git branch. |
ThreadMind stores everything in a .threadmind/ directory at your project root:
.threadmind/
config.json # Local state: where sessions start, author ID, session measurements
.gitignore # Excludes config.json from git
projects/
my-app.json # Project configuration
threads/
my-app/
main.md # Root thread (markdown + YAML frontmatter)
auth-system.md # Child thread
auth-api.md # Grandchild threadThread files use YAML frontmatter. Each one records its parent: the tree is rebuilt from the files, with no index to keep in sync or to conflict in git.
---
id: auth-system
title: Authentication System
parentId: main
author: mahmoud-a3f9
createdAt: 2026-04-15T10:00:00.000Z
updatedAt: 2026-04-15T12:30:00.000Z
branch: feature/auth
commit: 3f2a9c1e5b7d4a8f0c6e2b1d9a7f5c3e1b0d8a6f
paths: ["src/auth"]
---
## Decisions
- JWT with refresh tokens, stored in httpOnly cookies
- Passport.js over custom middleware, for maintainability
## State
- Login and refresh done, logout pendingstatus, branch, commit, paths and mergedInto only appear when set.
When you request context, ThreadMind walks up from the active thread to the root. It keeps the whole summary of the active thread, and only the Decisions and Constraints of its ancestors:
## System Context
You are building a Next.js e-commerce application...
---
## Thread: My App
## Decisions
- Next.js 15, PostgreSQL, Stripe
---
## Thread: Authentication System
## Decisions
- JWT with refresh tokens, bcrypt, Passport.js
---
## Thread: Auth API Endpoints (active)
_⚠ 2 commits changed src/api since this summary was written: check it is still accurate._
## Decisions
- POST /auth/login, POST /auth/register, POST /auth/refresh
## Next steps
- Rate limiting on /auth/login
---
_ThreadMind context: ~160 tokens | depth: 3 threads_Only the direct ancestor chain is included — sibling branches are excluded
Summaries written before code changes are flagged, using the commit and paths recorded with them
maxTokens leaves out the farthest ancestors first when the context would be too large
Each tool declares a title and MCP annotations (read-only, destructive, idempotent), which clients can use to decide when to ask for confirmation.
Tool | Description |
| Create a new project with a root "main" thread |
| List all projects (shows the session's project) |
| Switch the session to a different project (a single project is selected automatically) |
project_createParameter | Type | Required | Description |
| string | Yes | Project title (used to generate ID) |
| string | No | System prompt or global instructions |
|
| No | Project mode (default: |
Tool | Description |
| Create a child thread; on a feature branch, link it to the branch |
| Switch this session to a different thread and return its assembled context |
| Display the thread tree, with statuses and linked branches |
| Mark a thread done or abandoned (the reason is kept in its decisions), or reopen it |
| Fold a finished thread into its parent: replaces the parent's summary, marks the thread done |
| Delete a thread and all its descendants |
| Move a thread to a different parent (like |
thread_createParameter | Type | Required | Description |
| string | Yes | Thread title (used to generate ID) |
| string | No | Parent thread ID (defaults to active thread) |
thread_statusParameter | Type | Required | Description |
|
| Yes | New status |
| string | No | Target thread (defaults to active thread) |
| string | No | Why, added to the thread's Decisions section |
thread_mergeParameter | Type | Required | Description |
| string | Yes | The parent's new summary, including the thread's conclusions |
| string | No | Thread to merge (defaults to active thread) |
thread_deleteParameter | Type | Required | Description |
| string | Yes | Thread ID to delete (cascades to descendants) |
thread_rebaseParameter | Type | Required | Description |
| string | Yes | Thread ID to move |
| string | Yes | New parent thread ID |
Tool | Description |
| Update the summary of a thread, or one of its sections |
| Get the assembled context with token estimation |
summary_updateParameter | Type | Required | Description |
| string | Yes | New summary, or the text to add to |
| string | No | Target thread (defaults to active thread) |
| string | No |
|
| boolean | No | Replace the section instead of adding to it |
| string[] | No | Files or directories the thread is about, to flag the summary when they change |
context_getParameter | Type | Required | Description |
| number | No | Token budget; the farthest ancestors are left out first ( |
Tool | Description |
| Generate instruction files for agents that don't read MCP server instructions (AGENTS.md, etc.) |
threadmind_initParameter | Type | Required | Description |
| string[] | No | Files to generate: |
Writes the same instructions the server sends to MCP clients:
Target | File | Read by |
|
| Codex, Cursor, GitHub Copilot and other agents |
|
| Claude Code — not needed, it receives the server instructions |
|
| Cursor, as an always-applied project rule |
|
| Paste into any client's custom instructions |
Earlier versions wrote CLAUDE.md and .cursorrules. threadmind_init moves the ThreadMind section out of .cursorrules when it generates the Cursor rule, and reports any section left in either file.
Tool | Description |
| Show summary sizes and, with the Claude Code plugin, measured conversation sizes |
With the plugin, each session records the size its conversation reached (read from the Claude Code transcript) and the context loaded when the next one started. stats_show reports both:
Measured sessions (Claude Code plugin):
Conversation size when sessions ended: ~48,200 tokens on average, ~96,000 at most (12 sessions)
ThreadMind context loaded at session start: ~1,150 tokens on average (14 sessions)Resource | URI | Description |
Current Context |
| Assembled context for the active thread |
Thread Tree |
| ASCII visualization of the thread tree |
Thread Summary |
| Summary of one thread, without its ancestors |
Every thread of the active project is listed as a resource: in Claude Code, type @ to mention one and bring a sibling thread's summary into the conversation.
Prompt | Description |
| Show all available ThreadMind commands |
| Load the active thread's context into the conversation |
| Show the thread tree |
| Show statistics |
| Create a new thread (via |
| Switch to a thread (via |
| Move a thread to a different parent (via |
| Save the given summary, or have the AI write one (via |
| Generate instruction files (via |
| Same as |
| Same as |
tm-context, tm-tree and tm-stats embed their result directly, without a tool call. The other prompts ask the AI to call the matching tool, so your client's confirmation settings still apply to changes. Thread ID arguments support autocompletion.
In Claude Code, these appear as slash commands: /mcp__thread-mind__tm-help, /mcp__thread-mind__tm-create, etc.
The server instructions teach the AI short text commands you can type directly in chat:
Command | Action |
| Show all available commands |
| Load assembled context |
| Show thread tree |
| Create a new thread |
| Switch to a thread |
| Write and save the summary |
| Save specific summary content |
| Fold the thread into its parent |
| Mark the thread done |
| Mark the thread abandoned |
| Show statistics |
| Delete a thread |
| Move a thread to a different parent |
| Generate instruction files |
| Create a new project |
| List all projects |
You: Create a new ThreadMind project called "E-Commerce App" with system context
"Building a Next.js e-commerce platform with Stripe payments"
AI: [calls project_create] → Project "e-commerce-app" created. Main thread active.Claude Code needs no further setup. To let other agents (Codex, Cursor, Copilot…) use the project too, ask for threadmind_init, which generates an AGENTS.md file.
You: [discuss the architecture with AI...]
You: tm:summary
AI: [writes the summary in sections, then calls summary_update]
## Decisions
- Next.js 15 App Router, PostgreSQL with Prisma, Stripe Checkout
## Next steps
- Authentication
You: We'll use Stripe webhooks for order confirmation, record it.
AI: [calls summary_update with section "decisions"] → Section "decisions" updated.$ git switch -c feature/payments
You: tm:create Payment Integration
AI: [calls thread_create] → Thread "payment-integration" created under "main".
Linked to git branch "feature/payments".
main
└── payment-integration [branch: feature/payments] ← activeYou: tm:summary
You: /clear
(the plugin loads the context of payment-integration: main's decisions
and constraints, then the whole payment-integration summary)Without the plugin, ask for tm:context in the new session.
You: tm:merge
AI: [writes main's new summary with the payment decisions, calls thread_merge]
→ Thread "payment-integration" merged into "main", which is now the active thread.
main ← active
└── payment-integration [done] [branch: feature/payments]Team mode enables collaborative thread trees shared via git.
Create a project in team mode:
project_create with title "Shared Project" and mode "team"Each team member gets an author ID on their first write, derived from git config user.name and a short hash of git config user.email (stable across clones; override it with the THREADMIND_AUTHOR environment variable)
Thread files (.threadmind/threads/) are tracked by git. Each one records its parent, so two people creating threads never conflict, even under the same parent
The local config (.threadmind/config.json) is gitignored — each member has their own session state and measurements
A teammate who checks out your feature branch starts on the thread linked to it
Action | Own threads | Teammates' threads |
Read summary | Yes | Yes |
Update summary, change status | Yes | No |
Merge into parent | If you own the parent too | No |
Delete | Yes, unless a descendant is a teammate's | No |
Create child thread | Yes | Yes |
Switch to | Yes | Yes |
Ownership prevents accidental edits; it is not access control.
Upgrading from 0.4: the tree used to live in
.threadmind/trees/. ThreadMind now moves it into the thread files on first use and deletestrees/<project>.json— commit that change, and upgrade the whole team together..threadmind/stats/is no longer used and can be deleted.
# Pull teammates' threads
git pull
# View the full tree (includes everyone's threads)
# → Use thread_list
# Branch from a teammate's thread
# → Use thread_create with parentId set to their thread
# Push your new threads
git add .threadmind/
git commit -m "Add payment-integration thread"
git pushDevelopment setup, tests, releases and publishing to the MCP Registry are described in SETUP.md.
src/
index.ts # Entry point — stdio server, or `hook <event>` for the Claude Code hooks
server.ts # McpServer factory (tools + resources + prompts + instructions)
services.ts # Services over one .threadmind directory, shared by server and hooks
types/
index.ts # All TypeScript interfaces
core/
frontmatter.ts # YAML frontmatter parser/serializer (zero deps)
ids.ts # ID validation, slugification, title normalization
lock.ts # Cross-process lock file
clock.ts # Strictly increasing timestamps
storage.ts # File I/O with atomic writes; tree derived from thread files
workspace.ts # Workspace root resolution (env, client roots, cwd)
session.ts # Active thread per session, per git branch
git.ts # Current branch, commits since a summary
summary.ts # Summary sections: inheritance, section updates
project.ts # Project lifecycle management
thread.ts # Thread CRUD, status, merge, tree rendering
context.ts # Context assembly, outdated summary notes, token budget
instructions.ts # Server instructions and instruction files
stats.ts # Session measurements and statistics report
hooks/
index.ts # SessionStart / SessionEnd hooks of the Claude Code plugin
tools/
index.ts # 14 MCP tools with Zod schemas and annotations
resources/
index.ts # 2 MCP resources + the thread resource template
prompts/
index.ts # 11 MCP prompts
plugin/ # Claude Code plugin (manifest, .mcp.json, hooks, commands)
.claude-plugin/ # Marketplace listing the plugin
server.json # MCP Registry metadataFile-based storage over SQLite — git-friendly, human-readable, zero native dependencies
Thread files as the single source of truth — each file records its parent; no tree index to drift or to conflict in git
YAML frontmatter — thread metadata and content in a single .md file, readable by both humans and tools
No external YAML parser — minimal hand-rolled parser for the simple flat frontmatter format
Atomic writes — write to a temp file, flush it, then rename it over the target, so a crash never leaves a partial file
Serialized updates — read-modify-write operations run one at a time, across sessions and hooks too, through a lock file
Slugified IDs — thread IDs derived from titles ("Auth System" → "auth-system"), collision-safe with auto-suffix, restricted to a-z, 0-9 and - (which also rules out path traversal)
One active thread per session — sessions don't move each other; new sessions start from the checked-out git branch
Selective inheritance — ancestors pass on their decisions and constraints, not their state or next steps
MCP Prompts — slash commands; read-only ones embed their result instead of asking for a tool call
Server instructions — the server tells clients how to use it, so no instruction file is needed; threadmind_init writes the same text to AGENTS.md and other files for agents that don't read them
Workspace resolution — THREADMIND_ROOT, then the client's roots, then the working directory
Measured, not estimated, savings — conversation sizes come from the Claude Code transcripts; context sizes are estimates (~3.5 characters per token)
Node.js >= 18.0.0
Git (optional: team mode author detection, thread–branch links, outdated summary warnings)
Get the assembled context for the active thread (walks up the parent chain). Call this at the start of every session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the burden. It mentions 'assembled context' and 'walks up the parent chain' but does not disclose whether the operation is safe, idempotent, or any potential side effects.
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 with no wasted words. Every part earns its place, stating purpose and usage recommendation efficiently.
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 is adequate for a no-parameter tool, but lacks details about the structure or contents of the returned context. Without an output schema, more detail would improve 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?
With zero parameters and 100% schema coverage, the baseline is 4. The description adds meaning by explaining what the tool does without arguments (returns context for active thread).
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 action ('Get') and the resource ('assembled context for the active thread'), and distinguishes the tool from siblings by specifying its operation (walks up parent chain).
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 'Call this at the start of every session', providing clear when-to-use guidance. However, it does not mention when not to use, leaving no alternative directions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new ThreadMind project with a main thread
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Project title | |
| systemContext | No | System context or instructions for this project | |
| mode | No | Project mode: solo (default) or team |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden but only states the action without disclosing side effects, authentication needs, or error conditions. It is minimal.
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 a single, clear sentence with no redundant information, front-loaded with the core 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 the sibling tools and absence of output schema, the description is adequate but lacks information about what is returned (e.g., project ID) or any side effects.
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 'with a main thread', which is not in the schema, providing context beyond the 100% covered parameter descriptions. It clarifies that creation also includes a main thread.
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 verb 'Create', the resource 'new ThreadMind project', and includes 'with a main thread', which distinguishes it from sibling tools like project_list or project_switch.
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?
No guidance is provided on when to use this tool versus alternatives. It does not mention when not to use it or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all ThreadMind projects
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose any behavioral traits such as side effects, rate limits, or return format. The implied read-only nature is not explicitly stated.
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 a single sentence that immediately states the tool's purpose, with no wasted words. It is front-loaded and efficient.
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 simplicity of the tool (no parameters, no output schema), the description is minimally sufficient. However, it lacks details like return structure or pagination behavior, which would be helpful for a list operation.
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 and schema coverage is 100%, so the description does not need to add parameter information. Baseline score 4 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 'List all ThreadMind projects' uses a specific verb ('List') and a clear resource ('ThreadMind projects'), and it distinguishes from sibling tools like project_create or project_switch by focusing on listing all projects without filtering or pagination.
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 no guidance on when to use this tool versus alternatives. There is no indication of prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switch to a different project
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | Project ID to switch to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description fails to disclose important behavioral aspects such as whether switching persists, requires authentication, or affects other tool operations. The agent is left to infer side effects.
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 a single sentence that directly conveys the tool's action with no superfluous words. It is appropriately concise for a simple operation.
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 lack of annotations and output schema, the description is insufficiently complete. It does not explain the effect of switching (e.g., changes context for subsequent queries) or provide hints on how to obtain valid project IDs.
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 covers 100% of the single parameter with a clear description. The tool description adds no additional meaning beyond what the schema already provides, so a baseline score 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 uses a specific verb 'switch' and identifies the resource 'project', making its core purpose clear. It is distinguishable from sibling tools like 'thread_switch' which operates on a different resource.
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 no guidance on when to use this tool over alternatives, such as 'project_list' to first identify projects, or prerequisites like requiring an existing project. No context on typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show token savings statistics for the active ThreadMind project
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It states 'Show' indicating read-only, but does not elaborate on what 'token savings' entails, return format, or any side effects. This is minimal.
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?
A single sentence that captures the tool's purpose without unnecessary words. Efficient and well-structured.
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 display tool with no parameters, the description sufficiently explains the action. However, it could mention the need for an active project, but it is implicit in the name.
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?
No parameters exist, so schema coverage is 100%. The description does not need to add parameter info, and baseline score 4 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 uses 'Show' as the verb and specifies 'token savings statistics for the active ThreadMind project', making the action and resource clear. It distinguishes from sibling tools focused on project/thread management.
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 does not provide explicit guidance on when to use this tool versus alternatives. It only implies usage when needing token savings stats, but no exclusions or preconditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the summary/content of a thread
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The new summary content (markdown) | |
| threadId | No | Thread ID to update (defaults to active thread) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fails to disclose behavioral traits such as whether the update is destructive, reversible, or requires specific permissions. Only mentions 'update' without elaboration.
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?
Single sentence is concise but somewhat under-specified; it could benefit from additional context while remaining brief.
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 absence of output schema and annotations, the description lacks completeness regarding return values, error conditions, or side effects, leaving gaps for the agent.
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 description does not add meaning beyond what the schema already provides. The baseline score 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?
Description clearly states the action (update) and the resource (summary/content of a thread), effectively distinguishing it from sibling tools like thread_create or thread_delete.
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?
No guidance on when to use this tool versus alternatives; lacks context on prerequisites or scenarios where this update is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new child thread branching from a parent thread
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Thread title | |
| parentId | No | Parent thread ID (defaults to current active thread) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states 'branching' without explaining what that entails (e.g., content copying, relationship implications). No disclosure of permissions, side effects, or return 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?
Single sentence, no wasted words. Front-loaded with purpose.
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?
Minimal description for a creation tool with two parameters and no output schema. Lacks details on post-creation behavior (e.g., active thread change, return value). Adequate but incomplete.
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 covers both parameters with clear descriptions (100% coverage). The description adds 'branching' context but does not provide new parameter-level information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new child thread branching from a parent thread. It uses specific verb and resource, and distinguishes from sibling tools like thread_delete or thread_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like thread_switch or thread_list. The description does not mention prerequisites or context for creating a child thread.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a thread and all its descendants
| Name | Required | Description | Default |
|---|---|---|---|
| threadId | Yes | Thread ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the destructive action and scope. It does not disclose irreversibility, required permissions, or potential side effects beyond the stated descendants.
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 a single sentence that is concise, front-loaded with the action, and contains no unnecessary information.
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 only one parameter and no output schema, the description adequately conveys the tool's purpose and scope. It could mention error handling or success confirmation, but it is sufficient for a simple destructive 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?
The input schema covers the parameter with a description, and the tool description adds the important context that deletion affects descendants, going beyond the schema's 'Thread ID to delete'.
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 action ('Delete') and the resource ('a thread and all its descendants'), which is specific and distinguishes it from sibling tools like thread_create or thread_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., thread_switch or context_get), nor any prerequisites or conditions for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Display the thread tree for the active project
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description indicates a read-only operation. However, it does not disclose any additional behavioral traits such as auth requirements or output format.
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?
A single sentence of 8 words, front-loaded and waste-free. Every word is necessary.
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 is adequate for a simple display tool with no parameters, but it lacks details about the output structure (e.g., tree format) and does not leverage sibling context to clarify its role.
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?
There are no parameters, so the schema is fully covered. The description adds no further parameter information, which is acceptable as none exist.
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 verb 'Display' and the resource 'thread tree for the active project', distinguishing it from sibling tools like thread_create or thread_delete which are mutations.
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 implies usage for viewing the thread tree but provides no explicit guidance on when to use this tool versus siblings like context_get or thread_switch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate instruction files (CLAUDE.md, .cursorrules, etc.) to enable automatic ThreadMind integration with AI clients
| Name | Required | Description | Default |
|---|---|---|---|
| clients | No | AI clients to generate instructions for (default: all). Options: "claude", "cursor", "generic" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states that instruction files are generated, but fails to mention whether existing files are overwritten, if special permissions are needed, or any side effects. This is insufficient for a mutation-like 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?
The description is a single sentence that efficiently conveys the core purpose without excess words. It is front-loaded with the action ('Generate instruction files') and is appropriately concise.
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 one optional parameter and no output schema, the description provides adequate high-level purpose and parameter meaning via schema. However, it lacks details about file overwrite behavior, target directory, and any prerequisites, leaving some contextual gaps.
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?
Input schema coverage is 100% and the schema already describes the 'clients' parameter with valid options and default behavior. The tool description adds no additional meaning beyond the schema, so baseline score 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 generates instruction files (like CLAUDE.md, .cursorrules) for integrating ThreadMind with AI clients. It specifies the verb 'generate' and the resource 'instruction files', and the purpose 'enable automatic ThreadMind integration'. This distinguishes it from sibling tools that handle context, projects, and threads.
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 no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or specific scenarios. The agent must infer usage from tool names and context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a thread to a different parent. All descendants move with it. Similar to git rebase.
| Name | Required | Description | Default |
|---|---|---|---|
| threadId | Yes | ID of the thread to move | |
| newParentId | Yes | ID of the new parent thread |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry transparency. It discloses that all descendants move with the thread, which is crucial. However, it does not mention reversibility, side effects, or constraints like cycles, leaving gaps for a mutation 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 sentences with zero waste. The first sentence states the core action, the second adds a key detail (descendants) and a helpful analogy. Information is front-loaded and efficiently communicated.
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 mutation tool with no output schema, the description omits return value information and potential constraints (e.g., circular parents). It adequately covers the core behavior but lacks completeness in describing the full effect and post-condition.
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 already provides 100% coverage with clear descriptions for both parameters (threadId, newParentId). The description adds no new semantic meaning beyond what the schema states, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Move' and resource 'thread to a different parent', clearly stating the action. The analogy to git rebase and mention of descendants distinguish it from sibling tools like thread_delete or thread_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are given. While the git rebase analogy hints at usage, there is no guidance on prerequisites, exclusions (e.g., cannot move to a descendant), or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switch to a different thread
| Name | Required | Description | Default |
|---|---|---|---|
| threadId | Yes | Thread ID to switch to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavioral traits, but it only states a vague action. No information is given about side effects (e.g., whether this changes the active thread in a session, requires authentication, or returns data). For a mutating tool, this is insufficient.
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 concise at one sentence, but it is too brief given the tool's purpose. It could include a brief note on what switching implies without being verbose; currently it feels under-specified.
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 one required parameter, no output schema, and no annotations, the description is minimal. It fails to convey important context such as success conditions or whether the switch is permanent or temporary, making it incomplete for an agent to use reliably.
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% with a single parameter (threadId) already described in the schema. The description adds no further meaning, so a baseline score of 3 is appropriate; it does not improve understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Switch to a different thread' clearly states the verb 'switch' and the resource 'thread', distinguishing it from sibling tools like thread_create or thread_delete. However, it lacks specificity on what switching entails (e.g., activating the thread for further actions).
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?
No guidance is provided on when to use this tool vs alternatives like project_switch or thread_create. The description does not mention prerequisites or conditions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.2context_getproject_createproject_listproject_switchstats_showsummary_updatethread_createthread_deletethread_listthread_rebasethread_switchthreadmind_initScored across 12 tools
All tools have clearly distinct purposes: context_get, project_create/list/switch, stats_show, summary_update, thread_create/delete/list/rebase/switch, and threadmind_init each target a unique action with no overlapping functionality.
Tool names follow a consistent verb_noun snake_case pattern (e.g., context_get, project_create, thread_rebase). Even 'threadmind_init' fits as verb_noun with 'threadmind' as a compound noun.
12 tools is well-scoped for a hierarchical thread management system, covering project and thread lifecycle without being excessive or insufficient.
Core thread operations are present, but missing project deletion and a direct way to retrieve a single thread's content (only full context via context_get) creates notable gaps.
Memory for deep conversational context across any platform
Durable, revision-pinned memory storage and retrieval for AI conversations.
Turn AI conversations into visual knowledge maps. Create, connect, search, and organize thoughts.
Cross-LLM persistent memory: store context once, recall it from any AI model.
