MCP Tools Reference
basemind exposes one tool per job over stdio MCP: fifteen tools for code, documents, git history,
memory and the index. Each has its own exact schema; none takes a mode argument. Builds with the
comms feature add one coordination tool, agents, which still dispatches on a required mode.
Every tool definition carries _meta["anthropic/alwaysLoad"]: true, so a host that defers MCP tools
loads the schemas at session start: the tools are always loaded and are called directly, with no
tool-search round trip. tools/list for the fifteen tools is about 17 KB (about 4.2k tokens), down
from about 25 KB (about 6.3k tokens) for the four domain tools they replace; a test holds it under
20,000 bytes.
Every tool has a CLI command (basemind code|git|memory ..., basemind status, basemind rescan);
tests/cli_parity/ fails the build when a tool has none or the two disagree on parameters or
results. See the CLI reference. Moving from the code / git / memory / admin
tools: see Upgrading.
In the argument column required arguments come first and ? marks an optional one.
| Tool | Arguments | Use it for |
|---|---|---|
code_outline |
path, limit?, cursor?, max_tokens? |
What is in a file: symbols with kind, signature and 1-based line / end_line, plus imports. Code files only. A file edited since it was indexed is outlined as it is now and flagged stale; more than 200 imports are cut (truncated_reason: "imports"). |
code_symbols |
name, kind?, fuzzy?, limit?, cursor?, max_tokens? |
“Where is X defined”. Ranked: exact name, then prefix, then substring, then (with fuzzy: true) fuzzy subsequence. Case-sensitive. A row is path, line, kind, name, signature. |
code_read |
path, then symbol? (+ kind?) or line? + end_line? |
A symbol’s source body, or a 1-based inclusive line span. Exactly one of the two forms. A body over 128 KiB is cut after its last whole line that fits and flagged truncated (truncated_reason: "size_cap", omitted_bytes left out): read on from end_line + 1. A symbol in a file edited since it was indexed is found by parsing the file as it is, and the response is flagged stale. A symbol read refuses a file grown past scan.max_file_bytes. |
code_grep |
pattern, regex?, path?, language?, context?, limit?, cursor?, max_tokens? |
Text search over the indexed code. pattern is literal unless regex: true; a regex anchors ^ / $ at every line (CRLF-aware). path is a substring of the repo-relative path, never a glob. hits lists each file once ({"<path>": [hit, ...]}); a hit has its line, the full line text and the enclosing symbol’s name; a hit in a file edited since it was indexed has stale: true and no symbol. skipped_files counts files that could not be searched (deleted, not UTF-8, grown past scan.max_file_bytes, or leading out of the repository). A path or language filter that no indexed code file passes is an error, which names docs_search when the filter matches only documents. |
code_search |
query, lane? (hybrid / semantic / keyword), limit?, cursor?, max_tokens? |
Search code by meaning. Returns pointers (path, line / end_line, symbol), not bodies, and reports lanes_ran and lanes_unavailable with reasons. A ranking is paged to 100 hits; truncated says it was cut (truncated_reason: depth or rerank_top_k). The ranked list of a query is kept for up to two minutes, so a later page does not rank again. Needs the code-search feature. |
code_refs |
name, relation? (callers default / implementations / importers / definition), path?, line?, column?, match? (exact default / substring), limit?, cursor?, max_tokens? |
Usages; hits lists each file once ({"<path>": [hit, ...]}), a hit being its line, plus callee when that is not name. {name}: call sites of a name, matched on the exact identifier. {name, path}: callers of the definition in that file. Each hit then has resolved: true (scope / import resolution proved it binds to that definition), resolved: false (checked and not proven) or no resolved at all (not checked: the language has no resolution, the definition has no resolution facts, or the hit’s file was past the probe cap; resolution gives the reason when it holds for the whole definition). A pinned file edited or deleted since it was indexed is an error naming index_rescan, as it is for relation: "definition". relation: "implementations": types implementing or inheriting it. relation: "importers": files importing a module. relation: "definition" with path + line (+ 1-based column): go-to-definition. |
find_files |
query?, path_prefix?, language?, limit?, cursor?, max_tokens? |
Fuzzy file-name search, or a listing when query is omitted; files is a list of paths. Covers code, documents (markdown, config, PDFs) and every other file git tracks (images, fonts). A query no path holds as typed finds the file it names up to one typo first. A path_prefix or language that no indexed file has is an error. |
See Code Intelligence and Code Search.
Documents
Section titled “Documents”| Tool | Arguments | Use it for |
|---|---|---|
docs_search |
query, mime_type?, keywords?, entity?, scope?, limit?, cursor?, max_tokens? |
Semantic search over indexed documents (markdown, PDFs, Office, HTML, config and data files). Returns the best-matching passages with their path; each hit carries its document’s keywords, entities and summary. A ranking is paged to 100 hits, and truncated says it was cut: truncated_reason is depth (it goes on past them), rerank_top_k (the reranker kept its top_k best) or filter_depth (the ranking goes on past the 400 best-ranked chunks a keywords / entity filter saw). Needs the documents feature. |
See Document Search.
| Tool | Arguments | Use it for |
|---|---|---|
git_log |
path?, query?, author?, symbol?, rev?, limit?, cursor?, max_tokens? |
A row is sha (first 12 hex digits), summary, author, author_time_unix, and for recent and directory lists files ({"<path>": "<change>"}; a merge lists what it changed against every parent). No arguments: recent commits. path: commits touching a file, or a directory when it ends with / (200 commits inspected per page). query / author: full-text search; before the git-history index is ready it covers the subjects and authors of the newest 10,000 commits and sets truncated_reason: "live_walk". path + symbol: when that symbol’s body changed, read one window of the commits touching the file per page. A symbol or directory window that ends before the history does returns next_cursor (and truncated_reason: "window" when the page is short or empty), so follow the cursor until it is absent. Any git_log cursor is refused, and the walk must restart without it, when the git-history index came up since it was issued; unmatched on an empty page says that nothing inspected so far defines the symbol or touches the directory, and the last page is then an error. rev: that one commit in full, its file list held to max_tokens (budgeted and omitted when cut). A path that no commit reachable from HEAD touches and that is not on disk is an error. |
git_blame |
path, line? + end_line?, symbol?, rev?, limit?, cursor? |
Who last changed a file, a 1-based line span, or one symbol. A symbol is located in the file as it is at rev (default HEAD), not in the working tree, and line is a line at rev. |
git_diff |
path?, from?, to?, structural? |
No arguments: working-tree status (staged, modified, untracked), each list cut at 200 paths (truncated_reason: "path_cap", omitted counts the rest). A path ending in /: the status under that directory, every untracked file listed on its own and is_clean scoped to it; a directory that is not on disk and has no changed path under it is an error. path alone: that file’s working-tree diff against HEAD (a directory without the trailing slash is an error). path + from / to: diff between revisions, cut at 200 hunks or 128 KiB of hunk text (truncated_reason: hunk_cap or byte_cap, omitted hunks). structural: true: symbols added and removed instead of text hunks, with common the count of the unchanged ones. |
See Git Intelligence.
Memory
Section titled “Memory”| Tool | Arguments | Use it for |
|---|---|---|
memory_save |
key, value, tags?, visibility? (group / individual) |
Write a durable note for later sessions and other agents. Saving an existing key replaces it. Needs the memory feature. |
memory_search |
query? or key? or prefix?, tag?, visibility?, limit?, cursor? |
Recall notes: by meaning (query), one by key (key), or a list by key prefix (prefix). No selector lists everything. |
See Shared memory.
| Tool | Arguments | Use it for |
|---|---|---|
index_status |
none | Index health and repo identity: file counts per language, scan and degraded state, cache_dir (basemind’s cache directory), branch, head_sha. |
index_rescan |
paths? |
Re-index the given paths, or with no arguments the whole workspace, skipping unchanged files. Writes only basemind’s cache, never the repository. |
CLI only, with no MCP tool: basemind git churn, basemind git by-path <regex>, basemind code chunk,
basemind memory delete <key>, basemind cache stats|gc|clear and basemind admin telemetry.
Contract
Section titled “Contract”Every tool above follows the same rules.
- Exact schema. Required fields are required. An unknown argument is rejected with a
did-you-mean suggestion and the accepted list; it is never silently dropped. There are no hidden
aliases and no
formatargument. - Paths and positions.
pathis repo-relative with forward slashes. Every position is 1-based:line,end_line,column. - Paging and budget. Every list takes
limitandcursorand returnsnext_cursor. Lists are trimmed to amax_tokensbudget (default 6000) and setbudgetedwhen trimmed.limit: 0is refused by every tool that takeslimit. - Cuts. A page that ends at
limitis paging:next_cursorsays there is more and nothing else is set. A cut made by the token budget also setsbudgeted. A cut the caller did not ask for setstruncated: trueandtruncated_reason, andomittedcounts the items left out where the count is known: follownext_cursorwhere there is one, else narrow the call. Reasons:scan_cap(code_refs,code_symbols, anauthor-filteredgit_logsearch, amemory_searchlisting whosetotalstopped counting),byte_budget(code_grep),imports(code_outline),size_cap(code_read, which countsomitted_bytes),depth/rerank_top_k/filter_depth(code_search,docs_search),path_cap/hunk_cap/byte_cap(git_diff),window/shallow_clone/live_walk(git_log). Three fields say something else and keep their names:skipped_files(code_grep: files that could not be searched),limit_clamped(find_files: an over-largelimitwas lowered),body_truncated(one commit message in agit_logsearch hit) andtoo_large(git_diff: a file over 4 MiB was not diffed). - Lines. A line ends at
\n; a\rright before it is part of the ending and a\ron its own is text inside its line.code_read,code_grep, the outline andgit_blamecount lines this way, so a line number from one is a line number in the others. - Edited and deleted files. A file edited since it was indexed is read as it is now and the
response says
stale: true(code_outline,code_read,code_grep); a tool that can only answer from indexed positions (code_refswithpath) returns an error namingindex_rescan. A file deleted since the scan gets the same error from every tool. No tool reads an indexed file whole pastscan.max_file_bytes. - Filters. A
path/path_prefix/languagefilter that no indexed file passes is an error saying what would match, not an empty result. While the index is still being built the page is returned with itsnoticeinstead. - Errors. A failure the caller can fix is a tool result with
isError: truewhose text names the fix. A file that is not indexed says whether it is a document (usedocs_search) or needsindex_rescan; an empty index says to runindex_rescanorbasemind scan; a feature compiled out names the Cargo feature. - Empty index. An empty index is never a plain empty result: the response carries a
noticewithstate: "empty_index". - Inline results. Results are returned inline. A server-side Task is used only for a call still
running after 3 s (
index_rescan,code_search,docs_search), and only when the client declared the tasks extension. - Annotations. Every tool is read-only except
memory_saveandindex_rescan; none is destructive. No tool has anoutput_schema. - Telemetry. Telemetry keys are the tool names.
Example calls
Section titled “Example calls”code_outline {"path":"src/store.rs"}code_symbols {"name":"parse_config","kind":"function"}code_read {"path":"src/store.rs","symbol":"open"}code_read {"path":"src/store.rs","line":120,"end_line":160}code_grep {"pattern":"cache_root(","path":"src/"}code_grep {"pattern":"fn \\w+_call","regex":true}code_search {"query":"retry a failed upload with backoff"}code_refs {"name":"open_store"}code_refs {"name":"open_store","path":"src/store.rs"}code_refs {"name":"Drawable","relation":"implementations"}code_refs {"name":"tokio::sync","relation":"importers"}code_refs {"name":"open_store","relation":"definition","path":"src/main.rs","line":42}find_files {"query":"readme"}docs_search {"query":"how releases are versioned"}git_log {}git_log {"path":"src/store.rs","limit":5}git_log {"query":"fix race"}git_log {"path":"src/store.rs","symbol":"open"}git_log {"rev":"HEAD~1"}git_blame {"path":"src/store.rs","symbol":"open"}git_diff {}git_diff {"path":"src/store.rs"}git_diff {"path":"src/store.rs","from":"HEAD~1","to":"HEAD"}memory_save {"key":"decision/auth-tokens","value":"Tokens rotate every 24h.","tags":["auth"]}memory_search {"query":"token rotation"}index_status {}index_rescan {"paths":["src/store.rs"]}Instead of the shell
Section titled “Instead of the shell”| Shell | basemind tool call |
|---|---|
rg foo / grep -r foo |
code_grep {"pattern":"foo"} |
rg -e 'fo+' (regex) |
code_grep {"pattern":"fo+","regex":true} |
rg foo src/ |
code_grep {"pattern":"foo","path":"src/"} |
find . -name '*store*' / fd store / ls -R |
find_files {"query":"store"} |
cat file / reading a whole source file |
code_outline {"path":"file"} then code_read {"path":"file","symbol":"name"} |
git log |
git_log {} |
git log -- path |
git_log {"path":"path"} |
git log --grep X |
git_log {"query":"X"} |
git show REV |
git_log {"rev":"REV"} |
git blame file |
git_blame {"path":"file"} |
git status |
git_diff {} |
git diff / git diff -- file |
git_diff {"path":"file"} |
git diff A B -- file |
git_diff {"path":"file","from":"A","to":"B"} |
agents — multi-agent coordination
Section titled “agents — multi-agent coordination”A shared chat layer for agents on the same repo: threads addressed by at least two of subject /
path-glob / members, discovered by scope (member, cwd path-match, or subject filter — never global),
with a recency-filtered inbox. Requires --features comms.
| Mode | Purpose |
|---|---|
register |
Publish or update this agent’s identity card with the broker. |
list |
The agents the broker knows, optionally restricted to one thread. |
thread_start |
Open a thread addressed by subject, path-glob and/or members. |
thread_list |
Threads discoverable to you: membership, cwd path-match, or subject. |
join |
Join a thread so its messages reach your inbox. |
leave |
Leave a thread you joined. |
members |
Who belongs to a thread. |
add_member |
Add an agent to a thread you created. |
remove_member |
Remove an agent from a thread you created. |
archive |
Close a thread; creator or human admin only. |
post |
Send a message to a thread. Takes an optional idempotency_key (1-128 printable ASCII characters); a retry with the same key returns the original message id instead of storing a duplicate. Generated when omitted. |
history |
A thread’s messages as front-matter only; bodies come from message. |
message |
Read one message body by id — the only path to a body. |
inbox |
Unread messages across your joined threads, front-matter only. |
ack |
Clear messages you have read from your inbox. |
wait |
Block until a peer posts, or until timeout_secs elapses (default 30, max 40) — a long-poll replacement for looping inbox / thread_list. Cancel-aware: a cancelled call stops waiting at once. |
cleanup |
Preview stale agent, claim, message and thread retention; TTLs are overridable in hours. Preview-only over MCP: apply must be omitted or false, and basemind agents cleanup --apply applies it. |
status |
Active and stale agent counts plus the last maintenance time. |
See Agent Comms for orchestration examples.
Tool titles and annotations
Section titled “Tool titles and annotations”Each tool carries a human-readable title and MCP annotation hints, so a client can show a readable
name and decide what to auto-approve. The hints are exact per tool: a host that gates on read-only
can allow index_status and git_log without allowing index_rescan.
| Tool | Title | Read-only | Destructive | Idempotent | Open-world |
|---|---|---|---|---|---|
code_outline |
Outline a file | yes | no | yes | no |
code_symbols |
Find a definition | yes | no | yes | no |
code_read |
Read a symbol or line span | yes | no | yes | no |
code_grep |
Search code text | yes | no | yes | no |
code_search |
Search code by meaning | yes | no | yes | no |
code_refs |
Find usages | yes | no | yes | no |
find_files |
Find files | yes | no | yes | no |
docs_search |
Search documents | yes | no | yes | no |
git_log |
Commit history | yes | no | yes | no |
git_blame |
Blame | yes | no | yes | no |
git_diff |
Diff and status | yes | no | yes | no |
memory_save |
Save a note | no | no | yes | no |
memory_search |
Recall notes | yes | no | yes | no |
index_status |
Index status | yes | no | yes | no |
index_rescan |
Re-index | no | no | yes | no |
agents (title “Agent comms”) advertises the union of its
modes. Its mode parameter is a flat string enum in the tool schema, so a client sees every valid
mode and an invalid one is rejected with the accepted list. The server emits no MCP logging
notifications; use daemon.log and RUST_LOG for diagnostics.
MCP resources
Section titled “MCP resources”Besides the tools, basemind serves a small set of MCP resources. They are listed on demand
(resources/list, resources/templates/list), so they add nothing to the always-loaded prompt.
Each read runs the same code as the matching tool, so the body equals the tool result, including the
code-only policy: an outline of a non-code file errors with “not indexed”. They are served in lean
mode, over the daemon stdio relay and over the HTTP front-end.
| URI | Backing call |
|---|---|
basemind://status |
index_status |
basemind://outline/{path} |
code_outline; {path} is repo-relative and percent-encoded |
basemind://memory/{key} |
memory_search with key (shared tier) |
Paths are validated before they reach the index: absolute paths, .. or . segments, empty
segments, backslashes and NUL are rejected. completion/complete completes {path} from the index.
resources/subscribe is not supported.
Cancellation and tasks
Section titled “Cancellation and tasks”A client cancellation (notifications/cancelled) abandons these read-only calls at once and
answers request_cancelled (-32800): code_grep, code_search, docs_search, and agents
wait. Writing calls are never dropped mid-flight.
Results are returned inline. When the client declares the tasks extension
(io.modelcontextprotocol/tasks), a call that can run for seconds (index_rescan, code_search,
docs_search) gets 3 s to finish and is answered as an ordinary tools/call result if it does;
only a call still running after 3 s returns a pollable task handle (tasks/get). Clients that did
not declare the extension always get the synchronous result.
Paging
Section titled “Paging”limit: per-tool default.code_symbols,code_grepandcode_refsdefault to 100,code_outlineto 500,find_filesto 200,git_logto 20,code_searchanddocs_searchto 10.max_tokens: a token budget for the returned list, default 6000. Entries are kept in result order until the budget is hit; the response then carriesbudgeted: trueand anext_cursor.cursor: opaque token; pass a response’snext_cursorback to continue.
For index scans (code_refs), basemind bounds work on common names with scan_cap = limit * 8 (at
least 2000).
Lifecycle notices
Section titled “Lifecycle notices”The server warms the code map in the background after answering the MCP handshake. While
it isn’t fully ready, index_status and every code read tool may include a notice object instead
of, or alongside, their normal result:
| Field | Meaning |
|---|---|
state |
One of warming_up, building_index, rescanning, index_rebuilding, empty_index. |
message |
Human/agent-readable explanation of what’s happening. |
retry |
true to retry shortly for complete results; false if the result is usable but may be stale. |
index_status additionally reports warming / warm_ms (in-memory preload of an existing index)
and indexing / index_build_ms (first-time index build). Treat an empty or partial result carrying
a notice as “retry shortly,” not “no matches.” See
Index lifecycle and freshness for details.