Slimdex-MCP is a local Model Context Protocol server for coding agents that enables narrow, context-aware code retrieval, search, editing, and repository understanding to dramatically reduce token usage. It provides the following capabilities:
Indexing & repo overview: index_repo (build/refresh index), repo_map (directory overview), changed_files (git diff symbol mapping), snapshot (backup uncommitted), .slimdex.json (configuration).
File & code reading: read_lines (line range), outline_file (declarations only), get_file_skeleton (elided bodies), get_symbol_context (symbol bodies by name), get_context (comprehensive symbol brief), context_pack (topic exploration pack).
Search & discovery: search_code (regex with line/col highlights), search_symbols (fuzzy name lookup), search_intent (natural language BM25), find_definition, find_references, find_tests, dep_graph (import/dependency queries, Mermaid diagram).
Code editing: replace_symbol (overwrite or insert symbol body by name, batch edits, auto-snapshot & reindex).
Session continuity & memory: brief (onboarding summary), recap (prior activity), memory_* (save/search/list/get/delete durable notes), digest_save/get (architecture cheat-sheet with freshness verdict).
Utilities: batch (multiple calls in one request), stats (call counts and response sizes), install_hook (client-side write discipline hook).
Enables retrieval of code from Salesforce projects by recognizing and indexing Salesforce metadata sidecar files (e.g., .cls-meta.xml, .js-meta.xml, .object-meta.xml) for symbol search and code navigation.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@slimdex-mcp search_intent "parse the config file""
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Your agent reads a 900-line file to change one function — then pays for that file again on every turn that follows. The whole conversation is re-sent each time, so an early read isn't a one-time cost. It's rent.
Slimdex is a local MCP server that gives coding agents narrow retrieval instead: a file's outline, one symbol's body, who calls it, what breaks if it changes — and memory that survives the session, so the next chat starts informed rather than re-deriving the repo from zero.
claude mcp add slimdex -- npx -y slimdex-mcp~50% fewer tokens in day-to-day use — ~55–60% on navigation-heavy work, ~45% on output-heavy work, and 85–90% on the worst case it was built for (one 6,200-line file, explored through a skeleton and 12 symbol bodies instead of four full reads).
Status: 1.1.0, on npm and in the MCP Registry. Those numbers are self-measured on the repos it has been run against, single sessions, not independently validated — and
statscounts characters, not tokens. Read What's actually verified before relying on it.
Tool | What it returns |
| Builds/refreshes a persistent symbol + import index; only changed files re-parse |
| Declarations of one file with line numbers |
| Signatures with bodies elided, nesting preserved |
| One line range |
| One function/class body ±2 lines, capped by |
|
|
| Definition site(s) of a symbol as |
| Fuzzy symbol-name lookup, ranked exact→prefix→substring→subsequence |
| Natural-language query ranked over symbols by BM25 (no embeddings) — find code by what it does |
| One call: ranks a topic's symbols, shows how they connect, and bundles the top bodies under a budget — the whole exploration in one round-trip |
| Textual references as |
| Of the references to a symbol, which live in test files — or a warning that none do |
| Overwrite a symbol's body addressed by name (no re-sent old code); snapshots first, re-indexes after |
| One call: opt-in definition / signature / callers / imports / dependents, budgeted |
| Dir-level file/line/symbol counts; |
| Changed files + which symbols each hunk lands in |
|
|
| Per-tool call counts and response sizes, in characters, plus read follow-through and write discipline |
| Runs several calls in one request |
| Prior sessions' activity, reconstructed automatically from the server's tool-call journal — works even when nothing was saved |
| One-shot session opener: repo summary + journal-derived focus + saved conclusions checked against the live index (✓ live / ⚠ maybe stale) |
| Store a compact repo architecture cheat-sheet once; read it back with a per-covered-file freshness verdict, so the next session skips re-exploring |
| Copies uncommitted files into |
| Durable notes in |
The retrieval guidance below also ships in the server's MCP instructions, so
clients inject it into the model's context automatically.
brief first, at the very start of a session — one call that reports what the
repo is, where recent sessions were digging, and which saved conclusions still
match the code (stale ones flagged), so a fresh chat starts informed instead of
blank. Then get_context("Foo") to answer "what is this, who calls it, what does
it depend on" in one response. To understand a whole area rather than one
symbol, context_pack("how does auth work") runs the entire exploration
server-side and hands back a single bounded bundle — the relevant symbols, how
they connect, and the top bodies — so you spend one call and one transcript
entry instead of ten. Don't know the name, only what it does? —
search_intent("parse the config file") ranks symbols by intent with BM25, no
embeddings. Drop to get_symbol_context for one body (it flags itself if the file
drifted from the index, so you don't re-read to check), get_file_skeleton for a
file's shape, and read_lines when you need exact source. Before editing a
symbol, find_tests on it to see what covers it; to
rewrite a whole function, replace_symbol (you send only the new body — the old
code isn't re-sent just to locate the edit). Use batch to bundle several
lookups. Every search tool takes limit (default 20) and offset.
Response budgeting: get_context sections are opt-in via include
(default: definition, signature, callers, imports — add body or dependents
explicitly), callers are capped by callerLimit, and the response is bounded
by maxChars (default 12,000). Every cap that trips prints an explicit notice
(showing 3 of 68, truncated at maxChars=...) rather than dropping data
silently. get_symbol_context caps its span with maxLines the same way, and
memory_list returns the newest 50 facts unless told otherwise, as ~150-char
previews rather than whole bodies (memory_get ids:[...] expands them,
full:true dumps everything). On an 18-fact store that is the difference
between ~4,100 and ~18,600 chars in the call every session opens with.
<root>/.slimdex.json (optional){
"ignoreDirs": ["fixtures", "backend/src/main/resources/static/assets"],
"extensions": [".astro", ".vue"],
"suffixes": [".stories.mdx"],
"exclude": ["generated/", "legacy/vendor"],
"maxFileBytes": 2000000
}suffixes matches a filename ending, for file types an extension can't identify.
Salesforce metadata sidecars ship as a built-in: AccountSvc.cls-meta.xml,
panel.js-meta.xml and Account.object-meta.xml are indexed, while pom.xml,
web.xml and manifest/package.xml are not — adding .xml to extensions
would have pulled in every config tree in the repo. Suffix-matched files are
indexed for search and read reach, not symbols.
Merged on top of the built-in ignore list (node_modules, dist, .venv,
.svelte-kit, Pods, .pytest_cache, …). An ignoreDirs entry is either a bare
name, matching any directory so called at any depth, or a path containing /,
anchored at the repo root and respecting directory boundaries (src/gen will not
also ignore src/generated). index_repo echoes what it loaded and warns about
unknown keys, wrong types, or invalid JSON, so a typo'd config isn't silently
indistinguishable from none.
Build output usually needs no config at all. Beyond the directory list, any
file whose lines run past ~5,000 characters is treated as minified build output and
left out of the index — bundlers strip newlines, and hand-written source doesn't
look like that. This catches what a name list structurally cannot: a hash-named
bundle (index-B7xK2p9q.js) inside a directory called assets. assets, public
and static are deliberately not ignored by name, because real source lives in
them; index_repo reports the count as skipped(minified build output): N.
There's no compression trick. The saving is behavioral: these tools let an agent retrieve outlines, ranges, and locations instead of whole files, and the persistent index means repeat lookups hit a cached query rather than a re-read.
Two later sessions, run by different models on different repo shapes, added real-world numbers to the original report:
Multi-file web app, bug-fix session (GPT-5.3-Codex). 19 credits reported with slimdex; the model's own estimate for the same scope without it: 45–70 credits. Math: 19/45 → 19/70 ≈ 58–73% cheaper. The counterfactual is the model's estimate, not a measured A/B — directional.
Single giant file (folio-app: one 6,200-line, 313 KB app.js).
Slimdex's own stats: ~34,000 chars across 8 calls ≈ 9–10k tokens — one
skeleton (213 signatures), then bodies of only ~12 relevant functions, 9 of
them fetched in a single get_symbol_context names:[...] call. The naive
path: 313 KB ≈ 78–85k tokens across 3–4 forced full reads. Math: ~10k vs
~80k ≈ ~70k tokens saved, an 85–90% reduction on exploration. The bug's
diagnosis (an export path with no matching import path) was visible from the
skeleton's signatures before a single body was opened.
Together they sketch the scaling law: the saving scales with how much irrelevant code the naive path would drag in. One giant file is the best case; a normal repo lands around half to two-thirds cheaper; a repo of tiny files breaks even. Same standing caveats as everything here: stats count chars, not tokens (÷3.5–4), and single sessions are evidence, not benchmarks.
Both figures above measure reading only, which is the cheaper half. Output
costs roughly 4–5× input, so an undisciplined edit wastes more than an
undisciplined read: rewriting a whole function through a generic edit tool means
re-sending the entire old body purely so the tool can locate it. replace_symbol
addresses by name and that cost disappears. stats reports this alongside
follow-through, because the leak is otherwise invisible — the expensive path
still produces a correct edit, so nothing signals that you overpaid:
write discipline:
replace_symbol: 0 call(s), 0 symbol(s) rewritten by name
changed outside slimdex: 12 file(s)
pre-edit checks (find_tests/dep_graph/get_context/changed_files): 0External edits are inferred from content hashes moving between two index_repo
runs, so the number is honest about its limits: it sees that bytes changed, never
which tool changed them, and a human editing in another window counts too.
The figures above are single-scenario exploration numbers — the best case, where the naive path would have dragged in the most irrelevant code. Averaged across a whole real workday, not just the exploration slice, the band settles lower:
~55–60% on navigation-heavy work — reading and understanding a codebase, where narrow retrieval replaces whole-file reads most often.
~45% on output-heavy work — churning out new code, where more of the cost
is generation the server doesn't touch (though replace_symbol now shaves the
write side too).
~50% averaged over regular day-to-day use. The saving compounds the more
sessions run through it, because brief and memory mean each new chat starts
informed instead of re-deriving the repo from zero.
Use it regularly across sessions in your IDE for the best of this.
Treat these as one data point, not a benchmark. Single repo, single task, one
A/B run each, self-measured, no repetitions or variance. Your mileage depends
heavily on whether your agent actually reaches for the narrow tools instead of
falling back to reading files — which varies by client and model. The method is
repeatable if you want to check it: run the same task in two fresh sessions, one
instructed to use only Slimdex and one instructed to avoid it, and compare
/status cache-write.
Being explicit, since the rest of this README is easy to over-read.
Covered by the unit suite (npm test runs 224 tests across 23 files):
Symbol extraction across JS/TS (incl. class and object-literal methods),
Python, Go, Rust, Java/C#, and comment skipping — symbols.test.ts
Import extraction for JS import/require/export-from, Python, Rust
Block extraction, brace-scoped and indentation-scoped, with string/comment
awareness (quotes, templates, //, /* */, full-line #) — extractBlock.test.ts
Import resolution, external-module classification, reverse-edge dependents,
Mermaid emission, and root-BFS depth scoping — graph.test.ts
Search match format, pagination without overlap, per-line occurrence counting,
exact totals, regex escaping/rejection — search.test.ts
Opaque cursor round-tripping and malformed-cursor rejection; parser-backend
fallback — pagination.test.ts
Outline declaration detection vs. control flow — outline.test.ts
get_symbol_context maxLines budgeting and truncation notice
String/comment masking and brace-depth tracking — lexer.test.ts
Per-language extraction for all twelve supported languages — languages.test.ts
The index cache returns the same object until the index is rewritten
.slimdex.json loading: every key applied through a real index build, plus
the failure modes (invalid JSON, unknown keys, wrong types) each producing a
visible warning instead of silence — config.test.ts
changed_files against a real temporary git repository: hunk→symbol
attribution, untracked files, explicit base refs, and formatting; skips
cleanly when git isn't installed — git.test.ts
The file watcher, with real fs events: a save is debounced, reindexed, and
lands in the on-disk index — watch.test.ts
Graph edges beyond imports: name-reference edges for import-less code
(class→used-class, interface→implementation via dependents, trigger→handler)
and declarative-wiring edges from repo XML (metadata-binding→class), with
comment/string mentions excluded and per-build caching — apexgraph.test.ts
The in-memory file cache serves repeats without re-reading and always serves
fresh content after an on-disk change — fscache.test.ts
Test-file detection across JS/TS/Python/Go/Ruby/Java/C# conventions, with
Windows separators normalized and ordinary source (latest.ts, Contest.java)
not misflagged — testlink.test.ts
The write side: replacing a symbol's block, trailing code preserved, and CRLF
vs LF line endings kept so an edit isn't reflowed into a whole-file diff —
edit.test.ts
Memory staleness: a fact is marked live when it names a symbol/file that still
exists, flagged stale only when every code mention is gone, and left unflagged
for prose — plus brief composition — brief.test.ts
Intent search: camelCase/snake_case tokenization, and BM25 ranking that surfaces
a differently-named symbol by its intent words while scoring an unrelated query
to nothing — intent.test.ts
Freshness: a file newer than its indexed mtime reads as stale (line numbers may
be off), a matching mtime reads as fresh, and a missing file never cries stale —
freshness.test.ts
context_pack assembly: header + ranked symbols + bodies in one bundle, the
no-match message, char-budget gating that still guarantees the first body, and
the symbols-limit cap — pack.test.ts
The architecture digest: covered files modified after the digest read as stale,
a newer digest reads clean, coverage-scope and directory-prefix filtering, and
the rendered fresh/stale verdict — digest.test.ts
Covered end to end, through the real MCP server (integration.test.ts spawns
the server over stdio against a temporary fixture repo and asserts on output):
index_repo, repo_map, read_lines, get_file_skeleton, outline_file,
get_symbol_context, find_definition, find_references, find_tests (the hit
and the no-coverage warning), search_intent (intent ranking), context_pack (one-call
bundle), digest_save/digest_get (round trip with freshness verdict),
get_context (including its maxChars cap),
dep_graph (imports + mermaid), batch, search_code, search_symbols,
stats, brief, replace_symbol (write-then-query round trip and the
unknown-symbol refusal), the memory_save/search/list/delete round trip, the
path-escape guard, and the not-found paths.
CI runs the build and both suites on Ubuntu + Windows, Node 20 and 22.
Caveat on the watcher test: recursive fs.watch is platform-dependent, so
watch.test.ts degrades to a logged skip on filesystems that never deliver an
event — same behavior as the watcher itself. On Windows, macOS, and current
Linux it asserts the full save→reindex path.
npm run smoke still exists but proves only that the pipeline is alive — the
correctness assertions live in integration.test.ts.
Verified by inspection: src/ contains no network calls — no code leaves
your machine. This one you can check yourself:
grep -rE "fetch\(|https?://|axios|http\.request" src/.
Related MCP server: LocalNest MCP
In docs/:
tool-guide.md — every tool explained twice
(technically and in plain words) with an example each, the combined
workflow, and how mtime-based persistence works
tool-guide.html — the same guide as a styled,
self-contained page for the browser
token-savings-report.md — the original A/B
measurement, its method, and how to repeat it
agent-brain.md — the full operating discipline as a
readable document
agent-brain-slim.md — the one to drop into a
repo as CLAUDE.md / AGENTS.md. Self-contained and one page: savings ladder,
question→tool table, memory discipline, session hygiene, honest limits, env
knobs. Same coverage as the full document at ~30% of the prose, because the
tool rules are dense tables rather than paragraphs the server already injects.
Two measurements, because fixtures alone prove very little.
Fixtures — one per language, counting the declarations a developer would
actually navigate to: 65/65 found, 0 false positives, pinned by
test/languages.test.ts.
Real third-party code — extraction run over ~11,800 files from several hundred real packages (React, Babel, Remix, Socket.io, Playwright, Three.js, Emotion, zod, ajv …) and compared against an independently written heuristic for what counts as a declaration: 95.9% recall. Reproduce it yourself:
npm run audit -- ./node_modules # or any directory of code you didn't writeThat number is a floor, not a grade — the truth heuristic counts some non-declarations, so real recall is a little higher. What it's for is catching regressions and finding the next real gap.
Almost nothing that failed the audit was framework-specific. Frameworks add annotations, decorators and conventions; they rarely invent syntax. Handle the language and the frameworks come with it — fflib's Application/Domain/Selector/ Service/UnitOfWork layers extract completely (129 declarations) without a single fflib-aware rule.
The one genuine exception is test DSLs. A vitest/jest/mocha/RSpec file often
has no top-level declarations at all, so entire test directories used to index to
nothing. describe/it/test titles are now indexed as kind test, which is
what you actually navigate to in a test file.
Framework semantics are recovered wherever the reference exists somewhere in the repo, through two extra edge sources in the graph:
Name-reference edges, for languages that have no import statement (e.g.
Apex): if one file's code — comments and strings masked out — mentions a
top-level type defined in another file, that's an edge. This is what makes
implements answerable as "who implements this interface", and links a
trigger to the handler class it news up.
Declarative-wiring edges: bindings that frameworks keep in configuration
rather than code (custom-metadata records, flow definitions) usually live in
the repo as XML with the type name as an element value. Repo XML is scanned
for known type names — XML comments excluded — and each hit becomes a
metadata-file → class edge, so dependents answers "what wires this up".
Both scans are cached per index build and cost nothing on repos without such
files. Pinned by apexgraph.test.ts. What no static reader can see is a
binding that exists only in a live system — configured in a running org or
database and never retrieved into the repo. If it's not in the repo in any
form, there is no edge to draw; search the type name instead.
Language | Extensions | What's recognised |
JavaScript / TypeScript |
| classes, interfaces, types, enums, functions, top-level arrows, class and object-literal methods |
Apex |
| classes, inner classes, methods (incl. |
Java |
| classes, interfaces, enums, methods, generic methods with a leading |
C# |
| classes, interfaces, structs, async and generic methods, virtual members |
Kotlin |
| classes, data classes, interfaces, |
Swift |
| classes, structs, enums, protocols, |
Python |
| classes, |
Go |
| funcs, receiver methods, struct and interface types |
Rust |
| structs, enums, traits, |
Ruby |
| classes, modules, |
PHP |
| classes, interfaces, traits, methods, functions |
Scala |
| classes, case classes, traits, objects, |
C / C++ / Objective-C |
| classes, structs, enums, free functions (incl. K&R braces, pointer returns), |
Cold index is a full parse; warm is an mtime check per file. Measured on Windows, Node 24.
Repo | Files | Symbols | Cold index | Warm index | Typical query |
Salesforce DX org | 56 | 344 | 0.1 s | 15 ms | < 10 ms |
Java + React app | 356 | 1,713 | 0.42 s | 26 ms | 3–57 ms |
Synthetic stress | 5,000 | 50,000 | 1.5 s | 0.24 s | 5–22 ms |
The index is held in memory and invalidated by the index file's mtime. Without that cache every tool call re-read and re-parsed the whole index — about 20 ms of dead weight per call on the 5,000-file repo, and it grew with the repo.
find_references is the slowest tool at scale because it is a textual scan,
not an index lookup — but a literal pre-filter now skips the line-split and
per-line regex for any file whose raw source doesn't contain the searched name,
which on a typical repo is most of them. Scope with pathPrefix to cut the
remaining file reads when you know roughly where to look.
File contents are also served from a byte-bounded in-memory LRU (64 MB,
validated by mtime+size per hit), so the second scan of a repo — and the
skeleton→read_lines→context sequence agents actually perform on one file —
costs a stat() instead of a read.
memory_save writes to <root>/.slimdex/memory.json, which outlives the
process — a fact saved in one chat is readable in the next, by a different
client, after a restart. Chat and editor share one store only when both point at
the same SLIMDEX_ROOT.
Nothing is captured automatically: the server never sees your conversation, so
the agent has to decide what's worth keeping. The shipped instructions tell it
to read memory first in a new session and to save decisions, constraints and
gotchas as it learns them — but that's guidance to the model, not a guarantee.
Symbol extraction is regex-based and heuristic, not a parser or LSP. It can
miss unusual declarations, and find_references is a textual match that may
include same-named but unrelated identifiers.
Symbol and outline extraction now run against a masked copy of each line,
with string and comment contents blanked out, so declaration-shaped prose
inside a template literal is no longer indexed as code. Declarations are also
depth-aware: a const x = () => … or type X = … counts only at top
level, because locals inside a function body are not things anyone navigates
to. Class methods are still indexed at their nesting depth.
An inline Python # comment containing a brace can still confuse block
extraction (# is also the JS private-field sigil, so it can't be stripped
blindly).
changed_files attributes a hunk to the nearest preceding declaration —
right for a normal function body, approximate for code between declarations.
Treat it as blast radius, not a call graph.
search_code reports an exact total but stops at an internal scan cap on very
large result sets, printing N+ (scan cap reached) rather than a confident
wrong number.
Language support is uneven: JS/TS is the best-covered. C-family and Ruby,
formerly the thinnest, gained dedicated rules (free functions, Foo::bar
definitions, function-like macros, attr_*); the remaining soft spots are
advanced C++ shapes — templates split across lines, operator overloads.
For LSP-grade precision you'd swap the parser for tree-sitter or a language
server. src/parser.ts is the seam: a Parser interface selected by
SLIMDEX_PARSER, with the regex parser as the only implementation that
ships. A tree-sitter backend would drop in there without touching any tool or
the index format. It is not built — per-language grammars trade away the
"installs instantly, runs offline, zero config" property.
Ideas evaluated and rejected, with reasoning — these are design opinions, not measured results:
Symbol-ID dictionaries (S42 → path) — MCP has no client-side expansion
layer, so the model receives an opaque token it must spend another call to
resolve.
Token-budget managers / cost estimators — chars/4 estimates are
unreliable across tokenizers, and auto-compressing on a bad estimate can drop
data the model needed.
Delta / "already-sent, see response #5" caching — after context compaction the earlier payload is gone, so the reference resolves to nothing.
Embeddings / semantic search — large dependency footprint; possible future optional flag, not a default.
A tree-sitter parser backend — this is the one that would close the
remaining ~4%, and it was costed rather than hand-waved: web-tree-sitter is
WASM so it needs no native compilation, but the grammars
(tree-sitter-wasms) are 51.7 MB unpacked against ~4.5 MB for the whole
current install. Evaluated and declined at 95.9% measured recall, because
"installs in a second, runs offline, no configuration" is the property this
server exists to have. src/parser.ts remains the seam if that calculus ever
changes — a backend drops in there without touching a tool or the index
format.
Published on npm as slimdex-mcp,
and listed in the MCP Registry as
io.github.Siddhukaushik/slimdex-mcp. Nothing to build — point your client at:
npx slimdex-mcpOr from source, if you want to hack on it:
git clone https://github.com/Siddhukaushik/slimdex-mcp
cd slimdex-mcp
npm install
npm run build # produces dist/index.js
npm test # vitest unit suiteVerify it runs end to end against a repo:
npm run smoke # this repo
node smoke-test.mjs "C:/path/to/some/repo" # any otherVar | Effect |
| Repo to index (or pass as the first CLI arg; defaults to cwd) |
| Set to |
| Parser backend; only |
| Set to |
|
|
| Set to |
Per repository, Slimdex writes to <repo>/.slimdex/:
index.json — the code index (mtime-invalidated per file, and discarded
wholesale when the index format version changes, so a stale index built by an
older extractor is never reused)
memory.json — saved memory facts
stats.json — per-tool usage counters
The directory ignores itself: a * .gitignore is written inside it (the
node_modules/.cache trick), so it never shows up in git status and you don't
have to touch the repo's own .gitignore. Delete that inner file if you want
to commit the cache.
MCP is a shared standard, so the same server should plug into any MCP-capable
client. The project root is passed via SLIMDEX_ROOT (or as the first CLI
arg).
Only Claude Code and Claude Desktop have actually been run. The others below are the standard config shape for each client, written from their documented format — they are untested here and may need adjustment.
Since 1.0.0 the simplest wiring is npx -y slimdex-mcp — no clone, no build, and
it stays current. The examples below keep the node <ABS_PATH> form for anyone
running from source; to use the published package instead, swap
"command": "node", "args": ["<ABS_PATH>"] for
"command": "npx", "args": ["-y", "slimdex-mcp"].
Replace <ABS_PATH> with your build output, e.g.
C:\path\to\slimdex-mcp\dist\index.js, and <REPO> with the repo to index.
No tuning required. The savings that matter are on by default in every
client: memory facts list as previews, responses are terse, an identical re-read
of an unchanged file answers with a pointer instead of the body, and several
symbol edits go in one call. The env vars below are for opting out, or for
lean — which trades a further ~8,700 chars/turn against routing a third of the
tools through batch, so it is deliberately not the default.
claude mcp add slimdex --env SLIMDEX_ROOT=<REPO> -- npx -y slimdex-mcpFrom source instead: -- node <ABS_PATH>.
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"slimdex": {
"command": "npx",
"args": ["-y", "slimdex-mcp"],
"env": { "SLIMDEX_ROOT": "<REPO>" }
}
}
}~/.codex/config.toml
[mcp_servers.slimdex]
command = 'C:\Program Files\nodejs\node.exe'
args = ['<ABS_PATH>']
startup_timeout_sec = 30Registered globally like this, slimdex attaches to every Codex task and uses
that task's working directory as the repo root — no SLIMDEX_ROOT needed. Codex
launches the server with a restricted environment, so give command an absolute
path to node rather than relying on PATH.
.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
{
"mcpServers": {
"slimdex": {
"command": "node",
"args": ["<ABS_PATH>"],
"env": { "SLIMDEX_ROOT": "${workspaceFolder}" }
}
}
}~/.codeium/windsurf/mcp_config.json — same mcpServers shape as Cursor.
.vscode/mcp.json
{
"servers": {
"slimdex": {
"command": "node",
"args": ["<ABS_PATH>"],
"env": { "SLIMDEX_ROOT": "${workspaceFolder}" }
}
}
}Cline settings → MCP Servers → add:
{
"slimdex": {
"command": "node",
"args": ["<ABS_PATH>"],
"env": { "SLIMDEX_ROOT": "<REPO>" }
}
}settings.json → context_servers
{
"context_servers": {
"slimdex": {
"command": { "path": "node", "args": ["<ABS_PATH>"], "env": { "SLIMDEX_ROOT": "<REPO>" } }
}
}
}For clients that expose the workspace folder (Cursor, VS Code),
${workspaceFolder}keeps Slimdex pointed at the repo you have open.
index_repo once at the start (faster on subsequent runs), then brief to
pick up where past sessions left off with stale notes already flagged.
repo_map → get the lay of the land.
outline_file on a file of interest → pick line ranges.
read_lines for just those ranges.
find_definition / find_references / dep_graph to navigate.
find_tests before editing a symbol; replace_symbol to rewrite one without
re-sending its old body.
memory_save decisions and gotchas so the next session starts informed.
MIT © 2026 Kael VK Inc. (Business Number 751569161 RC0001) — see LICENSE.
Provided as is, with no warranty and no support. If it doesn't build, doesn't run, or doesn't work on your setup, that's yours to carry — see the disclaimer in the license.
Execute multiple slimdex calls in one request to avoid per-call protocol overhead. Pass calls: [{ "tool": "find_definition", "args": { "name": "login" } }, ...]. Cannot nest batch inside itself.
| Name | Required | Description | Default |
|---|---|---|---|
| calls | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It mentions the nesting prohibition and the efficiency motivation, but it does not explain failure semantics, ordering of results, or error handling. This leaves significant ambiguity for a tool that executes multiple calls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the main purpose, and includes a practical example and a critical constraint. Every word earns its place; no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter structure and lack of output schema, the description is not severely incomplete, but it lacks important context such as response ordering, partial failure behavior, and whether results are returned per call. These omissions could mislead an agent into assuming atomicity or a specific response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no description coverage (0%), but the description provides a concrete example ('calls: [{ "tool": "find_definition", "args": { "name": "login" } }, ...]') that clarifies the expected structure beyond the raw schema. This compensates well for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Execute multiple slimdex calls in one request to avoid per-call protocol overhead.' The verb 'Execute' is specific, the resource is 'multiple slimdex calls', and it distinguishes itself from other tools by focusing on batching to reduce overhead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on why to use this tool (to avoid per-call protocol overhead) and explicitly states a constraint: 'Cannot nest batch inside itself.' It could be improved by mentioning when NOT to use it (e.g., for dependent calls) but the current guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CALL THIS FIRST in a fresh chat — including on a repo slimdex has never seen, where it builds the index itself rather than sending you to index_repo. One synthesized opener instead of stitching memory_list + recap yourself: what the repo is, where recent sessions were digging (automatic journal), and each saved conclusion CHECKED against the current index so stale ones are flagged (✓ live, ⚠ may be stale).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Journaled calls to summarize for the focus section (default 200). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses that the tool builds the index itself if the repo is unseen, automatically consults the journal, and checks each saved conclusion against the current index, flagging stale ones with ✓/⚠. It does not detail side effects or persistence, but the core behavioral traits are clearly communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two dense sentences, front-loaded with the critical 'CALL THIS FIRST' directive. Every clause adds functional value: when to use it, the unseen-repo exception, the alternative approach, and the output's components with staleness markers. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and no output schema, the description sufficiently covers purpose, usage timing, and output content. It does not explain internal journal mechanics or return format, but those are not essential for correct invocation given the schema's complete parameter coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter `limit` is fully described in the input schema with a default value, achieving 100% schema coverage. The tool description adds no additional parameter-specific semantics, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the imperative 'CALL THIS FIRST in a fresh chat' and defines the tool as 'One synthesized opener' that covers repo identity, recent session focus, and stale-checked conclusions. It explicitly distinguishes itself from `memory_list` + `recap` and from `index_repo`, making its unique purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use guidance: 'CALL THIS FIRST in a fresh chat'. It also covers the special case of an unseen repo where the tool builds the index itself rather than redirecting to `index_repo`, and positions itself as an alternative to manually stitching `memory_list` + `recap`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize the working-tree diff (or a diff against base) as changed files with +added/-deleted counts AND the enclosing functions/classes each hunk lands in — the blast radius, without pulling the patch into context. The cheap way to start a session on a dirty repo. Requires a git checkout.
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | Ref to diff against (e.g. 'main', 'HEAD~3'). Omit for working tree vs HEAD. | |
| limit | No | Max files to list (default 30). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses a prerequisite ('Requires a git checkout'), a cost/behavior trait ('without pulling the patch into context' indicating it is cheap and does not load the full patch), and the output structure. It does not explicitly state it's read-only but 'Summarize' implies no side effects; it lacks details on error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences: the first packs the core purpose and output, the second gives the use case and prerequisite. It is front-loaded, specific, and contains no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two optional params, no output schema), the description is complete: it explains what it returns (counts and symbol locations), when to use it (start of session on dirty repo), and a prerequisite ('Requires a git checkout'). There are no critical gaps for agent selection or invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters fully (100% coverage), so the description need not compensate. It adds only a redundant clarification of `base` ('or a diff against base') but offers no new meaning for `limit` or parameter syntax, thus meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Summarize' and clearly identifies the resource as the 'working-tree diff' with two explicit output components: '+added/-deleted counts' and 'enclosing functions/classes each hunk lands in.' This distinguishes it from sibling tools like 'snapshot' or 'outline_file' that focus on structure rather than diffs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: 'The cheap way to start a session on a dirty repo,' and contrasts with 'without pulling the patch into context,' implying a lightweight alternative to reading the full diff. However, it does not name specific sibling alternatives or explicit exclusions, so it falls short of the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Understand a whole topic in ONE call instead of ~10: give a natural-language query ('how does auth work') and slimdex runs the exploration itself — BM25-ranks the symbols, shows how their files connect (import graph, one hop), includes the top few bodies, all under a char budget. Saves the round-trips AND keeps ten separate results out of the transcript. Orient with this; drop to get_symbol_context / read_lines for exact source.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The topic to understand, in words — 'how does login work', 'the indexing pipeline'. | |
| bodies | No | How many top symbols to include full bodies for (default 3). | |
| budget | No | Soft char cap on the whole pack (default 6000). | |
| symbols | No | How many ranked symbols to list (default 8). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden and mostly succeeds: it discloses that the tool runs exploration autonomously, ranks symbols, and operates under a char budget. However, it does not mention potential costs or failure modes (e.g., ambiguous queries), and stops short of stating whether it is read-only, though that is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core value proposition and each sentence serves a purpose, but it is slightly verbose (e.g., the round-trip savings sentence partially repeats the opening). It remains informative without being overly padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description must explain return content, and it does describe the included elements (ranked symbols, import graph, bodies). However, it omits the exact response structure or formats, and does not address error cases, leaving some gaps for a tool with 4 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds a bit of context by linking 'char budget' to budget and 'top few bodies' to bodies, but it does not provide new parameter-specific syntax or format details beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Understand a whole topic in ONE call' and explains what it does (BM25-ranks symbols, shows import graph, includes bodies). It distinguishes from siblings by explicitly naming get_symbol_context and read_lines as alternatives for exact source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Orient with this; drop to get_symbol_context / read_lines for exact source.' It clearly positions the tool for high-level orientation and round-trip savings, and contrasts with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query the internal import graph. mode=imports: what a file imports. mode=dependents: what imports it. mode=mermaid: a diagram — pass root (+depth, default 2) to walk outward from one file instead of dumping the whole graph, or scope to a path prefix. Run before refactoring a shared module.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| root | No | mermaid: start file to walk out from (BFS). | |
| depth | No | mermaid: import hops to follow from root (default 2). | |
| scope | No | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full burden. It discloses behavioral traits such as the mode-dependent output (imports vs. dependents vs. a mermaid diagram), the default whole-graph dump, and the ability to scope to a path prefix. This is significant behavioral context, though it does not explicitly state that the tool is read-only or describe performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is about 70 words, front-loads the purpose, uses a colon-separated mode breakdown, and ends with a practical usage tip. Every sentence adds value with no filler, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity (three modes, five parameters, no output schema). The description covers the modes, root/depth/scope, and a use case, but it omits the meaning of 'target' and does not describe the return shape for imports/dependents (only mermaid is said to produce a diagram). This leaves the agent with uncertainty about what the other modes return.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40% (root and depth have descriptions). The description compensates by explaining the meaning of each mode, the behavior of root/depth (including default depth 2), and the scope parameter. However, the 'target' parameter is entirely undocumented in both the schema and the description, leaving a notable gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Query the internal import graph.' It then enumerates the three modes (imports, dependents, mermaid) and clarifies mermaid's behavior, which differentiates it from sibling tools like search_code or find_references. This makes the tool's purpose unambiguous and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly gives a concrete scenario: 'Run before refactoring a shared module.' It also explains when to use mermaid with root/depth versus dumping the whole graph. However, it does not mention alternative tools or provide explicit when-not-to-use guidance, so it lacks exclusions but offers clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the stored architecture cheat-sheet plus a freshness verdict: covered files that changed since it was written are flagged as reasons it may be out of date. Read it early to understand the system without re-exploring; if flagged stale, re-read the changed areas and digest_save an update.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the output includes a freshness verdict and a reason (changed files), and implies a read-only operation via 'Return'. It doesn't mention edge cases like a missing digest, but the core behavior is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence front-loads the primary purpose and key output detail; the second adds actionable guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool, the description covers the return value and how to use it. It lacks a note about behavior when no digest exists, but this is a minor gap given the simplicity and the explicit staleness guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers them. The description correctly avoids adding unnecessary parameter details, and the baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and resource ('stored architecture digest'), clearly distinguishing this tool from siblings like digest_save. It also adds what makes this tool unique: the freshness verdict that flags changed files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent to 'Read it early' and provides a conditional follow-up ('if flagged stale, re-read the changed areas and digest_save an update'). This gives clear usage context, though it doesn't explicitly mention when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a compact 'how this repo works' cheat-sheet — modules, flows, entry points, conventions — so future sessions read a page instead of re-exploring. covers (the paths it summarizes) lets later sessions be told when a covered file changed. Overwrites the previous one. Save the why and the shape, not a symbol list.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The digest prose — compact, the architecture and flows, not a file dump. | |
| covers | No | Repo-relative paths/dirs this digest summarizes (omit = whole repo). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), idempotent, and not destructive. The description adds key behavioral detail by stating 'Overwrites the previous one,' which is important for user expectations. It also explains the mechanism of 'covers' for future change notification. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary purpose, and each clause earns its place. It avoids fluff and includes a clear directive ('Save the why and the shape').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple save tool with no output schema and only two well-documented parameters. The description, combined with annotations and schema, fully conveys the tool's behavior, including overwrite semantics and the role of covers. It does not discuss error handling or return values, but that is not critical for this straightforward tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The schema already describes 'text' and 'covers' well, and the tool description reinforces this with guidance like 'the why and the shape, not a symbol list' and 'omit = whole repo' for covers, but it does not add substantial new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Store') and the specific resource ('a compact 'how this repo works' cheat-sheet'), and distinguishes it from sibling tools like digest_get (retrieval) and memory_save (general memory). It also clarifies what the digest should contain ('modules, flows, entry points, conventions'), avoiding ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the practical benefit ('future sessions read a page instead of re-exploring') and the role of 'covers' for tracking changed files. It implicitly indicates when to use this tool (to persist architecture knowledge) but does not explicitly contrast it with alternatives like memory_save or index_repo, so it lacks explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a symbol name in the index; return definition site(s) as path:line:col + kind. Heuristic. Paged: the total is always exact, limit/offset control how many are printed, pathPrefix scopes them.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| name | Yes | ||
| limit | No | Max sites to print (default 50). | |
| offset | No | ||
| pathPrefix | No | Only definitions under this path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that the search is heuristic, that the total count is always exact, and that limit/offset control printed results. This goes beyond a simple 'find definition' and gives useful expectations about accuracy and pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first states the core purpose, the second adds heuristic and pagination details. Every clause earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description specifies the return format (path:line:col + kind) and key behaviors (heuristic, paging). Missing details like the 'kind' parameter and usage alternatives prevent a perfect score, but overall it's well-rounded for a lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 40%, with name, kind, and offset lacking descriptions. The description compensates for name (symbol lookup), limit/offset (paging semantics), and pathPrefix (scoping), but leaves 'kind' unexplained. It adds meaningful context but doesn't fully cover all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Look up a symbol name in the index; return definition site(s) as path:line:col + kind.' This specifies the verb (look up), resource (symbol index), and output format, distinguishing it from siblings like find_references or search_code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides operational context (heuristic, paged, pathPrefix scope) but never states when to prefer this tool over alternatives such as search_symbols or find_references. No exclusions or trade-offs are mentioned, so the agent must infer usage from the tool name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whole-word textual search for a symbol, returned as path:line:col with the enclosing function/class. Counts every occurrence, including repeats on one line. Not scope-aware, so may include unrelated same-named identifiers. Supports pathPrefix, limit and offset.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| limit | No | ||
| offset | No | ||
| pathPrefix | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and does so thoroughly: it discloses whole-word matching, output format, handling of repeated occurrences, scope limitations, and pagination support. This gives the agent a clear picture of expected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the core purpose, and every sentence adds value. It avoids redundancy and is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description covers the essential aspects: purpose, output format, limitations, and parameters. It is complete enough for an agent to invoke the tool correctly and interpret results without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions the symbol being searched and lists pathPrefix, limit, and offset, but does not elaborate on their exact semantics. Limit/offset are standard, but pathPrefix is named without detail, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Whole-word textual search for a symbol' with a specific output format (path:line:col with enclosing function/class). It distinguishes itself from siblings by emphasizing the textual, not scope-aware nature, which sets it apart from find_definition or search_symbols.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an implied usage context: it highlights that the search is not scope-aware and may include unrelated identifiers, suggesting it is not for precise reference resolution. However, it does not explicitly name alternatives or state when to use this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which references to a symbol live in TEST files: 'if I change calculateTax, which tests catch a break' — run exactly those, not the whole suite. Nothing covering it is surfaced as risk BEFORE you edit. Detected by path convention (.test., .spec., tests/, test_*.py …) or an indexed describe/it title. Textual, so same caveat as find_references.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| limit | No | ||
| pathPrefix | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It honestly discloses detection mechanisms (path conventions like *.test.* and indexed describe/it titles) and a limitation ('Textual, so same caveat as find_references'). It also reveals that only test references are surfaced, not other risk before editing. It does not mention side effects or return format, but for a search-like tool this is a reasonable level of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and uses the example to clarify intent. It contains four sentences, each adding value: purpose, actionable guidance, detection mechanism, and a caveat. It is slightly dense but not wasteful; the only minor issue is the reference to 'find_references' caveat without elaboration, which may be unclear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (3 params, no output schema), the description covers the core use case well but lacks details on limit and pathPrefix, and does not describe the expected output shape. For a focused search tool, it is adequate but not fully complete, especially for a newer agent trying to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It implicitly covers the sole required 'name' parameter as 'symbol', but makes no mention of the optional 'limit' or 'pathPrefix' parameters. These parameters are entirely undocumented, leaving the agent without meaning for how to use them. This is a clear gap given the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it finds references to a symbol that live in test files, with the example 'if I change calculateTax, which tests catch a break'. This distinguishes it from siblings like find_references and search_symbols by focusing specifically on test files, using a clear verb ('which references ... live in TEST files') and a concrete resource (test files). The example usage makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical context on when to use it: 'run exactly those, not the whole suite' suggests using it to target relevant tests. It also references a sibling tool ('same caveat as find_references') implicitly acknowledging an alternative. However, it does not explicitly name alternatives or state when NOT to use this tool beyond the textual caveat. This is clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ONE call for what would take several: definition, signature, callers/references (attributed to their enclosing symbol — heuristic), imports, dependents. Sections are OPT-IN via include (default definition,signature,callers,imports); add 'body' for full source, 'dependents' for reverse deps. Bounded by callerLimit and maxChars with explicit truncation.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| include | No | Which sections to return. Omit for the default set. | |
| maxChars | No | Hard cap on response size (default 12000). | |
| callerLimit | No | Max callers to list (default 12). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses that caller attribution is a heuristic ('attributed to their enclosing symbol — heuristic'), that sections are opt-in via include, and that output is bounded by callerLimit and maxChars with explicit truncation. It does not detail not-found behavior or return format, but the disclosed traits are meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and information-dense, using three sentences to cover purpose, configurable sections, and limits. Every sentence contributes value with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex with no output schema or annotations, yet the description covers its core behavior, configurable sections, defaults, and bounding limits. It does not explain the output structure or error cases, but it provides enough for an agent to select and invoke the tool correctly for most one-shot context requests.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 75% of parameters, and the description adds semantic meaning by explaining the default include set ('default definition,signature,callers,imports') and how to extend it ('add body for full source, dependents for reverse deps'). It also ties callerLimit and maxChars to truncation behavior, going beyond the schema's default-value descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is a one-call aggregation tool: 'ONE call for what would take several: definition, signature, callers/references..., imports, dependents.' It identifies a specific resource (context brief for a symbol) and distinguishes itself from single-purpose siblings by emphasizing the combined retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys strong usage context with 'ONE call for what would take several' and explains opt-in section control. It does not explicitly name when-not-to-use alternatives like find_definition or get_symbol_context, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Structural skeleton of a file: every declaration's signature with its indentation preserved and bodies replaced by ' … {line}'. Turns a 2,000-line file into a readable map for a fraction of the tokens. Use this before any full read of a file over ~300 lines.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It transparently states that bodies are replaced with ' … {line}' and that indentation is preserved, which are the key behavioral traits. It does not cover every edge case, but the core behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first defines the output, the second gives the use case and rationale. Both are information-dense with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with no output schema, the description fully covers what it does, what the output looks like, when to use it, and why (token savings). It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage for the path parameter, but the description's context makes it obvious that 'path' refers to the file to analyze. A single, self-explanatory parameter does not require extensive elaboration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as producing a structural skeleton of a file: every declaration's signature with indentation preserved and bodies replaced by a placeholder. This specific transformation distinguishes it from siblings like read_lines or outline_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit when-to-use guideline: 'Use this before any full read of a file over ~300 lines.' It does not explicitly name alternative tools or exclusions, but the threshold and context are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return ONLY the body of a symbol (function/class/method) plus a few context lines — not the whole file. Give a name (resolved via the index), several names at once, or an explicit path+line. This is the biggest per-lookup token saver. When a skeleton showed you WHERE the functions are, pull their bodies with names:[...] here — do NOT fall back to reading the whole file for a handful of bodies.
| Name | Required | Description | Default |
|---|---|---|---|
| line | No | Definition line (use with path). | |
| name | No | Symbol name to resolve via the index. | |
| path | No | File path (use with line instead of name). | |
| after | No | ||
| names | No | Several symbol names in one call — one bounded body each. The narrow alternative to a whole-file read. | |
| before | No | ||
| maxLines | No | Cap each returned span (default 200); tail elided with a notice. | |
| pathPrefix | No | Restrict name resolution to files under this prefix — disambiguates a duplicated name in ONE call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries behavioral disclosure. It clearly states output scope (body + context lines, not whole file) and index-based name resolution. It omits edge-case behavior (e.g., not found, multiple matches beyond pathPrefix) but is notably transparent for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose and immediately useful guidance. Every sentence earns its place, including the explicit 'do NOT fall back' instruction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no required fields, no output schema, and no annotations, the description covers main usage modes well. It explains how to request symbols and emphasizes token efficiency. It doesn't detail after/before defaults or maxLines cap, but schema provides those constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 75% of parameters, and description adds meaning beyond it: clarifies name is index-resolved, names allows multiple bounded bodies, path+line is an explicit alternative. It doesn't fully explain after/before semantics, but those are inferable from 'context lines' and schema bounds.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool returns the body of a symbol (function/class/method) plus a few context lines, explicitly excluding whole-file content. It clearly distinguishes this from broader file-reading tools and provides concrete usage patterns (name, names, path+line).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: after a skeleton reveals function locations, pull bodies with names; advises against falling back to whole-file reads. It also mentions it's the biggest per-lookup token saver, helping the agent choose it over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build or refresh the persistent code index (symbols + imports). Only files whose mtime changed are re-parsed, so re-run it liberally, like git fetch, before trusting a search. Honors /.slimdex.json (ignoreDirs/extensions/exclude/maxFileBytes) and reports config problems instead of ignoring them.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Ignore cache and reparse everything. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (idempotentHint=true, destructiveHint=false), the description adds meaningful behavioral details: incremental re-parsing based on mtime changes, honoring a config file (.slimdex.json), and reporting config problems instead of silently ignoring them. This provides valuable context for the agent about side effects and error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary purpose, followed by usage guidance and config behavior. Every sentence adds distinct value: purpose, re-run guidance, and config handling. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one optional parameter, no output schema) and the description covers its purpose, usage timing, incremental behavior, and config handling. It does not explicitly describe return values, but the lack of an output schema and the emphasis on side effects make the description sufficiently complete for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers the only parameter (force) 100%, so the schema fully explains the parameter. The tool description does not add any parameter-specific meaning, but the behavior it describes (mtime-based caching) indirectly relates to force. With full schema coverage, no extra info in the description is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Build or refresh the persistent code index (symbols + imports)'. This uses a specific verb ('build'/'refresh') with a specific resource ('persistent code index') and differentiates it from sibling search tools like search_code and find_definition by focusing on index maintenance rather than querying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: 're-run it liberally, like git fetch, before trusting a search'. This implies it is a prerequisite for reliable search results. It does not explicitly mention alternatives or exclusions, but the usage 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.
Wire slimdex's write discipline into the CLIENT, which registering the MCP server cannot do — the protocol has no mechanism for a server to add a hook, so this is the one call that closes the gap. Writes a PreToolUse hook that speaks up ONLY when an edit re-sends 25+ lines that an indexed symbol actually covers, or a whole file over 12KB is read. Merges rather than clobbers, is idempotent, and prints exactly what changed. scope: claude-global (default, all your repos) | claude-local | claude-project | copilot-global (VS Code, all your repos) | copilot-project (.github/hooks, COMMITTED). Use uninstall:true to remove it.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Which config to write. Default claude-global; use copilot-global for a VS Code-only setup. | |
| uninstall | No | Remove the hook instead of adding it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already indicating destructive behavior (destructiveHint:true), the description adds rich context: it writes a PreToolUse hook, merges rather than clobbers, is idempotent, prints exactly what changed, and specifies the exact conditions under which the hook speaks up. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: it covers purpose, why it's needed, behavior, scope options, and uninstall. It is front-loaded with the main action and flows logically without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two parameters and no output schema, the description is fully complete. It explains what the tool does, why it's the only way, how it behaves, what it outputs, and all configuration choices. There are no gaps for the agent to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers both parameters fully (100% coverage), but the description adds value by clarifying the default scope and when to use copilot-global vs other scopes. It also reinforces the uninstall parameter's purpose. This goes beyond simple schema repetition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool installs a PreToolUse hook and explains the specific niche (closing the protocol gap where MCP servers cannot add hooks). It distinguishes this from all sibling tools, which are read/search/save tools, by being the only installation mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains why this tool is needed (the protocol limitation), when to use it (to enforce write discipline), and provides scope choices with defaults and an uninstall option. It gives clear context for selecting copilot-global for VS Code, making the usage guidance strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove one saved memory fact by its id. Permanent — no undo, and no snapshot is taken.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds crucial details beyond the destructiveHint annotation: 'Permanent — no undo, and no snapshot is taken.' This informs the agent about irreversibility and lack of backup, which is important for decision-making.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the action, scope, and a critical warning. Every word adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema) and the presence of annotations, the description is complete. It covers purpose, mechanism, and side effects, which is sufficient for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It mentions 'by its id', which gives semantic meaning to the single parameter, but it doesn't specify what the id refers to beyond the context. It is adequate but could be more explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Remove', the resource 'memory fact', and the mechanism 'by its id'. This distinguishes it from sibling memory tools like memory_save, memory_search, and memory_list, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is evident: to delete a saved memory fact when you have its id. It doesn't explicitly compare to alternatives or state when not to use it, but for a simple delete operation 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.
Full text of specific facts by id, with the provenance note of what was being examined when each was saved. The expansion half of the preview model: triage cheaply with brief/memory_list, expand only what you need.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Fact ids from memory_list/brief/memory_search. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It details the return content (full text + provenance) and implies a read-only operation via 'Read' in the title. While it doesn't explicitly state side effects or permissions, the read nature and return format are well communicated, adding useful context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core function, and includes usage guidance. Every word earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema and no annotations, the description sufficiently explains what the tool returns (full text + provenance), how to obtain ids (from memory_list/brief/memory_search), and when to use it (expand after triage). It is complete for the tool's simplicity, leaving no critical gaps for an agent to misinvoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the 'ids' parameter as fact ids from memory_list/brief/memory_search, giving 100% coverage. The description reinforces this by stating 'specific facts by id' and explains the triage/expand relationship, adding contextual meaning beyond the raw schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: retrieving full text of specific facts by id, including provenance notes. It also distinguishes itself from siblings by positioning as 'the expansion half' versus brief/memory_list for triage, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides usage guidance: 'triage cheaply with brief/memory_list, expand only what you need.' This tells the agent exactly when to use this tool versus alternatives and implies ids come from the triage tools, as confirmed in the schema description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Saved facts newest-first as PREVIEWS (id, date, tags, opening clause); memory_get ids:[…] expands the ones that matter, full:true dumps everything. Prefer brief as the opener — same previews, staleness-checked.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | Whole bodies instead of previews — costly on a large store. | |
| limit | No | Max facts (default 50). |
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 discloses that results are previews (not full bodies), that full:true is costly, and that brief offers staleness-checking (implying memory_list does not). It doesn't state the response shape or pagination behavior explicitly, but enough context is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the most critical info (what the tool returns and how to expand). Every phrase earns its place, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional params and no output schema, the description is quite complete: it explains the preview fields, ordering, the full:true alternative, and points to brief for staleness-checked previews. Minor gap: no explicit mention of the response container (e.g., array), but this isn't critical given the preview description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% description coverage for both parameters (full and limit), including costs and defaults. The description only adds a brief mention of full:true behavior, not significantly beyond the schema. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (list saved facts), the ordering (newest-first), and the format (previews with id, date, tags, opening clause). It also distinguishes itself from siblings like memory_get and brief by specifying what it does NOT do (expand full bodies, staleness-checking).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use memory_get to expand specific ids, use full:true to dump everything, and prefer brief as the opener because it gives same previews but with staleness-checking. This makes when-to-use vs alternatives very clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a durable note (decision, gotcha, TODO, location) to /.slimdex/memory.json.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| text | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate that this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the specific file path and examples of what to save, but it does not disclose behaviors such as whether duplicate notes overwrite or append, or whether any permission is required. Given annotations cover the basic safety profile, the description provides some added context but not deep behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and target. It includes useful examples (decision, gotcha, TODO, location) and exact file path without any fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only 2 parameters and no output schema, the description covers the core purpose and file location, but it omits the 'tags' parameter semantics. It also does not clarify behavior on duplicates or whether it appends to the JSON file. While low complexity, the missing tag explanation and minor behavioral gaps prevent a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clearly implies the 'text' parameter via 'Save a durable note', but it completely omits any explanation of the 'tags' parameter, which is an array. Without description coverage, the agent cannot infer that tags are for categorizing notes. The description only partially clarifies parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Save') and specific resource ('a durable note' to '.slimdex/memory.json'), with concrete examples of content (decision, gotcha, TODO, location). This distinguishes it from sibling tools like memory_search or memory_delete, which handle retrieval or removal. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by listing example content types (decision, gotcha, TODO, location), suggesting it is intended for storing durable personal or project notes. However, it does not explicitly compare to alternatives like memory_get or memory_search, nor does it state when not to use it. The guidance is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find saved memory facts by substring and/or tag. Previews by default; memory_get expands one by id.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | ||
| full | No | Whole bodies instead of previews. | |
| query | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that previews are returned by default and that memory_get is the path to expand a single result. This goes beyond the schema's 'full' parameter description by adding the pointer to memory_get, which clarifies the intended interaction flow. It lacks explicit side-effect notes, but the read-only nature is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, first front-loads the core purpose and method, second adds a crucial behavioral note about previews and the alternative. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with three optional parameters and no output schema, the description covers the essential behavior: how to search, what to expect (previews), and how to get full results (memory_get). It doesn't detail the return structure, but the mention of 'id' implies results include identifiers, which is sufficient for usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only 'full' is described). The description partially compensates by indicating that 'query' performs substring matching and 'tag' filters by tag, which adds meaning beyond the parameter names. However, it doesn't clarify formats, case sensitivity, or how parameters combine, leaving room for ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb ('Find') and clearly identifies the resource ('saved memory facts') and the search method ('by substring and/or tag'). It also differentiates from siblings by noting that previews are returned by default and that memory_get expands one by id, which distinguishes it from memory_list and memory_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the tool's role (searching memory facts) and provides a clear usage boundary: previews by default, and for full expansion use memory_get. This gives context on when to use this tool versus memory_get, though it doesn't explicitly mention alternatives like memory_list or search_code.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compact outline of one file — declarations with line numbers, not the body. Orient before reading.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: it returns only declarations with line numbers, not the body, and is compact. Since no annotations are provided, this transparency is valuable. It implies a read-only operation and sets expectations for output specificity, though it doesn't discuss edge cases or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero wasted words. It front-loads the key information (what the tool does) and adds a clear secondary usage hint, making it exemplary in brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the tool's simple purpose: output format (declarations with line numbers) and intended use (orientation before reading). It doesn't elaborate on return formatting, but given the output schema absence and the straightforward nature of the tool, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has low coverage (0%) for the single 'path' parameter, and the description offers only the phrase 'one file' to clarify that path should point to a file rather than a directory. This adds minimal meaning beyond the schema, lacking details about path format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it creates a compact outline of a single file showing declarations with line numbers, explicitly excluding the body. This is specific and distinguishes it from siblings like read_lines or get_file_skeleton, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Orient before reading' provides clear context for when to use this tool—as a preparatory step to get an overview before reading the full file. However, it does not explicitly mention alternatives or exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read only lines [start..end] (1-indexed, inclusive) of a file. Cheaper than the whole file.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | ||
| path | Yes | ||
| start | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral detail: lines are 1-indexed, inclusive, and reading is cheaper than the whole file. However, with no annotations, it doesn't disclose error behavior (e.g., invalid ranges, missing files) or the return format, leaving some ambiguity for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences convey the essential information without redundancy. The description is efficiently written and every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-range tool with low complexity, the description is nearly complete: it specifies the operation, range semantics, and cost advantage. The main gap is that no output schema exists, so the return format is not disclosed, which is a minor omission for such a basic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description clarifies start and end as an inclusive 1-indexed range, which is beyond the schema's minimum=1 constraint. It does not explain the path parameter or explicitly state that end must be >= start, so the description only partially compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: reading a specific line range of a file, with the scope (start..end) and indexing semantics (1-indexed, inclusive). This distinguishes it from sibling tools like get_context or snapshot, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for partial file reads by noting it is 'cheaper than the whole file,' but it does not explicitly say when to use it versus alternatives or when not to use it. No alternative tools are named, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prior activity from the server's own tool-call journal — most-examined files, most-looked-up symbols, recent searches. Needs NO prior memory_save; works even when the last session saved nothing. recap = where sessions looked, memory = what they concluded. Normally use brief (folds both in); reach here for the raw journal.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many recent journaled calls to summarize (default 200). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the data source (server's tool-call journal), independence from prior memory_save, and the raw vs. digested nature of the output. It does not spell out side effects or return shape, but the read-only character is clearly implied by 'prior activity' and 'raw journal'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and dense: four short sentences that cover purpose, data source, usage guidance, and sibling differentiation without any filler. It is front-loaded with the core purpose and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description is remarkably complete. It conveys what the tool returns, when to use it, what it does not require, and how it relates to memory_save and brief, leaving no major contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, limit, is fully described in the schema with minimum, maximum, and a clear explanation. The tool description adds no additional parameter semantics, so the baseline of 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool surfaces prior activity from the server's own tool-call journal, listing specific content types like most-examined files and recent searches. It immediately distinguishes itself from siblings by contrasting recap vs. memory and positioning brief as the combined alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: the tool needs no prior memory_save, works even when the last session saved nothing, and should normally be bypassed in favor of brief. The instruction 'reach here for the raw journal' directly tells the agent when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a symbol by NAME — you never re-send the old body to locate the edit. Two modes: REPLACE (name/path+line plus body) overwrites an existing definition; INSERT (after:"X" or before:"X" plus body) adds a NEW symbol next to an existing one, which is what you want for 'add a method beside the related ones' — the anchor's own span comes from the index, so after means after its closing brace, not its signature line. Insert puts body in verbatim: indent it for the file, and include a leading/trailing newline if you want a blank line. range comes from the index; the file is SNAPSHOTTED first (.slimdex/snapshots), re-indexed after, and the new line span is reported so you don't re-read to verify. Safe to mix with ordinary edit tools: if the file moved under the index, a NAME is re-resolved against a fresh parse automatically (an explicit path+line still refuses, since that coordinate is yours). Ambiguous/unknown names are refused, never guessed. body = the complete replacement definition, indented for the file. edits:[…] applies several at once (one snapshot, one re-index); the batch is refused before any write if a target is ambiguous, two edits overlap, or a file isn't writable, and a write that fails mid-batch rolls the earlier files back and says so.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | The complete new definition, replacing the old one verbatim. | |
| line | No | Definition line (use with path). | |
| name | No | Symbol to replace, resolved via the index. | |
| path | No | File path (use with line instead of name). | |
| after | No | INSERT mode: add `body` as a NEW symbol immediately after this existing symbol's closing brace. Pin which occurrence with path + line when the name repeats inside one file (normal for CSS). | |
| edits | No | Several replacements, applied atomically. Each entry takes name, or path+line, plus body. | |
| before | No | INSERT mode: add `body` as a NEW symbol immediately before this existing symbol. | |
| pathPrefix | No | Disambiguate the after/before anchor when the name exists in several files. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already mark the tool as destructive and idempotent, the description adds substantial context: it snapshots the file first, re-indexes after, derives anchor spans from the index, inserts body verbatim, and guarantees atomic batch application with rollback on partial failure. It also explains that ambiguous names are refused and never guessed, offering safety details far beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but every sentence earns its place by conveying operational details essential for correct use. It is front-loaded with the core purpose ("Write a symbol by NAME") and then progressively adds mode distinctions, safety behavior, and batch semantics. Given the tool's complexity, the length is appropriate and not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a destructive hint and no output schema, the description is remarkably complete. It covers both modes, failure and refusal scenarios, interaction with the index, snapshotting and re-indexing, batch atomicity with rollback, and even reports the new line span so the agent knows the return value. No critical aspect of usage is left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already describes all parameters at 100% coverage, the description significantly enriches meaning: it explains the semantic difference between REPLACE and INSERT modes, clarifies that `after`/`before` refer to the anchor's closing brace, warns about indentation and newlines, and describes how `edits` provides atomic multi-symbol replacement. This goes well beyond the schema's literal field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: "Write a symbol by NAME" and immediately clarifies that you never need to re-send the old body. It further differentiates from sibling tools by detailing two modes (REPLACE and INSERT), making the tool's purpose unmistakable and distinct from the search/read-oriented siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: it explains that INSERT mode is "what you want for 'add a method beside the related ones'", and contrasts with ordinary edit tools by explaining name-based resolution and automatic re-resolution when files move. It also states refusals for ambiguous/unknown names and batch failure handling, effectively telling the agent when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Birds-eye overview: top directories with file counts, total lines, and symbol counts. Pass path to drill into one directory and list its largest files (with top to cap the list) — the bridge between orienting at the directory level and picking a file to skeleton. Start every session here.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | With `path`: how many files to list (default 20). | |
| path | No | Drill into this directory and list files instead of directories. | |
| depth | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It transparently describes the overview output and the drill-down behavior, including how `top` caps the list. It omits details about the `depth` parameter and does not explicitly state read-only nature, but the overview framing implies non-destructive use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and no wasted words. Every clause adds value: the overview scope, the drill-down usage, the `top` cap, and the session-start guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only overview tool with 3 optional parameters and no output schema, the description sufficiently conveys the primary outputs and the drill-down mode. It mentions the link to skeleton tools, which helps agent planning. However, it leaves the `depth` parameter unexplained and does not detail the exact return format for the drill-down view, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (top and path described). The description reinforces `path` and `top` by explaining their role in drill-down, which adds contextual meaning. However, `depth` is completely undocumented in both the schema and description, and the description does not significantly extend beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a 'Birds-eye overview' with specific outputs: 'top directories with file counts, total lines, and symbol counts.' It also distinctly frames itself as 'the bridge between orienting at the directory level and picking a file to skeleton,' which differentiates it from sibling tools like get_file_skeleton and outline_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Start every session here,' providing clear when-to-use guidance. It also explains the conditional behavior of passing `path` to drill into a directory. However, it does not explicitly name alternatives or state when not to use it, though the 'bridge... to picking a file to skeleton' implies the next step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search indexed files; return path:line:col + the matching line (+ optional caret highlight). Every occurrence on a line counts, and the reported total is exact unless the scan cap trips (then it says so). Page with limit and either offset or the opaque cursor from a previous call. Vendor/build dirs are already excluded. Use pathPrefix to scope; for symbols prefer find_definition/find_references.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max matches to return (default 20). | |
| regex | No | ||
| cursor | No | Opaque token from a previous call's 'next cursor' to fetch the next page. | |
| offset | No | Skip this many matches. Ignored if cursor is given. | |
| pattern | Yes | ||
| highlight | No | ||
| ignoreCase | No | ||
| pathPrefix | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and discloses important behaviors: every occurrence on a line counts, totals are exact unless the scan cap trips, and pagination uses either offset or an opaque cursor. It also explains the optional caret highlight and pre-excluded directories.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose and result format. Every additional sentence adds useful detail about pagination, exclusions, and alternatives, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema or annotations, the description explains the return format, pagination behavior, edge cases, and exclusions, making it largely sufficient. The only minor gaps are the undocumented 'regex' and 'ignoreCase' flags, which keep it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (38%), so the description compensates by explaining pattern, pathPrefix, limit/offset/cursor, and highlight. However, it does not clarify the 'regex' and 'ignoreCase' boolean parameters, which remain inferable but under-documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and resource ('indexed files'), and immediately specifies the output format ('path:line:col + the matching line'). It distinguishes itself from sibling tools by explicitly pointing to find_definition/find_references for symbol searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use guidance: use pathPrefix to scope, and prefer find_definition/find_references for symbols. It also notes that vendor/build dirs are already excluded, which informs expectations and prevents redundant filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Know WHAT the code does but not its name: a words query ranked over every indexed symbol by BM25 on tokenized names (camelCase/snake_case), kinds and filenames — 'validate user email' surfaces validateEmail / emailValidator. Matches WORDING, not meaning. Exact/partial name → search_symbols; literal string → search_code.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Top matches to return (default 10). | |
| query | Yes | What the code does, in words — 'parse the config file', 'retry a failed request'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: ranking by BM25, matching on tokenized names/kinds/filenames, and that it 'Matches WORDING, not meaning.' This goes beyond simple purpose and helps set expectations. However, it does not mention output format, whether an index must be pre-built, or any side effects, so it is not a perfect 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, highly efficient, and front-loaded with the main purpose. Every clause adds value: the scenario, the ranking mechanism, the example, and the sibling alternatives. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a search tool and absence of an output schema, the description covers purpose, behavior, and alternatives, plus an illustrative example. It does not explicitly mention prerequisites (e.g., whether indexing must have occurred) or return value structure, but these are not critical for selecting/invoking the tool. Slightly more context on outputs/limits would round it out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers both parameters with full descriptions (100% coverage). The description reinforces the query semantics with the phrase 'a words query' and an example, but does not add significantly more meaning beyond the schema. Thus baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: search for code by describing intent ('Know WHAT the code does but not its name'). It specifies the mechanism (BM25 over tokenized names, kinds, filenames) and provides a concrete example ('validate user email' surfaces validateEmail / emailValidator), which fully distinguishes it from sibling tools like search_symbols and search_code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is explicitly contextualized: 'Know WHAT the code does but not its name' sets the trigger. It also gives direct alternatives: 'Exact/partial name → search_symbols; literal string → search_code.' This makes it easy for an agent to decide when to pick this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find indexed symbols whose name matches a query, ranked exact > prefix > substring > subsequence. Use this when you half-remember a name ("something like handleAuth") — it reads only the index, never the files, so it is far cheaper and far less noisy than search_code for finding a declaration.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Filter by kind: function, class, method, interface, type, … | |
| limit | No | Default 25. | |
| query | Yes | ||
| pathPrefix | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the tool 'reads only the index, never the files' and describes cost/noise characteristics. This is valuable safety/performance transparency, though it doesn't mention prerequisites like repo indexing state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The first sentence states the action and ranking; the second gives usage context and an alternative. Information is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and no annotations, the description covers purpose, usage context, and cost characteristics. It lacks explicit return-format details, but the tool's function is simple enough that an agent can infer what matching symbols look like. The mention of ranking and index-only access adds necessary context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (kind and limit are described; query and pathPrefix are not). The description gives a usage example for query ('something like handleAuth') but doesn't expand on pathPrefix or limit behavior, so it only partially compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Find indexed symbols whose name matches a query' – a specific verb+resource – and adds ranking order (exact > prefix > substring > subsequence). This clearly distinguishes it from broader search tools and matches the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this when you half-remember a name' and contrasts with search_code: 'far cheaper and far less noisy than search_code for finding a declaration.' This gives both a clear use case and a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy every uncommitted file into .slimdex/snapshots// as insurance against accidental resets. Also runs automatically (at most hourly) when index_repo sees a dirty tree; newest 10 kept. Defeats a stray git checkout .; does NOT replace committing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false and destructiveHint=false, so the description carries the burden of explaining the tool's behavior. It discloses that it copies files, runs automatically at most hourly, keeps newest 10, and does not replace committing. This adds meaningful context beyond the annotations, though it does not mention details like permission requirements or exact cleanup behavior, preventing a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: three sentences, each adding essential information. The first sentence states the core action, the second covers automatic behavior and retention, and the third explains the tool's protection and limitations. No redundant or filler content exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema) and the completeness of the description, it covers all necessary aspects: what it copies, where it stores, when it runs automatically, retention policy, and what it does not do. This is fully sufficient for an agent to decide when and how to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so there are no parameter semantics to explain. The description does not need to compensate for schema gaps. Per the baseline rule for 0 params, this is a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: 'Copy every uncommitted file into .slimdex/snapshots/<timestamp>'. It distinguishes itself from committing by explicitly saying 'does NOT replace committing', and it provides a concrete use case (insurance against accidental resets). This makes it easy to differentiate from sibling tools like index_repo or changed_files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear when-to-use context: 'as insurance against accidental resets' and 'Defeats a stray git checkout .'. It also mentions an automatic trigger when index_repo sees a dirty tree, and explicitly states 'does NOT replace committing', which serves as a when-not-to-use. However, it does not name alternative tools explicitly, so it falls slightly short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Per-tool call counts and response sizes recorded to /.slimdex/stats.json. Reported in characters, not tokens — char/4 estimates are unreliable across tokenizers, so this measures what it can measure honestly. Use it to see which tool is actually producing your context, and to tune limits. Counters are CUMULATIVE across every session on this repo until reset. To measure ONE task: call checkpoint:true when you start, then session:true when you finish — the server is long-lived, so session:true alone means 'since the server booted', which can span several chats.
| Name | Required | Description | Default |
|---|---|---|---|
| reset | No | Clear ALL counters, including the repo's all-time history. | |
| session | No | Report what this process recorded since it started, or since the last checkpoint. | |
| checkpoint | No | Zero the session tally only (all-time history untouched). Call at the start of a task. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It discloses that counters are cumulative, explains the character-not-token choice, and clarifies the server-lifetime implication of session:true. It also reveals the file location. The main gap is that it doesn't state what happens with no flags, but overall transparency is high.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a bit longer than average but every sentence adds value: core purpose, unit rationale, usage scenario, lifetime semantics, and a concrete recipe. It is well-structured and front-loaded with the main idea, earning a 4 rather than a 3, though not as tight as a two-sentence description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three boolean flags and no output schema, the description is quite complete. It covers the data source, units, persistence, and a specific workflow. The only notable omission is the default behavior when no flags are passed (whether it just reports current totals), but this is a minor gap given the schema implies optional flags.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between checkpoint and session and how reset interacts with cumulative counters. This goes beyond simply restating schema fields, so a 4 is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool provides per-tool call counts and response sizes, and its purpose is to see which tool is producing context. The verb 'use it to see' gives a functional role, but it doesn't explicitly state 'reports' or 'retrieves', and the resource is a stats file. It does distinguish from siblings by its accounting focus, but the lack of a direct command verb holds it back from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use ('use it to see which tool is actually producing your context, and to tune limits') and provides a precise recipe for a one-task measurement (checkpoint:true then session:true). It doesn't mention when not to use it or alternatives, but the guidance covers the key scenarios. This is strong but not exhaustive enough for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0batchbriefchanged_filescontext_packdep_graphdigest_getdigest_savefind_definitionfind_referencesfind_testsget_contextget_file_skeletonget_symbol_contextindex_repoinstall_hookmemory_deletememory_getmemory_listmemory_savememory_searchoutline_fileread_linesrecapreplace_symbolrepo_mapsearch_codesearch_intentsearch_symbolssnapshotstatsMost tools have clear, distinct purposes, but the large number of search/navigation tools (search_code, search_symbols, search_intent, find_definition, find_references, find_tests) could still cause misselection. The detailed descriptions mitigate ambiguity, though some overlap remains among context retrieval tools (get_context, get_symbol_context, context_pack).
The majority of tools follow a predictable verb_noun pattern (search_code, find_definition, memory_save, digest_get), but several deviate with noun-only or short names (snapshot, stats, recap, brief, batch, repo_map, dep_graph). This minor inconsistency is not chaotic but prevents a perfect score.
With 30 tools, the server is over-scoped for a single MCP server, exceeding the 'too many' threshold. Many tools serve overlapping purposes (e.g., six search tools, six context retrieval tools), and the feature set could be consolidated or split into focused sub-servers.
The tool surface covers indexing, searching, symbol lookup, context retrieval, symbol editing, memory, session recap, and repository overview. Minor gaps exist (e.g., no direct file create/delete or git history tools), but the core workflows are well-covered with no dead ends.
Shared memory for coding agents. Stop re-explaining your codebase every session.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Siddhukaushik/slimdex-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
