Docs

MCP tools reference

This page lists each tool of the Pensieve MCP server, its arguments and what it returns.

An MCP client sends the description of each tool to the model on every turn. Thus Pensieve shows a small set by default. Other sets appear only when they are necessary. Every tool obeys the scope of the connection.

Set	When the agent sees it	Tools
Default	Always	15
Setup	Until setup is done	4
Work queue	With `pensieve mcp --all-tools` or `?tools=all`	2
Settings	With `pensieve mcp --all-tools` or `?tools=all`	16

Default tools

Tool	Arguments	Returns
`search`	`query`, `limit` = 8, `kind`	One line per hit, best first: `path:line`, the enclosing definition, the line that matched, and an id for `read` and `similar`. The top hits also show a few numbered lines. Query syntax: `"exact"`, `-word`, `ext:py`, `in:<path>`, `by:<person>`, `kind:code\|doc\|session\|folder\|repo\|person`, `since:3d`, `until:2026-10-01`, `project:<name>` (sessions).
`read`	`id` (one id, or up to 8 ids separated by spaces), `max_chars` = 12000	The full text of a result. For code, also the repo, branch, lines, owners from git blame, recent commits and the agent sessions that touched it.
`similar`	`id`, `limit` = 8	Items that are similar in meaning to a result, in the same line format as `search`. Use it before you write new code.
`people`	`topic`, `repo`, `name`	With `name`: one person, with their role, repos, recent PRs and how you work with them. With `topic`: who wrote the code most related to the topic (git blame), and the matching code. With only `repo`: the people of the repo, with their commits, main areas and recent commit subjects.
`repo`	`repo` (default: the repo of the scope), `part` = `overview` \| `gaps` \| `unexplored`	`overview`: where things are in a repo. That is the size, languages, top folders two levels deep, the start of the README, dependencies, the largest files, and topics with their files and authors. `gaps` (with `inactive_days` = 180): areas mostly written by people with no recent commit, the active person who knows each one best (`ask`) and the bus factor. `unexplored`: areas next to your own work that your agent sessions did not touch, and who owns them.
`projects`	`query`, `limit` = 8, `project`	Your projects: tickets with their branches and PRs, grouped into projects, with the people who work on them.
`list_repos`	none	The indexed repos in the scope, with their size and the number of agent sessions in each.
`current_scope`	none	The part of the index that this connection searches.
`open`	`id`, `action` = `open` \| `reveal` \| `visualize`	Opens an item on your computer: code in your editor at the line, the item in Finder, or the item on the Map.
`index_path`	`path`	Indexes a folder when you ask the agent to: a git repo, a folder of repos, a folder of agent sessions, or documents. Pensieve finds out which kind it is.
`stale`	`days` = 14	What looks abandoned: worktrees with no commit and no session, merged local branches, and repos with no activity for 3 months. Each item has a verdict and, where it is safe, a command. The agent asks you before it runs a command.
`threads`	`state` = `open,loose_ends`, `query`, `limit` = 10	Your threads that are not done, the closest to done first: the fewest steps left. Each thread shows its steps left. Each step says who can do it (you, your agent or the tracker) and the PR, branch or ticket that it acts on. `state` takes a list of states, or `all`. `query` takes words, a ticket key, a branch or a PR number.
`thread`	`id`, `full` = false, `version`	One thread now: its state and why, folder, branch, uncommitted files, PRs, tickets, what changed since the last session, the steps left, where that session stopped, its main files and the command that resumes it. `id` is a thread id (`th_…`) or an id from `threads`. `full` adds every file and the timeline. `version` = n gives that saved version (0 is the first, -1 the last). `version` = `list` lists the saved versions.
`share_thread`	`id`, `ask`	Makes a thread that is fit to send and saves it as one HTML page in `~/Downloads`. Returns the path of the file and the thread. The agent attaches the file. You approve what it sends.
`report_feedback`	`kind` = `bug` \| `idea`, `summary`, `details`	Saves a report on your computer. You read it in Settings → Feedback before you send it.

What a search returns

The result is short on purpose. The agent reads it again on every later turn. A result looks like this:

src/billing/retry.py:42  def schedule_retry(invoice)  ▸ if decline.hard: return None  [code:1832]
    41│ def schedule_retry(invoice):
    42│     if decline.hard: return None
docs/payments.md  Card retries stop after a hard decline …  [file:77]
session "fix card retries" (2026-10-12)  … we skip the queue for hard declines …  [session:4f1c…]

Pensieve adds a note to some hits:

(edited since indexed): the file changed after Pensieve indexed it, and Pensieve did not index it again before the search.
(near-copy of …: read both to tell them apart): another hit has almost the same code.
(main checkout; differs in your worktree): the agent works in a linked worktree, and its copy of the file is different.

To see what an agent gets, run the same search from a terminal in the repo:

pensieve search "retry failed webhook delivery" --kind code

Setup tools

Until you finish setup, Pensieve indexes nothing. Every connection then also gets these tools, so the agent that installed Pensieve can do setup with you in its chat.

Tool	Arguments	Returns
`setup_guide`	none	What Pensieve is, the user profiles, the source categories and the folders that each scan reads, the search models and the energy note. It reads no folder. The agent then asks you each question in order.
`setup_scan`	`profiles` or `categories`	What can be indexed in those categories, with the size of each item and the recommended items. macOS can ask you for folder access.
`setup_add_source`	`kind` = `files` \| `repos` \| `agents`, `path`	The id of a source that the scan did not find.
`setup_start`	`sources` or `recommended`, `content`	Starts indexing. Returns the time left, the energy note and how to search.

Work queue tools

A command-line agent, the built-in model or a model server that you run answers the text jobs in the background (Settings → Models → Notes and summaries). These two tools are only in the ?tools=all set: with them, an agent can answer the same jobs by hand.

Tool	Arguments	Returns
`pending_work`	`limit` = 5, `kind`	Jobs that wait for an answer: thread notes, session summaries, topic names, insights and collection plans. Each job holds its instructions and its data.
`submit_work`	`id`, `answer`	Saves the answer to one job. Pensieve uses it in its next pass.

Settings tools

These tools change Pensieve itself. An agent gets them only with pensieve mcp --all-tools, or with ?tools=all over HTTP.

Tool	Arguments	Returns
`show_search`	`query`	Opens the search panel with the query.
`show_visualizer`	`view`	Opens the Map window.
`status`	none	The size of the index and whether indexing runs now.
`list_scopes`	none	The named scopes and the current scope.
`save_scope`	`name`, `sources`, `description`	Makes or replaces a named scope.
`delete_scope`	`name`	Removes a named scope.
`get_settings`	none	The settings, with a description of each.
`update_settings`	`changes`	Changes settings, for example `{"editor": "cursor"}`.
`list_sources`	none	The sources by category, with their on and off state and item counts.
`set_source`	`id`, `enabled`, `map`	Switches a category or one item on or off, or on or off the Map.
`file_types`	none	For each file type: whether Pensieve reads its content, whether it shows on the Map, and how many files it has.
`add_folder`	`path`	Indexes another folder.
`remove_folder`	`path`	Stops indexing a folder.
`reindex`	none	Scans folders and repos now.
`usage_stats`	`days` = 7	Pensieve's own MCP calls: for each tool, the number of calls, errors and the p50 and p95 time.
`set_thread_state`	`id`, `state`, `reason`	Sets a thread's state by hand, as the button on the thread does: `todo`, `open`, `loose_ends`, `complete`, `forgotten`, or `auto`. An agent does not need it to close a thread: Pensieve sets each state from the evidence.

Errors

A bad argument, an unknown id or an item outside the scope comes back to the agent as a readable error. Pensieve logs each call on your computer, in usage.db. Settings → Usage shows the log.

Something wrong or missing? Tell us on GitHub.