Skip to main content
Glama
AkashGoenka

coldstart

by AkashGoenka
OverviewSchemaRelated ServersScoreDiscussions
TypeScript

Two layers, one tool:

  • The notebook (coldstart kb) — durable, agent-written notes about how this codebase actually works: what a file is for, how a flow spans files, which invariants hold. Captured after real tasks, recalled when a later task matches, and kept honest by the index — every note is anchored to real files, and a note whose evidence drifted is flagged, not served as truth.

  • Navigation (coldstart find / coldstart gs) — a fast static index over file paths, symbol names, exports, and the import/call graph. It answers "which files are relevant to this task?" in milliseconds, with checkable evidence instead of a similarity score.

No embeddings, no model to run, no service to babysit. Agents are already good at reading and reasoning about code; what they waste tokens on is finding the right file and re-deriving what the last session already figured out. coldstart does those two parts and gets out of the way.

Install

Requires Node.js 18+.

npm install -g @cstart/coldstart
cd your-project
coldstart init   # coldstart.md + client wiring + notebook + background index warm-up

A single coldstart init does everything — navigation and the notebook. It asks two things — the experience (cli, recommended, or mcp) and the client — then writes the agent-facing guidance into the client's own rules file (as an imported coldstart.md for Claude Code; inlined directly for Cursor and Codex, which don't resolve @file references), wires the client, and sets up the notebook (skeleton, git wiring, and — for Claude Code, Codex, and Cursor — the capture/recall hooks). Pass --experience / --client to skip the prompts. The client is never auto-detected; you always pick it.

  • Claude Code → writes coldstart.md and ensures CLAUDE.md imports it via @coldstart.md, and registers both the find/gs search hooks (a PostToolUse nudge + a PreToolUse find-dedup guard) and the notebook recall/capture hooks (UserPromptSubmit + Stop/SubagentStop) in .claude/settings.json — merged into any existing settings, never overwriting them. The mcp experience also writes .mcp.json.

  • Codex → embeds the full coldstart guidance inline in a marked block in AGENTS.md (Codex has no @file include, so there's no separate coldstart.md), refreshed in place on re-run, and registers Codex-specific navigation plus notebook hooks in .codex/hooks.json. The capture hook understands Codex rollout and subagent transcripts. The mcp experience also writes [mcp_servers.coldstart] into .codex/config.toml.

  • Cursor → writes .cursor/rules/coldstart.mdc — an always-applied rule that carries the full coldstart guidance inline (Cursor doesn't reliably resolve @file references in rules), rewritten on every init — and registers Cursor-specific navigation plus notebook hooks in .cursor/hooks.json (a preToolUse find-dedup guard, a postToolUse nudge, beforeSubmitPrompt recall, and stop/subagentStop capture — merged into any existing hooks). The capture hook parses Cursor's own conversation transcript. The mcp experience also writes .cursor/mcp.json.

  • Other → writes coldstart.md only, and prints the wiring directions (plus the MCP server entry for the mcp experience).

On every client, the PostToolUse hook also delivers the "Edited together" signal without waiting to be asked. Once an agent has edited two different files, it names the files that git history says keep changing alongside them — the sibling implementation, the test in another language, the doc that drifts. Agents don't reliably run gs before editing, so the signal only reached them if they went looking; this puts it in front of them at the edit. It's advisory: the message says outright that the relation is a habit rather than a code dependency, and asks the agent to check rather than to change anything. Each file is named at most once per task, and the list resets whenever you send a new message.

init then warms the index in the background, so your first lookup is instant. Re-running init is safe — it never duplicates entries.

Upgrading

npm install -g @cstart/coldstart@latest
coldstart init   # re-run in each project to refresh coldstart.md

A version stamp in the keeper's lockfile makes the old background keeper shut down on the next lookup; a fresh one spawns from the new binary. No manual restart needed.

NOTE

Migrating from coldstart-mcp: the package was renamed coldstart-mcp → @cstart/coldstart at 2.0.0 (the CLI is now the primary surface). coldstart-mcp is deprecated but still installs; switch with npm uninstall -g coldstart-mcp && npm install -g @cstart/coldstart && coldstart init. The coldstart-mcp binary name is kept as an alias, so existing MCP configs keep working.

Removing coldstart

init writes per-repo wiring that a global npm uninstall can't reach (npm fires no reliable uninstall hook, and it has no record of which repos you init'd). So — like husky — coldstart ships an explicit reverse:

coldstart unwire          # strip coldstart's wiring from this repo (notebook kept)
coldstart unwire --purge  # also delete .coldstart/notebook/ and its git plumbing

unwire removes only coldstart-owned markers from the files init touched — hook entries, the @coldstart.md import, the AGENTS.md block, the MCP server entry, and files coldstart fully owns (coldstart.md, .cursor/rules/coldstart.mdc) — never your own content in shared files. It sweeps all four clients, is idempotent (a second run reports everything already gone), and keeps the notebook by default since it's committed, shared data. Run it in each project first, then npm uninstall -g @cstart/coldstart to remove the package.

Related MCP server: Stoa

The notebook

A repo-local knowledge base written and read by agents, in .coldstart/notebook/:

coldstart kb search tile save lifecycle   # plain task words, symbols, or file names
coldstart kb lookup src/models.py Tile    # everything known at one exact address
coldstart kb write spec.json              # the write gate (two-phase dedup)
coldstart kb commit                       # publish notes to git, nothing else rides along
coldstart kb view                         # open a single-file HTML browser of the notebook
coldstart kb repair                       # worklist of notes that are written but unfindable
coldstart kb repair-aliases                # worklist of aliases that may no longer be true
coldstart kb status / lint / render / init / migrate

What a note is. Three shapes: a file note (what a file is for — a single summary, or per-symbol facets for hub files), a flow note (a cross-file story: ordered steps, invariants), and a lesson (a trap, rule, bug-cause, rationale, or confirmed absence). Every note carries anchors — concrete file paths and symbols its claims rest on.

Where notes reach the agent. Three surfaces, no new habits required:

  1. Summary: lines on find results — a past agent's verified overview of a file, right where the file ranks. [fresh] means the file is byte-identical to when the summary was verified — the agent can rely on it without re-reading the file.

  2. Recall at prompt time (optional hook) — notes whose titles, aliases, or anchors match the incoming prompt are surfaced as a compact title + gist + path block, hard-capped, framed as reference data. Nothing matches → nothing injected.

  3. kb search / kb lookup — a search engine over the notebook for mid-task vocabulary changes, and an exact-address lookup (path [symbol]) before editing a file.

Why it can be trusted. This is the part that took the design work:

  • Freshness is mechanical, not hoped-for. Every anchor is stamped with a content hash at write time; the index re-checks stamps as the code changes. A drifted note renders [evidence changed: <path>] and the guidance says re-verify — stale knowledge degrades into a labeled hypothesis instead of a confident lie.

  • The log is the truth. Notes live in an append-only .raw event log (commit it — merges are unions, so parallel branches of notes reconcile without conflicts). The Markdown notes are derived, regenerated mechanically, and gitignored.

  • Writes go through a gate. A new note's concept is first searched against existing notes — the agent must explicitly merge into a match (--into <id>) or declare it new (--new). Duplicates are gated at write time, not cleaned up later.

  • Concurrent sessions are safe. Multiple agents can write at once: per-note append-only logs, exclusive creation for new note ids (a same-moment duplicate becomes two visible notes, never a silent merge), lossless merging for shared file notes, and atomic renders (a reader never sees a half-written note).

  • Corrections happen in-session. If an agent finds a note wrong while the evidence is in its context, the guidance tells it to fix or retract the note right then — no better-placed future agent exists.

Setup: the notebook comes with coldstart init — no separate step. It creates the notebook skeleton, sets union-merge for the logs, and (on Claude Code, Codex and Cursor) wires the two hooks — capture at session end, recall at prompt time. (coldstart kb init still exists as an alias if you want to (re-)wire just the notebook.) Other hosts can drive the notebook without the hooks: via the full kb CLI, or — for no-shell clients — the kb_search / kb_lookup / kb_write / kb_status / kb_repair / kb_repair_aliases MCP tools.

Language-agnostic. The notebook's freshness machinery is content-hash based, so it works on any codebase — including languages the navigation index doesn't parse. Where the index does parse, notes additionally get symbol-level freshness.

NOTE

The notebook is young. What's verified today: notes written by agents in real sessions checked out accurate against the code; the stale-note loop closes end-to-end (flag → re-read → correction); capture, recall, and concurrent writes hold up under stress. The bet — stated as a bet — is that a corpus like this compounds over a repo's lifetime: the second time any question comes up, the answer is one Read away instead of a re-derivation.

Navigation: the two operations

What it answers

Replaces

find <terms>

"Which files are about this?" — ranks files by how many of your query terms they cover (filenames, path segments, exported symbols, plus a repo-wide name-reference pass).

a flurry of grep/glob while orienting

gs <file>

"What is this file?" — top-level symbols with line ranges, who imports it, who calls each symbol, and name-related neighbors.

reading a whole file just to learn its shape and usage

The intended flow: find a concept → pick the best path → gs that file for its shape and who uses it → Read only for the implementation inside a method body. Notebook summaries ride along on find results, so often the orientation step answers itself.

flowchart LR
    A["coldstart find<br/>which files?"] --> B["coldstart gs<br/>what is it? who uses it?"] --> C["Read<br/>just the method body"]
    class A,B cold
    class C warm
    classDef cold stroke:#16708f,stroke-width:2px
    classDef warm stroke:#c26714,stroke-width:2px

find — locate the files for a concept

coldstart find auth session cookie
TIP

Pass every salient identifier from your task — the symbol, the domain noun, the rare token you half-remember — not one distilled keyword. find ranks files by how many of your terms each one covers and shows, per file, which terms it defines vs. imports and a preview of the lines where they cluster. Often that's enough to answer without opening anything.

Speed-wise, find competes with raw grep: its repo-wide reference pass runs on ripgrep — yours from PATH, the bundled copy, or an editor's (COLDSTART_RG overrides) — with git grep/grep fallbacks, and the ranked page comes from the pre-built index, not a scan.

Flags: --path GLOB (scope; comma-combine, ! excludes) · --tests (include test files) · --via (show name-reference relations) · --json

gs — drill into one file

coldstart gs src/auth/service.ts

Returns the file's symbols (with line ranges), its 1-hop internal imports, who imports it, and per-symbol cross-file callers — in one call. This is the answer to "who uses this file / who calls this symbol"; it is not a grep.

Flags: --symbol a,b (deliver named method bodies inline) · --match TERM (filter a god-file to one area; a|b = OR, /regex/ = regex) · --view symbols|imports|importers|callers · --json

graph — see the whole repo at once

coldstart graph

For humans, not agents. Writes one self-contained HTML file and opens it: every indexed file is a point on a sphere, positioned by directory, and clicking one opens a 2D view of everything it is connected to — with each relation named (imports, calls save(), load(), edited together · 13 of 42 commits, same note · <title>). Click a neighbour to open its connections; click one of those and the view slides along, so you always see two levels rather than an ever-growing hairball.

No dependencies. The page is HTML, CSS, and a canvas script with your repo's data baked in — no server, no build step, and nothing leaves your machine. Mail it, drop it in a gist, open it on a plane. Try it on coldstart's own codebase.

Flags: --out PATH (default .coldstart/graph.html, gitignored for you) · --no-open · --json

Batch independent lookups in one shell call

coldstart find auth; coldstart find 'session cookie'; coldstart gs src/auth/service.ts

Two ways to call it, identical output

coldstart ships as one binary with two front doors:

  • CLI (primary) — coldstart find … / coldstart gs … / coldstart kb …. For any shell-capable agent (Claude Code, Cursor, terminal use). This is the fast path.

  • MCP (for no-shell clients) — the find and gs tools, plus the notebook as kb_search / kb_lookup / kb_write / kb_status / kb_repair / kb_repair_aliases, all byte-identical to the CLI. For clients like Claude Desktop that have no shell. (kb commit stays CLI/human-only — publishing notes to git is never an agent action.)

Same engine, same index, same results. Pick whichever your agent can reach.

It works best with Claude Code, Codex, and Cursor: all three get platform-specific find/gs hooks and notebook recall/capture hooks from coldstart init. Any other client gets coldstart.md plus printed wiring directions.

Bring your own semantics

coldstart has no embeddings, no generated summaries, no semantic layer computed at index time — on purpose. The semantic layer is the agent. Every consumer is already a frontier model; pre-computing meaning at index time only duplicates that, worse and stale. So the index keeps what's cheap to keep exact — paths, symbols, exports, the import/call graph — and returns why each file ranked.

The notebook is the same philosophy applied to memory: coldstart still computes no meaning of its own. It stores, anchors, and freshness-checks the meaning agents author — written at task time, by the reasoner that had the full context, about the question that actually mattered. The full argument is in PHILOSOPHY.md.

How the index stays fresh

coldstart is one keeper, thin readers:

flowchart TD
    K["keeper — coldstart --daemon<br/>watches repo, patches/rebuilds, saves cache<br/>serves nothing"] -->|debounced save| C[("on-disk cache")]
    C --> F["coldstart find<br/>reads cache, prints"]
    C --> G["coldstart gs<br/>reads cache, prints"]
    C --> M["MCP server<br/>reads cache, stdio"]
    class K cold
    classDef cold stroke:#16708f,stroke-width:2px

  • A single keeper process per repo watches the filesystem and keeps the on-disk cache current. It does not answer queries.

  • The CLI readers (find/gs) and the MCP server are stateless readers over that cache. The first reader for a repo lazily spawns the keeper, so even uncommitted edits stay live.

  • Readers never build the index. On a cache miss they wait for the keeper's build (progress to stderr) instead of silently kicking off a multi-minute build inline — or three of them concurrently.

  • No HTTP, no ports, no bridge. The keeper logs to ~/.coldstart/daemon/<root>.log and exits when its lockfile is removed.

There is no cache TTL. The index is never discarded for being old — it's kept correct instead:

  • While the keeper runs: edits are debounced (400 ms), then patched incrementally (~2–5 ms/file, up to 30 files or 20% of the repo, whichever is larger) or trigger a background full rebuild above that (served from the last good index until the swap). The cache re-saves ~5 s after edits settle, in atomic generations — a reader can never load a half-written mix of old and new.

  • When the keeper starts: it reconciles — stat-checks every indexed file against its stored fingerprint (~150 ms even at 16k files) plus a git diff against the indexed HEAD — and patches exactly what changed while nothing was watching. A branch switch that used to force a 96-second rebuild on a 16k-file repo is now a ~3-second patch.

  • As a backstop: every patch is lint-checked against index invariants (a violation triggers an automatic rebuild and lands in a repair log that status shows), and a rotating fingerprint audit after each save catches watcher-missed events.

The keeper also stamps the notebook's anchor freshness (a small sidecar, derived single-flight) — the notebook never loads the code index to answer a query.

Lifecycle commands

coldstart status              # keepers on this machine: alive? fresh? last patch/rebuild/save? repairs?
coldstart restart             # kill the current repo's keeper (respawns on next lookup)
coldstart restart --root DIR  # kill a specific repo's keeper from anywhere
coldstart restart --all       # kill every keeper
coldstart index               # build + save the cache once, up front (single-writer prep)

restart is the right move whenever anything feels stale — a fresh keeper reconciles on start, so it comes back correct, not just alive. status answers "is my index fresh, and why?": liveness, cache age, the keeper's last reconcile/patch/rebuild/save stamps, and the tail of the repair log — no network probe.

Supported languages

Navigation index: TypeScript, JavaScript, JSX/TSX, Vue, Svelte, Astro, AngularJS 1.x, Java, Kotlin, Ruby (Rails-aware: has_many/belongs_to associations, routes.rb resources, controller↔view edges), Python (Django convention edges), Go, Rust, C#, PHP (Laravel convention edges), C++, Groovy (incl. Gradle DSL), GraphQL, YAML, TOML, XML, and .env files.

Not indexed: Swift, Dart — no extension mapping; these files are not walked or parsed.

The notebook works regardless — its freshness stamps are content-hash based, so notes on a Swift repo are as trustworthy as notes on a TypeScript one (they just lack symbol-level freshness detail).

When not to reach for it

  • A literal string / phrase / regex inside file bodies → Grep.

  • Reading an implementation → Read, after gs gives you the shape.

  • find says "no indexed file contains any of […]" → those identifiers aren't in the repo. Don't grep spelling variants.

Development

npm install
npm run build
npm test

# run a query from your build:
node dist/index.js find auth --root .

# run the MCP server in a single process (no background keeper) for debugging:
node dist/index.js --root . --no-daemon

See PHILOSOPHY.md for why coldstart computes no semantics of its own, ARCHITECTURE.md for the index pipeline, process model, and notebook internals, and TROUBLESHOOTING.md for recovery procedures.

Limitations

  1. It's a routing layer plus an agent-written notebook — no semantic analysis or generated code summaries. This is deliberate: the consuming agent is the semantic layer (see PHILOSOPHY.md).

  2. gs callers are one-hop and file-scoped. Member-expression calls (this.method(), api.method()) aren't cross-file resolved; named function/constant calls are. Chase further hops by calling gs on the caller files.

  3. Dynamic/computed imports (import(variable)) and runtime-DSL references (polymorphic associations, gem/reflection-backed models) stay unresolved.

  4. Hidden directories and files over 1 MB are skipped by the index.

  5. The keeper is per-repo and per-machine — no sharing across projects or hosts. The notebook does travel: its .raw logs are committed and union-merge across branches and machines.

  6. Notebook quality is bounded by what writing agents actually read — notes are accurate about what they state, but a note is not a proof of completeness.

Writing

Longer pieces on the problems behind this tool — what agent sessions actually cost, and what happened to the design when the measurements disagreed with the plan.

License

MIT — see LICENSE.

coldstart MCP server

Available Tools

8 tools
findA

Locate the files relevant to a task. Pass query = EVERY salient identifier from the task (symbol names, domain nouns, the rare token you half-remember) — not one distilled keyword. Recall is bounded by the terms you give: a one-token query cannot out-rank lookalikes, so over-supply rather than under-supply. Reach for find BEFORE Read/Grep/Glob.

HOW IT WORKS: find greps every term across the repo body AND matches declared names (filenames, path segments, exported symbols), then ranks files by DISTINCT-TERM COVERAGE — the file that covers MORE of your query rises above its lookalikes. This catches body-level matches (nested defs, dynamic refs, string literals) that a declared-name index misses.

OUTPUT: a ranked page. Top files get an inline preview — their indexed symbols (with line ranges) plus the body lines where your rare terms CLUSTER (def/class/assignment lines first), so you often answer WITHOUT a follow-up Read. Lower-ranked files list as bare paths. Prose/doc and stylesheet matches are partitioned into secondary lists so they do not crowd out source. Related files (sharing a rare identifier with a top hit, no import edge between them) are surfaced as first-class neighbors.

NAMING: case- and separator-insensitive (LoadStaging ≡ load_staging). It does NOT expand synonyms or plurals for you — that is your job: if the concept could be named two ways, pass both tokens.

AFTER THE RESULT:

  1. A path + its inline symbols/preview answer the question → done, no Read needed.

  2. Path looks right but you need shape/usage → gs on it (symbols + imports + per-symbol callers + importers in one shot).

  3. "no indexed file contains any of [...]" → those identifiers do not exist in the repo; reformulate or grep for a phrase/regex find cannot index. Do not grep spelling variants of a token find already reported absent.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSpace-separated identifiers for the thing you are looking for — pass every salient token from the task, not one keyword. camelCase/snake_case both accepted. More discriminating tokens = sharper ranking.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully describes behavior: how it greps body and declared names, ranking by distinct-term coverage, output format (inline preview vs bare paths), partitioning of prose/stylesheets, and naming insensitivity. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is thorough and well-structured with sections (HOW IT WORKS, OUTPUT, NAMING, AFTER THE RESULT). It is slightly verbose but every sentence adds value, and the key points are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the tool and lack of output schema, the description is exceptionally complete, covering input, mechanism, output format, naming conventions, synonyms, and post-result instructions. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter, but the description adds significant value beyond the schema by explaining effective query construction (pass all salient identifiers, more tokens = sharper ranking) and the underlying search mechanism.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Locate the files relevant to a task.' It uses a specific verb and resource, and explicitly distinguishes from siblings by advising 'Reach for find BEFORE Read/Grep/Glob.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage guidance: pass all salient identifiers, not one keyword; explains when to use (before Read/Grep/Glob) and when not to (do not grep spelling variants of absent tokens). Also includes post-result actions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

gsA

Drill into a known file. Returns these sections as compact text:

  • Symbols — top-level + per-class methods (name, kind, line range, extends/implements). With cross-file callers attached per exported symbol (inline if 1 caller; newline-per-caller block if ≥2). For huge files (>20 symbols, no match), symbols are reordered by caller count (most-used first) and truncated to top 15.

  • Imports — 1-hop internal outbound dependencies (library imports stripped).

  • Importers — 1-hop reverse: files in this repo that import this one. With match, additionally lists EVERY indexed file (importer or not, any language) whose CONTENT references the matched term even when its filename does not (a registry, admin, or config file using the symbol — or a frontend file referencing a backend name). That subsection IS the complete "who uses " answer: it is exhaustive over indexed content, so a subsystem absent from it does NOT use the symbol — do not grep to enumerate or re-verify use-sites, and do not keep hunting in subsystems the section rules out.

  • Edited together — files that keep changing in the SAME COMMITS as this one, from git history, shown with the count as evidence ("changed together in 14 of this file's 17 commits"). This is a HABIT, not a dependency: no import or call edge connects them, so do not go looking for one. It is frequently what an edit here forgets — a sibling implementation with a shared interface, a test in another language, a doc or template that has to stay in sync. Files connected to this one by an import edge are omitted here, so everything shown is a file the graph did NOT give you. Rendered in EVERY view, including a narrowed one. Absent = no git history yet (a new file, a shallow clone) or nothing pairs strongly enough.

  • Related — files sharing rare identifier/string-literal tokens with this file (with match: with the matched symbols' code region), shown only when NO import edge connects them. These are name-reference relations the import graph cannot see — Django migrations↔models, config-by-name registration, cross-language (JS↔Python) pairs. Treat them as first-class neighbors: the shared token shown is the reason they are related. Rendered in EVERY view, including a narrowed one. Use this AFTER find surfaces a candidate file. This is the right tool for "who uses this file" / "who calls this symbol" — no separate call needed.

view controls which sections you get (default full = all of them). symbols, imports, importers, callers each return one section in isolation when you want a byte-light answer.

For god-files (large classes, large routers, large config modules), pass match to filter symbols/imports/importers/callers to one area — e.g. match: "auth" or match: "/^handle/". Substring is case-insensitive; wrap in slashes for regex.

Prefer this over Read when you need shape, neighbors, or usage. Reach for Read only for implementation details inside a method body. If you have called gs on 5+ files for one question, you are enumerating — go back to find with a sharper path glob or a different concept token instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
viewNoWhich sections to return. Default "full" = symbols (with inline callers) + imports + importers. Use one of the narrower views to halve or quarter the output when you know what you need: "symbols" (shape only, no callers), "imports" (outbound only), "importers" (inbound only), "callers" (per-symbol cross-file callers in expanded form, no symbol shape).
matchNoFilter all sections by name. Substring (case-insensitive) by default; use `|` to OR substrings (`match: "resource|tile"`); wrap in slashes for regex (`match: "/^handle/"`). Use this on large/god-files to avoid a wall of output — e.g. `match: "tile"` on a big models.py reduces output to just tile-related symbols, their callers, and matching imports/importers.
symbolNoDeliver the BODY of the named symbol(s) inline, sliced from their indexed line range — so you read a method WITHOUT a Read at a guessed offset. Comma/pipe-separate names (`serialize,restore_state`). A bare name matches the method (`serialize` → `Graph.serialize`). Each body is followed by `callers:`/`calls:` POINTERS (file + line range) so the next hop is one more `gs --symbol` call, not a windowed Read. Use this the moment a file’s symbol list shows the method you need — it replaces the read-at-offset hunt on god-files. If the name is NOT a declared symbol (a runtime/template-injected value, a string key, a config token), it falls back to an in-tool GREP: returns the body lines where the token appears, with context — so you never shell out to grep. Overrides `view`/`match`.
file_pathYesRelative path to the file (e.g. "src/auth/service.ts"). Suffix matches are accepted.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden — and it delivers: symbol reordering/truncation beyond 20 symbols, the exhaustive 'do not grep' semantics of importers under match, and the 'Edited together is a HABIT, not a dependency' caveat with an explicit 'do not go looking for one' instruction. It also discloses absence conditions (no git history, weak pairing), rendering scope ('Rendered in EVERY view'), and the in-tool grep fallback for non-declared symbols. No annotation contradiction is possible since no annotations exit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well front-loaded with a one-sentence purpose ('Drill into a known file. Returns these sections as compact text:') and a scannable bullet structure for the five sections. The length is largely justified by dense anti-error guidance, but it loses a point for redundancy: 'Rendered in EVERY view, including a narrowed one' appears twice, and parameter prose overlaps the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with no annotations and no output schema, this is complete: every section type is defined, non-obvious absence conditions are explained, all four parameters are documented, and explicit stop/continue heuristics are given. An agent could select, invoke, and interpret results correctly without any additional lookup.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds value beyond the schema by explaining when each parameter matters — match for god-files with concrete exaples ('match: "auth"', '/^handle/'), and symbol as a replacement for the read-at-off-set hunt, including its override behavior and grep fallback. Some duplication with the schema's own parameter text remains, so it stops short of 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a concrete verb+resource ('Drill into a known file') and enumerates the exact output sections (Symbols, Imports, Importers, Edited together, Related), thoroughly scoping what the tool does. It also differentiates it from siblings and the Read alternative by positioning it as the follow-up to find and as 'the right tool for who uses this file / who calls this symbol'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('Use this AFTER find surfaces a candidate file', 'Prefer this over Read when you need shape, neighbors, or usage') and when-not-to ('Reach for Read only for implementation details inside a method body'). It even names a stopping rule — after 5+ gs calls for one question, go back to find with a sharper glob — an unusually precise guard against enumeration.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kb_lookupA

Read everything the NOTEBOOK knows at ONE exact address — the file you are about to edit. Address-keyed, not concept-keyed: unlike kb_search (fuzzy, ranked), this filters notes by exact anchor path, so it is exhaustive at that path. Returns the file note's facets, every cross-file flow that passes THROUGH this file, and lessons/absences anchored here — each with a live freshness stamp against the current code.

Reach for this the moment you have DECIDED on a file and are about to modify it: it surfaces the flow you might break, the absence you are about to violate, the rationale for the code's shape. A clean result ("nothing known here") is itself a positive signal — proceed. Anything marked [evidence changed: ] drifted since it was verified; re-verify before relying on it, and correct the note with kb_write if it proved wrong. Pass an optional symbol to narrow to one top-level symbol at that path.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesExact repo-relative path of the file (e.g. "src/auth/service.ts").
symbolNoOptional top-level symbol name to narrow the lookup to notes anchored at that symbol.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description fully discloses behavior: returns facets, cross-file flows, lessons/absences with freshness stamps, explains drift detection, and notes the optional symbol narrowing. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured and front-loaded, but slightly verbose. Every sentence adds value, but could be tightened. Still concise enough for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description provides comprehensive context: return types, freshness stamps, drift warnings, and usage scenarios. Missing output format is acceptable as it's implied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of params with descriptions, but the description adds meaning: 'Address-keyed, not concept-keyed' for path, and 'narrow to one top-level symbol' for symbol, plus context on exhaustive lookup.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads notebook knowledge at a specific file path, using 'Read everything the NOTEBOOK knows at ONE exact address'. It also distinguishes itself from kb_search by specifying exact lookup vs fuzzy search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance: 'Reach for this the moment you have DECIDED on a file and are about to modify it.' It contrasts with kb_search and explains how to interpret results (clean result = positive signal, re-verify drifted stamps).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kb_repairA

List the notebook notes that are WRITTEN BUT UNFINDABLE — missing the fields a note cannot be retrieved without (identityAliases, anchor symbols, a flow's verified paths). Notes written before those fields were required are correct but unreachable, and this is how they get found.

Returns a worklist, never a change: repairing is your work, because every gap needs a judgement about the code (which words a reader would search for, which symbols the note is actually about, which files you can honestly claim to have read). Fix each one with kb_write, passing the note's id — fields merge, so nothing already in the note is lost.

A clean notebook returns "Nothing to repair here." Run it when the user asks to repair, fix, or clean up the notebook.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It does well: explicitly states the tool 'Returns a worklist, never a change', describes the empty-notebook sentinel ('Nothing to repair here.'), and clarifies that notes written before the fields were required are 'correct but unreachable' — disclosing the tool's non-destructive diagnostic nature. It doesn't over-claim error/rate behavior, but the safety profile (read-only worklist) is clearly conveyed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three well-organized sentences: purpose, what-it-returns/next-steps, and usage trigger. Every sentence earns its place with concrete, actionable detail. The key information (returns worklist, never a change; fix with kb_write passing id; merge semantics; empty-notebook sentinel) is front-loaded and complete.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter diagnostic tool with no output schema, the description is complete. It covers what is found, why notes are unfindable, what the tool does NOT do (doesn't repair), how to fix each issue (kb_write + id + merge), the clean-notebook output, and when to run it. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters and schema coverage is 100%, so there are no parameters to document. Per the rubric, 0 params = baseline 4. The description adds no param-specific detail because none is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb+resource ('List the notebook notes') with a clear scope ('WRITTEN BUT UNFINDABLE'), and gives concrete examples of what makes a note unfindable (missing identityAliases, anchor symbols, verified paths). It clearly distinguishes this from siblings by framing it as a diagnostic/worklist tool rather than a search or write tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to run it ('when the user asks to repair, fix, or clean up the notebook') and contrasts with kb_write ('Fix each one with kb_write'). It also warns that repairing is the user's (agent's) work, requiring judgement about code, and clarifies the tool returns a worklist never a change. The merge semantics are stated so the agent knows replays don't lose data.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kb_repair_aliasesA

List file/flow notes whose identityAliases may no longer describe them — a DIFFERENT problem from kb_repair: that one finds notes with NO aliases at all, this one is for aliases that exist but have gone stale (a note rewritten several times can carry words that were really symptoms of an earlier write, not stable facts). Paginated 10 notes at a time.

Each entry shows the current (capped) identityAliases AND the full historical union hidden past the render cap — read both before retracting anything, because dropping a visible alias can resurface an older hidden one on the next fold. Re-read the note's code, then reconcile via kb_write (retract stale entries, re-put the rest) — never mechanically, every judgement needs the current code. End every note's kb_write with aliasesVerified:true on it, even when nothing changed — that is what stops it reappearing; without it the same note resurfaces on your next call.

Returns "No file/flow notes to reconcile." when done. Once a batch is marked aliasesVerified, call again with NO offset (or offset 0) — verified notes drop out of the list on their own. Do not increment offset yourself across a reconciling pass: the list shrinks as notes get marked, so a fixed offset (including a stale more.nextOffset) silently skips whatever shifted into that position. offset/more.nextOffset still work for browsing the list WITHOUT marking anything — just not as a way to advance while reconciling.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoNotes per page. Defaults to 10.
offsetNoPagination offset (0-based). For browsing only — do NOT increment this across calls once you start marking notes aliasesVerified, since the eligible list shrinks as you go. Leave at 0 (or omit) and just call again; reviewed notes fall out automatically.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and delivers richly: explains the pagination shrink behavior, the aliasesVerified mechanic that stops reappearance, the resurfacing of hidden aliases on the next fold, and the exact return string 'No file/flow notes to reconcile.' Also warns about stale nextOffset silently skipping entries. Exceptionally transparent about behavioral edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is thorough but densely packed with genuinely useful operational detail. It front-loads the core purpose first, then branches into reconciliation workflow and pagination caveats. Each sentence earns its place, though it's long enough that a lighter-weight summary of the critical warnings could improve scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema and no annotations, this description compensates fully. It covers the return value ('No file/flow notes to reconcile.'), pagination behavior, workflow dependencies (kb_write, aliasesVerified flag), and edge-case pitfalls. For a complex reconciliation tool with no structured metadata support, this is exceptionally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds meaningful value beyond the schema: it explicitly warns about the offset pitfall ('do NOT increment this across calls once you start marking notes aliasesVerified') and clarifies that offset is for browsing only, while reconciled notes auto-drop. This is useful semantic depth beyond what the schema description states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states precisely what the tool does: lists file/flow notes whose identityAliases have gone stale, explicitly distinguishes it from kb_repair (no aliases at all vs. stale aliases). The verb 'List' plus the specific resource (file/flow notes with stale identityAliases) is specific and immediately differentiated from the sibling kb_repair.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use vs. when-not-to: 'a DIFFERENT problem from kb_repair' naming the exact alternative. Also gives explicit operational guidance: don't increment offset while reconciling, call again with offset 0, never retract mechanically, end every kb_write with aliasesVerified:true. This is exemplary usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kb_statusA

Notebook overview: how many notes exist (by type: file/flow/lesson), how many are flagged stale (their anchored files drifted since verification), and how many are superseded/retracted. Pass paths (array of repo-relative paths) to instead list the notes anchored at each of those exact paths with their freshness state — a quick "is anything known here?" check across several files at once.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathsNoOptional repo-relative paths. When given, returns per-path anchored notes + freshness instead of the whole-notebook overview.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes what the tool returns in both modes (notes by type, stale counts, per-path freshness). No annotations exist, so description carries burden; it is transparent about the query nature, though it does not explicitly state it is read-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each covering a distinct mode (no paths vs. with paths). No wasted words; highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description clearly specifies what is returned for both invocation modes (overview counts, per-path freshness). For a tool with one optional parameter, this is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides a description for the single parameter 'paths'. The tool description adds context by explaining the behavior difference and the concept of 'anchored notes' and 'freshness', adding value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool provides a notebook overview with counts by type and stale/superseded status, and describes an alternative mode for specific paths. Distinguishes from siblings like 'kb_search' (likely searches content) by focusing on status and anchoring.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to pass the 'paths' parameter ('a quick is anything known here? check') and implies using without paths for a full overview. Does not explicitly mention when not to use or alternatives among siblings, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kb_writeA

Save or correct NOTEBOOK notes after finishing real work here — you have the files in context, so no future agent is better placed to record what you learned. Write a file note (what a file is for), a flow note (how a task spans files), or an absence lesson (a confirmed "there is no X"). Pass specs (an ARRAY of specs) to write ALL your notes in ONE call — malformed notes are reported together instead of one hiding the rest, and the result ends with a coverage line naming any worked files still without a note; pass spec (a single object) for a one-off. Also the tool to FIX or RETRACT a note you used that proved wrong: op: "put" replaces; op: "retract" with target: {kind: "note"} removes the whole note (or target: {kind: "anchor"|"alias"|"facet"|"invariant"|"behavior"|"feature", key: "<value>"} removes one part).

TWO-PHASE reuse gate: a flow/lesson spec sent WITHOUT an id first searches the notebook for the same concept. If plausible matches exist, kb_write returns {status:"candidates", candidates:[...]} INSTEAD of writing — re-call with into: "<id>" to merge into an existing note, or is_new: true to declare a genuinely new one. This makes note identity reliable (matching, not guessing an exact title). File notes skip the gate (id derives from the path).

The spec shape: type ("file"|"flow"|"lesson", or sugar "file-hub"/"file-single"), title, summary, anchors ([{path, symbols?}] — the addresses the note is about, which drive freshness), plus type-specific fields (file: facets/character; flow: steps/verified; lesson: kind:"absence"/scope/body). Call with NO arguments to get the full spec guide.

REQUIRED for the note to be findable at all — file-single: identityAliases + anchors[].symbols; file-hub: identityAliases + facets[].symbol; flow: identityAliases + steps + verified; lesson: scope.terms. A note missing these is written but unreachable: identityAliases are the only STABLE search surface besides the exact title (incidentAliases are optional — symptom words for a write that describes one, replaced by the next such write, never required), and anchor symbols are the only channel that answers a query typed as an identifier.

This tool WRITES to the repo notebook; it never commits to git — publishing notes is a human-only step (coldstart kb commit).

ParametersJSON Schema
NameRequiredDescriptionDefault
intoNoPhase-2 answer: merge this write into the existing note with this id (from a prior `candidates` response).
specNoA single note spec (JSON object). Fields: type, title, summary, identityAliases (stable — unions forever), incidentAliases (this write's symptom words — replaced by the next write that changes summary/body, omit if this write isn't about an incident), anchors:[{path,symbols?}], and type-specific fields (facets/character for file; steps/verified for flow; kind/scope/body for lesson). REQUIRED for the note to be findable at all — file-single: identityAliases + anchors[].symbols; file-hub: identityAliases + facets[].symbol; flow: identityAliases + steps + verified; lesson: scope.terms. A note missing these is written but unreachable: identityAliases are the only STABLE search surface besides the exact title (incidentAliases are optional — symptom words for a write that describes one, replaced by the next such write, never required), and anchor symbols are the only channel that answers a query typed as an identifier. Omit `id` on a new flow/lesson to trigger the reuse gate. Use `specs` instead to write several notes at once.
agentNoOptional agent id (given in a capture prompt, alongside session). Selects THIS agent stream's durable worklist for the coverage line so a subagent does not clear the main agent's list. Defaults to "main".
specsNoThe capture path: an ARRAY of note specs (each the same shape as `spec`), written in ONE call. Order flows before the file notes that reference them. Well-formed notes are written; malformed ones are reported together (not atomic — a bad note never silences a good one); the result ends with a coverage line naming any worked file still without a note. Prefer this over many single-`spec` calls.
is_newNoPhase-2 answer: declare this a genuinely new concept, bypassing the candidate matches from a prior `candidates` response.
sessionNoOptional session id (given in a capture prompt). Enables the flow-evidence check: a flow whose step files this session never actually read gets a warning.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It thoroughly discloses key behaviors: the two-phase reuse gate returning `{status:"candidates"}` instead of writing, non-atomic multi-spec writes (malformed notes reported together but good ones written), a coverage line at the end, flow-evidence checks with session, and the git/publishing boundary. It also explains the consequences of missing required fields ('written but unreachable') and the stability/replacement semantics of identityAliases vs incidentAliases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with clear paragraphs for purpose, reuse gate, spec shape, required fields, and git behavior. It is front-loaded with the core purpose. However, there is redundancy: the 'REQUIRED for the note to be findable' paragraph is nearly duplicated in the spec parameter description, and incidentAliases semantics appear twice. This prevents a perfect score while still being appropriately detailed for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must explain return behavior and does so thoroughly: candidate responses, coverage lines, malformed note handling, and the flow-evidence warning. It covers the two distinct call modes (`spec` vs `specs`), the reuse gate interaction, required fields for findability, and non-commit behavior. This is comprehensive for a tool with six parameters and nested object inputs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Though schema coverage is 100%, the description adds substantial semantic context beyond the schema. It explains the relationship between `spec`/`specs`, the phase-2 meanings of `into` and `is_new` (merging vs declaring new), the purpose of `session` for flow-evidence checks, and `agent` for the coverage line. It also details the `spec` shape and required fields per type, enriching the bare schema definitions significantly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Save or correct NOTEBOOK notes after finishing real work here', using a specific verb (save/correct) and resource (NOTEBOOK notes), and clearly distinguishes this write tool from read/search/repair siblings like kb_search, kb_lookup, and kb_repair. It also explicitly states it handles fixes and retractions in addition to initial writes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'after finishing real work here — you have the files in context, so no future agent is better placed to record what you learned.' It also explains when to use `specs` vs `spec`, describes the two-phase reuse gate process, and clearly states what the tool does NOT do ('never commits to git — publishing notes is a human-only step'), providing sufficient context and exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.6/5.0
Disambiguation4/5

Most tools have clearly distinct purposes: find/gs for code navigation, kb_* for notebook management. Minor overlap exists between kb_status (with paths) and kb_lookup, both of which can check what notes exist at a path, though at different depths; kb_repair and kb_repair_aliases are also closely related by name, but their functions are well-differentiated.

Naming Consistency4/5

The kb_* tools follow a consistent `kb_<verb>` pattern (search, lookup, write, repair, status, repair_aliases). The outliers are 'find' (a bare verb without the prefix) and 'gs' (an abbreviation), which break the pattern but are still readable and distinct.

Tool Count5/5

Eight tools is a well-scoped count for a code-search-and-notebook server. Each tool earns its place: two for code navigation and six for notebook management, with no redundancy or bloat.

Completeness5/5

The notebook surface is complete: status, search, lookup, write (create/update/retract), repair, and alias reconciliation cover the full lifecycle. Code navigation covers locating files (find) and drilling into structure/usage (gs). The server intentionally defers raw file reading to Read/Grep/Glob, which is acceptable given its purpose.

Maintenance

ActivityActive
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • agentmem

    Thezenmonster
    A
    license
    A
    quality
    D
    maintenance
    Governed memory for coding agents with trust lifecycle, conflict detection, staleness tracking, and health scoring. SQLite + FTS5, zero infrastructure. Works with Claude Code, Cursor, Codex, Windsurf.
    13
    3
    MIT

  • Stoa

    BrettNye
    A
    license
    Not graded
    quality
    A
    maintenance
    Persistent shared memory for AI coding agents that turns a folder of markdown files into searchable memory across sessions, repos, and machines.
    12
    Functional Source , Version 1.1, MIT Future

  • Memory MCP

    EtienneBBeaulac
    A
    license
    A
    quality
    C
    maintenance
    Gives AI coding agents persistent, evolving knowledge about a codebase, enabling them to store and retrieve observations about architecture, conventions, gotchas, and recent work context.
    10
    29
    1
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/AkashGoenka/coldstart'

If you have feedback or need assistance with the MCP directory API, please join our Discord server