Skip to content

Tools reference

Brandon White edited this page Nov 20, 2026 · 8 revisions

Fourteen listed tools, every full tool behind them

tools/list names 14 tools (about 1,510 tokens; it was 47 tools and 5,930 tokens). lookup, search, section, grep, symbol, recall, remember, journal, handoff and hook keep their names; the rest of the surface sits behind four tools with an op argument:

Listed tool op Runs
note (reads) read (default), list, find, backlinks, outlinks, broken, link, log, vaults, sources, judge, help read_note, list_notes, find_by_frontmatter, backlinks, outlinks, broken_links, make_link, write_log, list_vaults, list_sources, judge_task, the help text
edit (writes) create, append, history, frontmatter, section, link, next_id, index, refresh, refresh_all create_note, append_to_note, append_history, set_frontmatter, replace_section, link_notes (vault and path name the note written into), next_id, build_index, refresh_index, refresh_all_indices
discuss open, post, read, status, awaiting, list, queue, conclude, unresolved, decide open_discussion, post, read_discussion, discussion_status, awaiting, list_discussions, decision_queue, conclude_discussion, mark_unresolved, record_decision
miss list (default), report, resolve misses, report_miss, resolve_miss

lookup without id runs ids; remember with old runs supersede; recall with op: "status" runs journal_status and with op: "log" runs memory_log. Each listed schema names the arguments most calls use, without descriptions; every argument of the full tool an op runs is still accepted and checked. The whole reference, every tool and argument described, is one fetched text: the MCP resource atlas://help, or note {op: "help"} for a client without resources. The full tool names (the table below) still work as tool names for this release, so existing calls and hooks keep running; the server's instructions point at the help.

Four are always loaded

search, recall, section and grep are marked always-loaded (_meta["anthropic/alwaysLoad"]: true in tools/list, Claude Code 2.1.285 and later), so their schemas are in context from the first turn and the model calls them without a tool search first. Every other tool stays deferred: only its name is in context until the model searches for it. lookup and symbol (the identifier and code indexes) are deferred too: 12 calls a week did not pay for their 627 bytes in every agent's context, so an agent loads them by a tool search (in Claude Code, ToolSearch with select: and the tool's name) before its first call.

Answers are compact text

Every tool answers in plain text by default; format: "json" gives the JSON instead (for the memory tools: recall {key} and recall {op: "status"} as fields, every other memory answer as {"text": ...} around its text), and verbose: true adds scan times and timings where a tool takes it. read_note is one vault:path sha256=... bytes=N line, then the note exactly as written (the JSON answer repeats the frontmatter parsed beside the content). A tool without a text form of its own writes its JSON as key: value lines, a list of flat records as one table under key: N, and every element of every list: the work-queue tools (decision_queue, awaiting, journal_status) are never cut. journal_status lists the active lanes (an open question, a queued entry, or a record in the last 14 days), then +N idle lanes (all=true to list) for the rest; all: true lists every lane. The text (src/text.rs):

  • A list is a header row of field names, then one tab-separated row per record, so names appear once. Inside a value a tab is written \t, a newline \n and a carriage return \r; nothing else is escaped.
  • A snippet is about 120 characters centred on the matched identifier or word, cut on character boundaries, with … where it was cut. Repeat mentions in one section are one row with a count (n).
  • Default limits are small (lookup mentions 3, search 50 lines or 5 sections, ids 50, misses 20) and a cut list ends with +N more (limit=L). recall {query} ends with what it left out: +N more over budget_tokens, +N more scoring near zero, +more (limit=L). A kind or scope filter searches every word of the query up to its first 48, and a query longer than that ends with +N more words were not searched; with no filter, a long query is searched by its 12 rarest words. The query is not echoed.
  • Freshness says nothing when everything is fresh; otherwise one stale SOURCE:PATH STATE[, reindexed] line per file, up to 8 per source; past that one stale SOURCE N files (REASON)[, reindexed] line, where REASON is why the source is rebuilt from empty (schema rebuild, index rules changed, first index) or the count per state (12 changed, 3 new). JSON gives stale_count and reason in place of the list.
  • lookup shows its definitions first (defs), then the strongest definition's text capped at 600 characters (full: true for every definition whole), then mentions. search in sections mode shows snippets (full: true for whole sections).

Each answer is sent once, as the text content: there is no structuredContent copy.

Token ledger

Every answer is logged to the token_log table with the bytes returned and the bytes the same question costs without atlas: what grep -rniF would print for the question's literal over the same files, plus the files a reader then opens (whole when at most 80 lines, else an 80-line window around each match, windows merged). The rule is in src/tokens.rs; the measurement runs on a background thread after the answer is written. atlas --token-report prints a summary in about 15 lines: the measured ratio (mean and median), credit, cost and net, the "Where the savings live" rows by source (when two or more sources are each under 1% of both the credit and the cost, they fold into one "small sources" row), and the answers and ledger ratio of the 7 days to the newest logged day. Every line fits 80 columns. atlas --token-report --verbose prints the full report: totals by tool and by day (tokens returned, the counterfactual, and the ratio) and every block below; --tsv prints the full report as tab-separated lines. The blocks named below are the full report's.

The other read tools with a grep equivalent use the same two parts: section greps its id or heading like lookup, grep is its own pattern, read_note reads the whole note, recall {query} greps the query over the export files, and recall {key} or {lane} reads the record where it is written (a memory's whole file; another record's text plus 40 lines either side in its export; a lane's every record), the rule the hooks use. Writes, journal among them, log no counterfactual.

The "brief without atlas" is what an agent spent on the rulebook (memory.brief_reference) before atlas, measured from the calibration's pre-atlas transcripts: the bytes of their Read calls of that path (matched as text, slashes and case folded, a relative path joined to the call's folder) over every pre-atlas subagent transcript, readers and non-readers alike; main sessions are left out. Agents read parts of it, so its size is not the yardstick. With no calibration, or no such read, the report says "not measured" and gives no ratio. Each subagent start logs the rulebook's size at that moment; --token-report counts agents by those rows (a distinct session and agent id) and keeps their sum as one if read whole line, the size once per agent, not a measurement. Each agent is counted once, at its first start: Claude Code fires SubagentStart again whenever an agent resumes (a SendMessage, or a background task waking it), and a resumed agent keeps its context, so the report gives those repeats as resumes and does not count them as reads. It never enters a per-answer ratio. Beside it, hook injections sums what the recall hooks injected: a main session (it lives for many prompts) per prompt, by the turn rule of the cost section, and a subagent per agent, each as p50, p95 and max, then the largest one main session or subagent received. brief vs injections then compares the measured rulebook with what the hooks injected on the agents both tables hold, and the ratio. A Where the savings live block, right after the headline, gives credit, cost and net per source (lookups, routing, the rulebook at subagent starts, prompts and tool calls, memory and note reads, tool definitions, the rest), each against its yardstick; the rows sum to the net, whose credit counts the rulebook only when it is measured. No source is credited twice: a measured rulebook replaces the SubagentStart hit credit, and is credited less the credit of recall by key or lane, which may read the same records. Other lookups that open the rulebook may still overlap it; the ledger records no agent or file per answer, so the block's header bounds that overlap by the rulebook row's credit instead of measuring it. A PreToolUse injection is costed by event, so a subagent's lands on the prompts and tool calls row. read_note is 1x by design: its counterfactual is the whole file it returns, and section is the cheaper read for one heading. recall.inject_floor (a cosine threshold) and recall.session_budget_tokens (a cap per session) bound it. Then a context selection line says what recall.select did to those injections: how many were sent whole, trimmed to their matching clauses or collapsed into a ref to a near-duplicate, the tokens each would have taken whole against what was sent, and the share saved.

The report also measures what atlas itself costs, from bytes, with no model estimate. A: the tool list and instructions sent at every session or subagent start the store shows, plus each atlas tool schema loaded later through tool search. B: the hook injections as sent, by event, plus their re-reads: an injection stays in context for every later request up to the next compaction. C: every tool's returned bytes, one total for all sessions (the ledger has no session column). A Net block after the headline gives credited savings minus that cost, and a net table gives it by tool. Each re-read is priced from its request's usage block: cache reads, 5-minute and 1-hour cache writes and uncached input by their proportions, at the ratios of one price table by model (src/token_cost.rs); a request with no usage block or an unknown model is priced at the full rate and counted. Tool search loads and re-reads are seen only with --token-report --transcripts DIR (Claude Code's projects folder, read only); without it, or for a session whose transcript is gone, the net line says it counts only the costs atlas can see and that the true net is lower. A turn is a distinct second of a main session's UserPromptSubmit rows, so a prompt that injected nothing is not counted and the cost per turn errs high.

recall {key: "KEY@HASH"} reads one exact version: HASH is 8 to 64 hex digits of the version's SHA-256 (a ref is written with 12, the start of the sha line a recalled record shows). The answer is that version verbatim, marked (current), or (changed: the current text is KEY@NEW) when a later version replaced it; a hash no version has is an error that says the ref is dangling. Versions are never deleted, so a ref handed out once always resolves to its text. recall {key: "SRC:PATH:A-B@HASH"} reads lines A to B of a vault or source file: marked (current) when the hash still names them, else the current lines with their new ref (a path with a space cannot be written as a ref). With memory.transcripts on, recall {key: "turn:<session8>:<line>@hash"} returns one earlier transcript turn as stored (visible text, secret lines [redacted]) and recall {query, kind: "turn"} lists matching turns with their refs; both see this project's turns only, and with the source off both are refused. atlas --compact-report --transcripts DIR [--sweep T,T,...] adds the checkpoint card's size and coverage, the hooks' latency, and with --sweep the token side of where to compact (a plain and an atlas-assisted arm at each threshold on the same sessions, each atlas row judged against plain at the same threshold: compactions, raw and cache-weighted tokens, re-reads; plain at Claude Code's default point is a labelled reference row only). --token-report --verbose ends with the compaction line: the ratio of context before a compaction to its summary, refs and their dangling rate, and the lookups made again after one: within 40 tool calls of the boundary, repeats over lookups (comparable with the offline replay) and misses of targets unchanged since (a file's mtime and size, a folder by the edits under it and any shell command, a record's sha), then the uncapped misses, the repeats of changed targets and the unstamped ones (shell commands, MCP calls without a key). atlas --token-report --repeats [--since TIME] lists the 20 targets repeated most since TIME (paths, patterns, keys, and a shell command's first two words with a hash), misses, changed and unstamped apart.

atlas --misses-week [--since TIME] is the weekly misses pass: the ten open misses (report_miss) seen most since TIME (default seven days ago), by tool and query, then the ten injected keys that cost the most tokens in the same window, to check whether each earned its place.

Every key a hook injects is logged to hook_inject with its scores, bytes and counterfactual. atlas --hook-report marks each one a hit by fixed rules, looking only at the same session's later assistant messages: the key in a tool input (a recall key=, a lookup, a grep), its source read (a memory's file, or a Grep of its export file whose pattern matches it), or a quoted run of 8 of its words; and prints the hit rate per hook. --transcripts DIR --since TIME adds injections reconstructed from past transcripts (rescored by the hook's own gate), --rows lists every key, and --tune-floor SCALE prints the relevance-floor curve from the active floor up and the floor that maximises the bytes the kept hits save net of the bytes injected (SCALE is the share of a hit's counterfactual credited: 1 for the full ledger credit). --token-report credits each hit by the same rules; once an injection's transcript has been still for six hours (and ends before the ledger's last row), its verdict is stored in hit_verdict, so a repeat report reads only the transcripts still changing. A stored verdict (a hit's, or a routed Read's in read_verdict) keeps the judge's version and the transcript's last change and size, and is judged again when either differs, as when a settled session is resumed; once the transcript is deleted, its stored verdicts stand. They hold memory as it was when they were judged: a later edit to a record does not change them.

The counterfactual is rule-based, not a bound: some rows overcount and others score 0. atlas measures the other side itself, from your own Claude Code transcripts: the bytes of the Grep, Read and shell-read results agents read when they looked something up in the files atlas serves, before atlas, grouped into one episode per question. The server does it in the background, never on a hook's path, at its first start and again when the lookup rules or the configured targets change; atlas --calibrate does it by hand, with progress. The cutoff is the earlier of the store's first atlas answer and the first atlas call in the project's transcripts, kept from the first run; the transcripts are those whose session ran in one of the project's folders (every one without projects), less temporary, scratch, eval and replay folders (calibrate.skip); a call another transcript already holds (a replay, a resumed session) counts once. What the rules read of each pre-cutoff call (never a result's text) is kept in the store, so a later recalibration does not lose history Claude Code has since deleted. --token-report --verbose then heads its output with the measured ratio (mean pre-atlas episode over mean atlas answer, a ratio of sums; the medians' ratio beside it, marked not additive), when it was measured, from how many episodes and transcripts and with which rules version, and the ledger ratio with its per-answer median, labelled rule-based, not a bound. With fewer than 30 episodes from 5 transcripts it gives the ledger ratio alone and says why. The rules are in src/calibrate/.

Tool Writes What it does
lookup an identifier's definitions (strongest first, each with the defining text) then mentions (newest first), source, path, heading path and line for each, plus freshness; text_hits when nothing is registered
ids registered identifiers in natural order: kind, definition and occurrence counts, newest date; filters prefix, pattern, kind, source
list_sources vaults and sources: root, globs, files and sections, last scan and index times, stale files
judge_task the task judge's pick for an agent launch prompt (prompt; kind, else read from the prompt, subagent_type and description): scope, unknowns, model, effort, split, and a Judge: line to paste. Needs orchestrate.judge.cells
report_miss misses log records what grep found and atlas did not: tool, query, what atlas returned, where it was found, reason
misses the misses log, newest first: open (default), resolved or all
resolve_miss misses log marks a miss resolved; the reason is the note. Misses are never deleted
list_vaults short name, folder name, note count
list_notes notes under a folder, optional glob (* ? **; without / it matches the file name)
read_note a vault:path sha256=... bytes=N line, then the note as written; JSON: content, sha256, size, parsed frontmatter
search substring (default), regex, or fts (SQLite FTS5, ranked) over vault notes only (an empty answer says so when sources are configured; sections or grep reach sources), returning vault, path, line, snippet; or sections: ranked FTS5 over the sections of every vault and source, returning whole sections with heading path and line range, plus freshness; semantic ranks the same sections by meaning, hybrid fuses both rankings (see the Semantic search page)
symbol a name (or Type::name) in Rust, WGSL, Protocol Buffers, Go, TypeScript, JavaScript, C#, Python or Java (Kotlin and unindexed files: definitions only; see Code index for when each needs its SCIP indexer): its definitions, then references with the function each sits in (the caller), then impl edges, each root:path:line with a snippet (see the Code index page)
find_by_frontmatter key = value (list values match any item, prefix for queued vs queued 139)
backlinks / outlinks across all vaults: wikilinks, embeds, Markdown links, obsidian:// links, each resolved
broken_links links whose target note is missing, cross-vault included (attachments not checked)
make_link [[wikilink]] in the same vault (folder dropped when the file name is unique in the vault, as Obsidian's shortest-path links do), obsidian://open link across vaults; errors if the note or heading is missing
link_notes yes appends - <link> under ## Related (or another section, created if missing); reverse links back; skips a link already present
create_note yes fails if anything exists at the path (create_folders to make parents)
append_to_note yes appends at the end
append_history yes - YYYY-MM-DD: text as the last line under ## History (heading created at the end if missing); date defaults to local today
set_frontmatter yes replaces named keys' lines in place; other keys and the body stay byte-identical
replace_section yes replaces one heading's body, or the preamble (text between the frontmatter and the first heading) with preamble: true or heading: ""; requires expected_sha256
next_id yes allocates the next PI-### (any prefix and width) and optionally creates <folder>/<id> <name>.md, {{id}} substituted
build_index yes writes a generated index between markers (see Generated indices)
refresh_index / refresh_all_indices yes regenerate from the specs stored in the markers; no write when nothing changed
write_log the audit log, newest first: time, tool, vault, path, client, reason, discussion, sha before and after; filters vault, path, client, discussion, since, until (UTC, 2026-10-08 or 2026-10-08T14:30)
open_discussion yes creates Discussions/D-### <topic>.md with subjects, participants and P-1 (see the Discussions page)
post yes appends the next post to a thread
read_discussion posts as JSON (since_post for only what is new), integrity check, and outcomes
discussion_status each claim, challenge and question: answered, conceded, retracted, contested, unchallenged or open
awaiting challenges and questions to an author's posts that the author has not replied to
conclude_discussion yes verdict post, status concluded; gated on contested challenges; returns the verdict's link
mark_unresolved yes ends a thread without agreement for a human decision
record_decision yes settles an unresolved thread with a decision post
list_discussions threads, filtered by vault, status, subject, needs_decision
decision_queue every unresolved thread in every vault, oldest first

append_to_note and set_frontmatter accept an optional expected_sha256. Every write returns sha256_before, sha256 and changed; an edit that produces identical bytes writes and logs nothing.

Line endings: no write normalises a note's line endings. Every edit leaves the bytes outside the edited span untouched, and inserted text takes the note's own ending (CRLF when its first line break is CRLF, else LF); new notes are LF. Test writes_keep_crlf_files_crlf runs every write tool over a CRLF note.

Every write cites a reason

Every write tool except open_discussion and post has a required reason argument: why the change is being made. (open_discussion and post record their post's kind, author and the start of its body as the reason.) Every write tool except the thread tools also takes an optional discussion (perf:D-004 or perf:Discussions/D-004 ....md): the thread the change comes from. The server checks the thread exists, stores it on the audit row and the JSONL line, and a short reason that just points at the thread ("per perf:D-004") is enough. A thread's read_discussion then lists those writes as outcomes, and write_log {discussion: "perf:D-004"} finds them. The reason is checked before anything is read or written, and the call is refused if it is missing, not a string, blank, under 12 characters after trimming, over 500 bytes, more than one line, or a stock placeholder (update, fix, n/a, none, edit, minor changes, no reason given, not applicable, ... compared case- and punctuation-insensitively; the list is PLACEHOLDERS in src/tools.rs). The trimmed reason is stored in the writes row and the writes.jsonl line, and never written into the note (an append_history line is exactly the text given). write_log answers "why did this note change?": write_log {vault: perf, path: "Ideas/PI-014 ....md"}.

The perf-vault workflow ("How to add an idea")

  1. next_id {vault: perf, folder: Ideas, prefix: "PI-", name: "Short name", content: "---\nid: {{id}}\n..."} takes the number and creates Ideas/PI-NNN Short name.md in one step. Two agents can never get the same id: allocation runs under the database write lock, skips any number a file in the folder already uses (by hand or by a writer outside this server), and the file is created exclusively, retrying on a clash.
  2. Status change: set_frontmatter {values: {status: "parked", tags: [...]}} then append_history {text: "parked: measured +0.2 ms (PR #123)"}. Nothing is removed; parking is a frontmatter change.
  3. Index and area lines: either append_to_note / replace_section on the hand-written tables, or (once the tables are converted, see Generated indices) refresh_all_indices.
  4. Evidence on an existing idea: append_to_note or replace_section with the sha from read_note.

Repeats, line ranges and anchors

With the hooks on, the PreToolUse hook names the session and agent behind the next atlas call. A read tool called again by the same agent with the same arguments then answers unchanged since your call #N with these arguments, or, when the answer changed and the changed lines are under half of it, only those lines (+ line new, - line gone). fresh: true on any call gives the whole answer, and every such reply says so. Without the hooks there is no agent identity, and repeats are compared per server process: one server serves a session and its subagents, so a subagent may be told unchanged since call #N of an answer only its parent holds, and follows the reply's fresh: true to get it. Once a PreToolUse hook has been seen, a call it did not announce is never answered by reference. A PreCompact hook forgets the session's answers. The work-queue tools (decision_queue, awaiting, journal_status, next_id, the discussion reads, misses) and recall {lane} always answer whole; whole for journal_status means every active lane and the idle count (all: true for every lane).

read_note takes lines (A-B, A- or A, from 1) or budget_tokens (whole lines up to about that many tokens, the first line always); the header line names the lines shown, and a cut ends with +N more lines (lines=A-B). Search hits already carry vault:path:line. A record recall {key} reads, and a whole record in a recall {query} answer, carries @L1234 (the line of the export file its key names) or @path:line. Pointers do not by default: with recall.pointer_anchors on, each ends with @src:path:line, and read_note {vault: src, path, lines} reads that part of the vault or source file. Measured on the memory evaluation, the anchors cost more tokens a question than the line reads they enable save (see the configuration reference). read_note reads a source's files as well as a vault's notes.

Clone this wiki locally