This server provides MCP tools for reading, searching, editing, and validating code in a repository.
Read code: read_range reads files or line ranges, including dependency sources and multi-file batches.
Find symbols: find locates declarations by name and returns their source; grep does literal or regex text searches with path filters and context.
Edit files: insert adds text, replace_text swaps unique strings, create_file and delete_file manage files, and apply runs multiple edits atomically.
Validate: check runs build/typecheck/tests/lint/codegen using repository commands; run_tests runs scoped tests; run_command and declare_command manage repeatable named commands.
Safety features: edits support expected revision/digest preconditions, and results can be truncated with continue handles for pagination.
Arno gives coding agents what an IDE gives you, served over MCP. Read by symbol, edit against a known revision, get the compiler's diagnostics back with the edit, validate with the repository's own commands, see what changed, and revert to a checkpoint — each step one tool call, none of it through the shell.
Symbol-aware reading is how Arno finds its way around; the transaction is what it is for. Where the shell is still the better tool, use it — the question Arno has to answer is whether an agent gets more done, at acceptable cost, with it than without (docs/benchmark.md).
Half the tokens, more issues fixed. Claude Code on 12 real closed issues from cobra (Go), ky (TypeScript), requests (Python) and ripgrep (Rust), judged by each upstream fix's own hidden tests:
Claude Code with… | Issues fixed | Tokens per task | Time per task |
its built-in tools | 10 of 12 | 1.38M | 215s |
Arno in their place | 12 of 12 | 0.68M (−51%) | 163s (−24%) |
Not just a shorter tool list: against a shell trimmed to Bash, Read, Edit and Write, Arno still used 18–25% fewer tokens and fewer turns, in two separate runs. Sonnet 5, one run per task, four languages — results and caveats · how to set it up.
Status: 0.0.11 shipped as Jade; 0.0.12 is the first release called Arno — early, usable, and looking for feedback. Testing it? Start with the tester guide.
curl -fsSL https://raw.githubusercontent.com/julianbei/arno/main/install.sh | shFor macOS and Linux — Windows isn't supported (here's why, and where to upvote). Run it again to update. Other ways to install.
Related MCP server: Serena
Thanks for testing. Half an hour gets you set up; the useful part is a week or two of your normal work with it switched on, and then telling us how it went — including if you turned it off.
macOS and Linux:
curl -fsSL https://raw.githubusercontent.com/julianbei/arno/main/install.sh | shWindows isn't supported, sorry! If you'd like it to be, please 👍 issue #2 or tell us there why it matters to you. (WSL 2 runs Linux, so the Linux build may work there, but we don't test it or take bug reports for it.)
The script picks the build for your OS and CPU, checks it against the
release's checksums and installs it to /usr/local/bin, or ~/.local/bin
when that is not writable — no sudo, no Go toolchain. If that directory is
not on PATH, it offers to add it to your shell profile, and it prints the
absolute path to use as command in your MCP client config. On a first install it then opens
arno-mcp install, a menu that installs the language servers you pick, or
shows how to install them by hand; Enter skips it, and you can run it again
any time. Run the same command again to
update — Arno tells you when a new release is out (see
Update check). (Prefer Go? go install github.com/julianbei/arno/cmd/arno-mcp@latest works too.) Arno reads
structure in every language with nothing else installed; exact references,
cross-file rename and type errors on edit need the language's server —
arno-mcp install installs these for you, or by hand:
Language | Install | Notes |
Go |
| First answer about 1.6s. |
Java |
| First answer about 8.5s while it indexes. |
Scala |
| Set |
Kotlin | — | No grammar or server yet: text search only. Tell us if you need it. |
A missing server is never an error: Arno says which answers are approximate.
For Claude Code, put this in .mcp.json at the root of the repository you
work in (other hosts: Codex CLI, goose, OpenCode):
{
"mcpServers": {
"arno": {
"type": "stdio",
"command": "arno-mcp",
"args": ["--root", "/absolute/path/to/the/repo", "--tools", "core"],
"alwaysLoad": true
}
}
}That keeps Claude Code's own tools too. For the clearest signal, run some
sessions with Arno in place of them: claude --tools "" with the same
config (why and trade-offs). Restart
or reconnect the client (/mcp) after installing or upgrading Arno.
Ask the agent: "call arno.capabilities". You should see your languages, each
with server … (not started) or no server (… not installed), plus the build
and test commands Arno found (mvn, gradle, sbt, go test). If a server
you installed shows as not installed, that is a bug report.
Work as you normally would. If you want a checklist for the first sessions:
Find and follow code: "where is X declared, and who calls it?" — find,
references.
Rename across files: a method or class used in several files — rename
(exact with gopls, jdtls or metals running).
A change in several places at once: "change the signature and update the
callers, then check it builds" — apply with check.
Run the tests that matter: run_tests with a file or test name, or apply
with check: "impact".
Repeatable commands: have the agent declare_command something you run
often (./gradlew :core:test, sbt "testOnly *ParserSpec"); later sessions
reuse it from .arno/commands.json.
Undo: checkpoint before something risky, revert if it goes wrong.
When | File this |
After a week or two — or when you turn Arno off | |
The agent used the shell although a Arno tool existed | |
A tool gave a wrong answer or failed | |
Something you wish Arno did |
The templates ask for the output of arno.capabilities and, optionally,
arno.telemetry. Neither contains source code; telemetry is
local only and records no arguments or response text, so both are
safe to paste from a private repository.
Known rough edges on the JVM: no formatter runs for Java or Scala files; large Gradle builds can make jdtls's first answer much slower than 8.5s; Kotlin has no support yet.
An agent that falls back to grep, sed and cat is operating outside any
tooling you control. No revision tracking, no guardrails, no telemetry, no way
to know what it did or why it chose to do it that way. Every shell fallback is
a hole in your visibility.
You cannot fix that by telling the model not to use the shell. The model uses the shell because the shell is cheaper — fewer tokens, fewer round trips, more flexible. So the only durable fix is to make the structural tool the cheaper option, and then measure whether you succeeded.
That is the entire bet, and it is testable. On this repository's own benchmark, Arno answers seven realistic engineering questions in 0.85x the tokens of the equivalent shell commands. It was 5.63x before responses became plain text instead of JSON — see docs/response-style.md for what changed and why.
The counter-measurement matters as much. One question asked against an unrelated repository came out at 1.36x — worse than the shell — because an ambiguous symbol name forced an extra disambiguation call. Seven scenarios at home and one away disagree, both are honest, and the second is the one that predicts outside use. The 0.0.4 pilot on four outside repositories answers it at a larger scale: used in place of Claude Code's built-in tools, Arno solved 12 of 12 real issues with 51% fewer tokens, and 18–25% fewer than a shell trimmed to four tools (docs/benchmark-results.md). Arno is not finished.
Arno's own development log (docs/feedback.md) records every time its author reached for bash instead, and why. The pattern it found was blunt: the fallbacks that survived longest each closed within two tasks of being named in the log — not when the tool shipped.
curl -fsSL https://raw.githubusercontent.com/julianbei/arno/main/install.sh | shDownloads the latest release binary for your OS and
CPU, verifies it against checksums.txt, and installs it without sudo to
/usr/local/bin or ~/.local/bin. Run it again to update: a arno-mcp
already on PATH is replaced where it is, and nothing is downloaded when it
is already current. If the directory is not on PATH, it offers to add it to
your shell profile (ARNO_ADD_TO_PATH=1 does it without asking) and prints
the absolute path to use in your MCP client config. ARNO_VERSION pins a release tag;
ARNO_INSTALL_DIR picks the directory. Read it first if you like:
install.sh.
Windows isn't supported — see issue #2, and give it a 👍 if you'd like that to change.
arno-mcp installarno-mcp install # menu: pick what to install
arno-mcp install --list # what is installed, and how the rest would be
arno-mcp install --servers go,java,scala # install these, no questions
arno-mcp install --all # every missing server this machine can installThe menu lists each language server Arno can use, whether it is installed, and
the exact command it would run — go install for gopls, brew install jdtls,
cs install metals, npm install -g for TypeScript and Pyright, rustup component add rust-analyzer, gem install ruby-lsp — and confirms before
running anything. A server with no installer on the machine gets instructions
for installing it by hand. The install script opens the menu after a first
install; ARNO_SKIP_SETUP=1 skips it.
For an agent, or any script — there is no terminal to answer a menu, so the same steps come without questions:
# install Arno and chosen servers in one go
curl -fsSL https://raw.githubusercontent.com/julianbei/arno/main/install.sh | ARNO_SERVERS=go,java sh
arno-mcp install --list --json # state of every server, as JSON
arno-mcp install --servers java,scala --dry-run # the commands, not run
arno-mcp install --servers java,scala # run them--list --json gives each server's key, whether it is installed and
where, the command that would install it on this machine, and manual
steps when there is none. arno.capabilities ends a missing server's line
with the command that installs it. Installing is deliberately not an MCP
tool: global package installs go through the agent's shell, where you approve
them.
The install script above is the easiest way. These work too.
go install github.com/julianbei/arno/cmd/arno-mcp@latest # newest
go install github.com/julianbei/arno/cmd/arno-mcp@v0.0.12 # pinned to a tagLands in $GOBIN, or $(go env GOPATH)/bin if that is unset — which is
usually ~/go/bin, and is not on PATH by default. Add it if it is not
there, then confirm:
export PATH="$PATH:$(go env GOPATH)/bin"
arno-mcp --versionIf you would rather not touch PATH, use the absolute path in your MCP client
config instead of the bare arno-mcp shown below.
Prebuilt binaries for linux and darwin on amd64 and arm64 are attached to each
GitHub release, with a
checksums.txt alongside them. Each is built natively on its own platform —
Arno links tree-sitter through cgo, so the linux builds need a reasonably
current glibc. On an older distro, build from source or use the container
image, which is statically linked against musl.
VERSION=$(curl -fsSL https://api.github.com/repos/julianbei/arno/releases/latest | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p' | head -n 1)
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -fsSL "https://github.com/julianbei/arno/releases/download/${VERSION}/arno-mcp_${VERSION}_${OS}_${ARCH}.tar.gz" \
| tar xz
sudo mv "arno-mcp_${VERSION}_${OS}_${ARCH}" /usr/local/bin/arno-mcpSince 0.0.11, each GitHub release
also carries arno-mcp_<version>.mcpb, one bundle with the binaries for macOS
and Linux on Intel and ARM. Open it with Claude Desktop, pick the repository
Arno should work on, and it runs with the core tools; no terminal and no
Docker. Language servers still come from arno-mcp install, or run without
them on tree-sitter alone.
git clone https://github.com/julianbei/arno.git
cd arno
make binary # bin/arno-mcp, version stamped from git describe
make install # or straight onto your PATHreferences and rename use gopls for their exact, compiler-resolved form.
Without it they still work — references degrades to a textual approximation
that says so in the response, and rename refuses rather than guessing.
arno-mcp install --servers go # or: go install golang.org/x/tools/gopls@latestThe same goes for every language below: arno-mcp install shows which servers
are installed and installs the rest (Language servers).
Arno is a stdio MCP server. Point your client at the binary:
{
"mcpServers": {
"arno": {
"type": "stdio",
"command": "arno-mcp",
"alwaysLoad": true,
"env": {
"ARNO_WORKSPACE_ROOT": "/absolute/path/to/the/repo/arno/should/work/on"
}
}
}
}ARNO_WORKSPACE_ROOT is the repository Arno inspects and edits. It does not
have to be the Arno checkout — pointing it somewhere else is the entire point.
A --root /path/to/repo flag takes precedence over the environment variable,
and Arno prints which of the three sources it used (flag, env, working
directory) at startup, so an agent can never quietly operate on the wrong
repository.
Arno works on a non-git directory and on a repository with no commits yet. In
both cases it says what is degraded — changes, diff, history and
checkpoint need git — and everything else keeps working.
Arno saves tokens when it replaces the agent's own tools, not when it is added next to them. Every turn resends the whole tool list, and in Claude Code the built-in tools are about 38k tokens of it. In Arno's pilot benchmark (12 real issues in cobra, ky, requests and ripgrep, one run each):
Tools | Tasks solved | Tokens per run | Time per run |
Claude Code's built-in tools | 10 of 12 | 1.38M | 215s |
Built-in tools trimmed to Bash, Read, Edit, Write | 10 of 12 | 0.90M | 213s |
Arno only, core profile | 12 of 12 | 0.68M | 163s |
Both, all built-in tools and Arno | 11 of 12 | 1.50M | 191s |
Trimming the built-in list is most of the saving on its own. Arno on top of that used 25% fewer tokens and 24% less time than the trimmed shell, and solved the two tasks both shell setups failed. Given both Arno and every built-in tool, the agent used Bash for four calls in five and paid for both lists. To run Arno in place of the built-in tools:
claude --tools "" --mcp-config arno.jsonwith arno.json passing the core profile, which lists twelve tools — read,
edit, validate, and run the commands a repository declares — and keeps the
others callable:
{
"mcpServers": {
"arno": {
"type": "stdio",
"command": "arno-mcp",
"args": ["--root", "/absolute/path/to/the/repo", "--tools", "core"],
"alwaysLoad": true
}
}
}The trade-off is real: without Bash the agent cannot run arbitrary commands.
run_tests, check and repository commands declared with declare_command
cover building, testing and repeatable scripts — a declaration lives in
.arno/commands.json, so later sessions reuse it; a task that needs git operations, network access
or ad-hoc scripts needs the shell back. The numbers above are one run per task
— see docs/benchmark-results.md for the results,
a rerun after the pilot's fixes, and the caveats.
Verified with a live session — find a declaration, insert beside it, run
check — using only Arno's tools:
Codex CLI (0.154), in ~/.codex/config.toml:
[mcp_servers.arno]
command = "arno-mcp"
args = ["--root", "/absolute/path/to/the/repo", "--tools", "core"]Codex asks before every MCP tool call. With approval_policy = "never" it
refuses them outright; run codex exec --approve-for-me or approve Arno's
tools interactively.
goose (1.50), for one run:
goose run --with-extension "arno:arno-mcp --root /absolute/path/to/the/repo --tools core" -t "…"or permanently with goose configure → Add Extension → Command-line
Extension, command arno-mcp --root /absolute/path/to/the/repo --tools core.
Verified through goose's claude-code provider.
OpenCode (1.18), in opencode.json at the repository root or in
~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"arno": {
"type": "local",
"command": ["arno-mcp", "--root", "/absolute/path/to/the/repo", "--tools", "core"],
"enabled": true
}
}
}OpenCode prefixes tools with the server name, so they appear as
arno_arno_find and so on. Verified with the github-copilot provider
(Claude Sonnet 5).
Cline and Gemini CLI are not verified yet.
Without "alwaysLoad": true, Claude Code may never use Arno. Claude Code
hides MCP tools behind a tool search by default: the agent sees their names but
not their definitions, and has to search before it can call one. With its own
shell and file tools right there, it does not. In Arno's benchmark, an agent
given both Arno and the shell made no Arno call in three of three runs; the
same setup with alwaysLoad called Arno directly. Other hosts may have their
own equivalent — check that Arno's tools are actually being called.
The MCP tool catalog is fixed at connection time. A newly added tool does not appear until the client reconnects. If you upgrade Arno mid-session and a tool seems missing, reconnect before investigating.
Use the binary, not go run ./cmd/arno-mcp. A go run stanza recompiles at
every process start: measured here at 284–584ms to first handshake against 14ms
for the binary, with a warm build cache. A cold one is seconds. It also means
the server silently changes whenever the source does — useful while hacking on
Arno itself, confusing everywhere else. This repository's own .mcp.json
deliberately still uses go run for that reason.
Variable | Effect |
| Repository to operate on. Overridden by |
| Emit machine-readable JSON instead of plain text. |
| Disable local usage recording entirely. |
| Keep the telemetry log outside the workspace, one subdirectory per workspace. |
| Let metals import an sbt build so Scala edits get diagnostics. Runs sbt; creates |
| Turn off the daily check for a newer release (Update check). |
The install script reads its own:
Variable | Effect |
| Release to install, e.g. |
| Where to put |
| Language servers to install afterwards without a menu: |
| Skip the language-server step. |
| Add the install directory to the shell profile without asking. |
| Base URL of the releases, for a mirror. |
Arno is a child process, not a service, so the useful shape is to copy the binary into your own image rather than run Arno's:
FROM ghcr.io/julianbei/arno-mcp:latest AS arno
FROM your-project-base
COPY --from=arno /arno-mcp /usr/local/bin/arno-mcp
ENV ARNO_WORKSPACE_ROOT=/workspaceOr build it yourself from the included Dockerfile.
The published image is distroless/static, so it carries no git, no gopls and
no language toolchains. Arno detects each of those at runtime and degrades with
an explicit message rather than failing, so this still works — you get the
textual references fallback, and changes/diff/history/checkpoint are
off. If you want the full surface, install git and gopls in your image;
Arno will find them.
31 tools, in four groups. Every response is plain text, shaped to lead with the decisive line — the answer first, the supporting detail after, raw output only when you ask for it.
Over MCP each one is registered as arno.<name> — arno.outline,
arno.replace_symbol, and so on. The tables below use the bare name for
readability. Most MCP clients show you the prefixed name already, often with
the dot rewritten (Claude Code displays mcp__arno__arno_find). Over the wire
Arno accepts both arno.find and arno_find.
Tool | What it does |
| What Arno can do in this workspace: per language, grammar or text scan, language server state, formatter; git, validation commands, declared commands. Call it first. |
| File structure — declarations grouped by kind, without reading bodies. |
| Verbatim lines, or a whole file. |
| Locate a declaration and get its body in one call. |
| Literal or regex text search with path globs. The replacement for |
| Find usages. Exact from the language server when one is installed; a name-matched approximation otherwise, and it says which answered. |
| Pull a working set for a query. |
| Assemble the surrounding context for one symbol. |
| Directory structure. |
Symbols are addressed as path::Name, or path::Name@line when a name is
ambiguous. An ambiguous read returns the candidates with their signatures
rather than guessing.
Tool | What it does |
| Replace a whole declaration. Takes the full |
| Replace exact, unique text. Anchored on content, not line numbers. Like every text edit, returns the edited region as it now reads. |
| Replace an entire file's contents. |
| Create a new file. |
| Delete one file; directories are refused. |
| Delete one declaration. |
| Cross-file rename from the language server; refuses rather than guessing when it cannot be exact. |
| Add text without replacing anything — a new function, a new section, an extra case. Appends with no anchor; places before or after a unique anchor with one. |
| Several edits as one atomic unit — anchors validated up front, all applied or none, one revision bump and one validation at the end. |
Every edit returns consequences, not "success": the revision transition, which
symbols moved, immediate diagnostics, and the IDs of any background validation
it started. Edits accept an expectedRevision precondition; supplying it makes
a stale edit fail loudly instead of silently clobbering a concurrent change.
Tool | What it does |
| Build, typecheck or tests — discovering the repository's own command rather than assuming one: Makefile target, then npm script, cargo, Maven, Gradle, sbt, pytest/mypy or bundler, by manifest. A project it cannot identify is reported as such rather than run with the wrong toolchain. Every result names the command that ran; |
| Tests scoped to a file, a test name, or the changed files. |
| Run one of the repository's declared commands by name. |
| Add or remove a declared command. |
| Poll a background job. |
| Raw output for a job, on demand. |
Exit status is authoritative. A command that prints a success-looking line and exits non-zero fails.
Tool | What it does |
| What moved — by file and by symbol, not just by path. |
| The patch, including untracked files. |
| Which commits touched one symbol, via |
| Mark a revertible point: snapshots the files Arno edited and records git's |
| Restore those files to a checkpoint. Never moves git, and refuses if a commit landed since the checkpoint. |
| The workspace event stream. |
| How Arno's own tools have been used in this workspace. |
Discovery guesses how to build and test a repository from its manifests, and the
guess is sometimes wrong: a Makefile's python -m pytest picks the system
interpreter, npm run test runs lint and browser suites for a one-file check,
and a Go module with a TypeScript app beside it has two answers to "build". A
committed .arno/project.json states the answer once, the way an editor keeps
its settings in .vscode/:
{
"areas": [
{ "path": ".", "language": "go",
"build": "go build ./...", "test": "go test ./...",
"testName": "go test -run {name} ./..." },
{ "path": "web", "language": "typescript",
"typecheck": "node_modules/.bin/tsc --noEmit",
"test": "node_modules/.bin/vitest run",
"testFile": "node_modules/.bin/vitest run {file}",
"testName": "node_modules/.bin/vitest run {file} -t {name}" }
],
"env": { "python": ".venv/bin/python", "vars": { "CI": "1" } },
"generated": ["web/dist", "*.pb.go"],
"notes": "Browser tests need Playwright; run unit tests by file."
}Areas are parts of the repository with their own language and commands,
each run inside its path. check runs a kind in every area that declares
it; run_tests with a file uses the deepest area containing that file, with
{file} relative to the area and {name} the test name.
Empty fields fall back to discovery, so a config can state only what discovery gets wrong. A config that does not parse, names an unknown field or a path outside the workspace fails the check instead of being ignored.
env puts the interpreter's directory first on PATH and adds the
variables to every command. generated paths are skipped by grep,
find and the workspace tree. notes, with the list of areas, is sent
to the agent when a session starts.
check with dryRun says when a command comes from .arno/project.json.
arno-mcp init --root /path/to/repo drafts the file from discovery, one area,
for you to review and commit; it never overwrites an existing one.
Beyond build and test, every repository has its own verbs — lint, codegen, migrate, release-gate — and an agent that does not know them reaches for the shell. So Arno lets it record them instead:
declare_command(name: "lint", run: "golangci-lint run ./...")
run_command(name: "lint")They live in .arno/commands.json, which is meant to be committed. It becomes
the repository's declared command vocabulary — written once by whoever (or
whatever) worked out the incantation, replayed by name forever after. Calling
run_command with no name lists what the repository declares; calling it with
an unknown name answers with the commands that do exist, so a wrong guess
teaches rather than fails.
Repository rules — Semgrep, a custom linter, a licence check — belong in
validation, and they need no integration in Arno. Declare one command that
runs the steps in order, joined with &&:
{
"validate": {
"run": "go test ./... && semgrep scan --config .semgrep.yml --error",
"description": "tests, then repository rules"
}
}or, without editing the file, declare_command(name: "validate", run: "…").
run_command(name: "validate") runs it inside Arno, so the run is part of the
session's record. Exit status decides: a rule that fails fails the run, the
steps after it do not run, and the summary leads with the failing output.
Use semgrep scan --error or the equivalent flag of your tool — a tool that
prints findings and exits 0 passes.
Structure comes from tree-sitter grammars compiled into the binary, so it
works with nothing installed. Semantics come from a real language server,
which you provide — arno-mcp install installs it for you — and arno starts
it on first use, reuses it for the session, and shuts it down on exit.
Language | Structure | Semantics, with this installed |
Go | ✅ built in |
|
TypeScript / TSX | ✅ built in |
|
JavaScript | ✅ built in |
|
Rust | ✅ built in |
|
Python | ✅ built in |
|
Ruby | ✅ built in |
|
Java | ✅ built in |
|
Scala | ✅ built in |
|
Everything else | text scan, announced | — |
Every row is verified end-to-end by make conformance, which builds an image
containing all eight servers and runs arno against a real repository per
language.
Semantic requests wait for the server to finish indexing (its $/progress
tokens), because an indexing server answers wrongly rather than slowly. When
the primary server declines a rename, arno asks the language's installed
alternative: ruby-lsp renames classes but not methods, so Ruby method rename
needs solargraph installed alongside it. With ruby-lsp alone, method
rename refuses and repeats the server's reason.
Every edit response names what checked the file (checked: pyright-langserver)
or why nothing did (not checked: app.py: pyright-langserver is not installed).
Scala needs one opt-in. metals reports errors only after importing the sbt
build, and it asks permission first, because importing runs sbt and creates
.bloop/ and .metals/ in the repository. Arno declines unless
ARNO_METALS_IMPORT=1 is set, and says so in the edit response. A repository
an editor has already imported needs no setting.
"Structure" is outline, symbol read, edit-by-symbol, grep and search.
"Semantics" is exact references, cross-file rename, and type-level
diagnostics on edit.
Arno looks for servers on PATH and in the places toolchains actually install
them — ~/go/bin, ~/.cargo/bin, ~/.local/bin, ~/.coursier/bin — because
go install puts gopls somewhere that is not on PATH by default, and a
client that only checked PATH would report Go as unsupported on a machine
that has a working gopls.
A missing server is never an error. Arno degrades to the behaviour above and says which answer you got.
Structure before source. Return the minimum sufficient representation first — outline before full source, summary before raw logs.
Deterministic tools before model reasoning. Arno orchestrates tree-sitter, git, gopls and the project's own build tooling. It does not reimplement them, and does not guess where they could answer.
Every edit has a precondition and returns consequences. An edit can name the revision it expects and is refused if Arno's revision has moved; it returns the revision transition, what changed and the diagnostics — not "success". Changes made outside Arno do not yet move the revision (release plan Phase 5).
Conclusions before logs. The verdict leads. Raw output expands on request.
Semantic operations before textual ones. But textual escape hatches stay available, because the semantic path does not always exist.
State is explicit. Revisions, checkpoints and change sets are objects, not implications.
Validation waits by default, backgrounds on request. check,
run_tests and run_command return the verdict; a long run can return a
job to poll instead.
An approximation must announce itself. When Arno falls back to a text scan or a name-matched graph, the caveat travels with the data, in the response — not in documentation the agent will never read.
Arno is model- and harness-independent. MCP is an adapter, not the architecture.
Measure agent outcomes, not infrastructure sophistication. Tokens and turns per completed task — and token reduction is worthless if the success rate drops with it.
Repository-native execution. Builds, tests and lint run through the
repository's own commands — discovered, or declared in
.arno/commands.json — inside Arno, so validation is part of the record
instead of a shell side trip.
Cheaper than the escape hatch. If the shell is easier, faster and cheaper for a workflow, Arno has failed that workflow. The benchmark, not opinion, says which (docs/benchmark.md).
The longer design document is docs/scope.md.
Arno does not try to match the shell's composability. Using the shell is a decision, not a leak, when the work is one of these:
Git operations: commit, branch, rebase, push, blame. Arno reads git
state (changes, diff, history) and never moves it.
One-off probes: curl a local server, inspect a process, check a port,
read an environment variable.
Debugging a script or a build system itself, where the question is what a shell command does rather than what the code says.
Installing dependencies and toolchains: npm install, go install,
pip install.
Network access of any kind.
What stays on Arno's side of the line, even though a shell could do it:
Builds, typechecks, tests, lint and codegen. Run them with check,
run_tests or a declared command (declare_command, then run_command).
Validation run from the shell is validation the change transaction cannot
see: no verdict in the edit record, no scoped test runner, no failure
summary.
Reading and searching code, and editing it. That is where Arno's revisions, diagnostics and provenance apply.
A command you keep running from the shell for validation belongs in
.arno/commands.json, or in .arno/project.json as an area's build or test
command.
Windows. Arno is built and tested for macOS and Linux only, and we'd rather do those two really well than three halfway. Until further notice we don't build, test or look at Windows. If you'd like Arno on Windows, please 👍 issue #2 — and if you think this is the wrong call, say so there; honest feedback is welcome. WSL 2 runs Linux, so the Linux build may work there, but it isn't tested.
This list is more useful than the feature list — it tells you what is worth reporting and what is already known. What is planned is in ROADMAP.md.
Nine languages get a real grammar; the rest fall back to a text scan.
Go, TypeScript, TSX, JavaScript, Python, Ruby, Java, Scala and Rust are
parsed properly. Anything else (Kotlin, Swift, C/C++, C#, PHP, …) is served
by a heuristic that finds some declarations and misses others — and the
amount it misses varies enormously by language, so treat those outlines as
a hint rather than an inventory. Arno always says which you got
(! no kotlin grammar — …).
Semantic features need a language server installed for that language.
Arno speaks LSP to whatever is on the machine (see
Language support). With a server, references and
rename are compiler-exact and cross-file. Without one, references
degrades to a textual approximation that says so, and rename refuses
rather than guessing — an approximate reference list is still useful to a
reader, but an approximate edit is corruption.
No completion, hover or code actions. Arno's LSP client implements what the tools need — references, rename, diagnostics — not the whole protocol.
No blame, no cross-repo work, no remote execution.
Formatting runs only where it is safe. gofmt and rustfmt always run. prettier (TypeScript/JavaScript), black or ruff (Python) and scalafmt run only when the repository declares them — its config file, and for Node and Python the project's own binary — because a formatter the project did not choose turns a one-line edit into a whole-file diff. Ruby, Java, JSON and Markdown are left as edited.
Revision tracking is Arno's own counter, not git's. It detects concurrent
edits within a session. It is not a VCS. A checkpoint snapshots the files Arno
has edited and records git's HEAD; revert restores those files and
nothing else, never moves git, and refuses once a commit has landed since the
checkpoint — undoing committed work is git's job. Checkpoints do not survive
a restart of the server.
Not hardened for untrusted input. It runs shell commands you declare and
edits files you point it at. Treat it as a development tool, and do not point
it at a repository you would not run make in. What running Arno inside a
sandbox or container does and does not cover:
Covered by Arno itself: reads and writes stay inside the workspace root,
symlinks included; dependency sources are read-only; a repository cannot
make Arno launch a binary it ships (declared commands run through the
shell you already trust, and a .arno/project.json interpreter is a path
you review in the diff).
Covered only by the sandbox: what a declared command, a Makefile
target, an npm script or a test suite does when check, run_tests or
run_command runs it — network access, files outside the workspace,
credentials in the environment. Arno runs the repository's own commands
with your environment; a malicious repository's make test is as
dangerous under Arno as in your shell.
Not covered at all: an agent asked to declare a harmful command, and language servers, which execute project configuration of their own (build scripts, plugins) when they index a workspace.
Tool names and required arguments are frozen and enforced by a test. 0.0.3
added no tools and made two arguments optional (query on find, path on
read_range), both backward compatible. Schemas and server instructions are
still read once at connection time, so reconnect after upgrading.
docs/tool-contract.md has the full surface and the
policy on what counts as a breaking change.
What is not frozen: response wording, the .arno/* file formats, the
exact spelling of symbol IDs, and everything under internal/. Treat responses
as text for a model to read, not as a format to parse. ARNO_JSON=1 gives
machine-readable output if you need to parse something.
Arno records how its own tools are used — call counts, response sizes, timing, and the failure classes that most often precede a caller giving up and using the shell.
It is written to .arno/telemetry.jsonl in your workspace and never
transmitted anywhere. It records no arguments, no response bodies and no
error text — only a 10-character hash of each call's target (path, symbol or
query), so the confusion report can tell a second tool asked about the same
thing. ARNO_TELEMETRY=0 turns it off; telemetry(reset: true) clears it.
Arno tries not to leave files in a repository it was only asked to work in:
In a git repository, before creating the log, Arno adds it to
.git/info/exclude — the clone-local ignore file, never committed — unless
git already ignores it. .gitignore is never touched. The log does not show
up as untracked, so a harness that commits every untracked file does not
commit it.
ARNO_STATE_DIR=/some/dir moves the log out of the workspace entirely, into
a subdirectory per workspace. Use it when Arno is rooted at a checkout that
something else commits or reviews wholesale.
A call Arno rejects outright (an unknown tool name) never creates the log.
.arno/commands.json is different: it is the repository's declared command
vocabulary, meant to be committed, and is only created when you declare a
command.
Separate from telemetry, Arno looks up the newest release tag on GitHub — one
unauthenticated request for releases/latest, carrying nothing about your
workspace or how you use Arno — at most once a day, in the background, with a
three-second timeout. A failed or offline check also waits a day. When a newer
release exists, it says so only where you asked what you are running:
$ arno-mcp --version
arno-mcp v0.0.12
update available: v0.0.13 (running v0.0.12) · curl -fsSL https://raw.githubusercontent.com/julianbei/arno/main/install.sh | sh, then reconnect your MCP clientand as the second line of arno.capabilities. It never appears in the server
instructions or in other tool responses. ARNO_UPDATE_CHECK=0 turns it off;
it is also off in CI (CI set) and for development builds.
It exists because response cost is invisible to whoever is reading the response. Its first live reading found a tool returning 4.6KB in 704ms on a routine call — something sixteen tasks of hand-written notes had never noticed.
docs/reporting.md says what makes a useful report. There are four issue templates:
feedback — how it went after some real use, or why you turned it off.
bug — it did the wrong thing.
friction — "I used the shell instead." This is the valuable one.
feature wish — it should be able to do X.
If you are unsure which, pick friction. It is the cheapest to write and the easiest to act on, and "it was just habit" is a real answer — we want it. Every shell fallback is a place Arno was not worth reaching for, and that is the only signal that reliably improves it.
Before filing a bug, check whether your client has reconnected since the version changed. A stale tool catalog explains a surprising share of "this tool does not exist" and "my fix did not take effect".
make build # go build ./...
make test # go test ./...
make fmt # gofmt -w ./cmd ./internal
make binary # bin/arno-mcp, version-stamped
make install # onto your PATHThe repository declares its own commands in .arno/commands.json, including
release-gate — build, vet, tests and a gofmt check, which is the gate a tag
has to pass. Run it the way an agent would: run_command(name: "release-gate").
Layout:
Path | What lives there |
The MCP stdio server — the entry point that matters. | |
A small CLI for driving the internal API directly. | |
The token benchmark: Arno against equivalent shell commands. | |
Revisions, change sets, checkpoints, git. | |
Symbol index, outlines, search, grep, references. | |
Mutation, atomic apply, formatting. | |
Immediate feedback on edits; gopls. | |
Async job runner, command discovery. | |
Per-language adapters (Go, TypeScript, Rust). | |
The declared-command registry. | |
Local usage recording. | |
MCP adapter, and the transport-independent internal API. | |
Shared request and response types. |
Contributions are welcome. The one hard rule is principle 8: if you add a code path that approximates, the response has to say so.
Apache License 2.0 — see LICENSE. Copyright 2026 Julian Amelung.
Apply several edits as one atomic unit: all land or none do. Ops: replace_text, replace_range, replace_symbol, delete_symbol, insert. Anchors are validated before anything is written, touched files are formatted, and one validation runs at the end instead of one per edit. Prefer this over several single edits when changing more than one site.
| Name | Required | Description | Default |
|---|---|---|---|
| check | No | Run one validation after all edits: build, typecheck, tests (the edited files' tests), or impact (those plus tests of callers of touched declarations). | |
| edits | Yes | Edits to apply in order. | |
| format | No | Format touched files afterwards (default true). | |
| expectedRevision | No | Revision expected before editing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors beyond the destructiveHint annotation: atomicity ('all land or none do'), validation of anchors before writing, formatting of touched files, and a single validation at the end. These are not covered by the annotation and give the agent a solid understanding of the tool's execution model.
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 concise sentences with no fluff. The core atomic behavior is front-loaded, followed by the ops list and key behavioral details. 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 complex tool with multiple edit types, the description covers the atomicity guarantee, ops, validation, formatting, and usage guidance. With full schema coverage and a single annotation, nothing essential is missing for an agent to correctly invoke and reason about 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?
Schema description coverage is 100%, so all parameters are already documented in the schema. The description does not add parameter-specific meaning beyond what the schema provides, but it does clarify the overall operation context. Baseline 3 is appropriate given the high 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 states a specific verb ('Apply') and resource (several edits as one atomic unit), lists the supported ops, and explicitly differentiates from sibling single-edit tools by noting it should be preferred when changing more than one site. An agent can clearly understand what this tool does and how it differs from alternatives.
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: 'Prefer this over several single edits when changing more than one site.' This tells the agent when to use this tool versus the single-edit siblings, and the atomicity requirement implies when it's necessary. Clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a validation command on demand and wait for the verdict: kind build (default), typecheck or tests. Uses the repository's own Makefile target, npm script or cargo command when present. Waits by default and returns pass/fail directly. Every result names the command that ran; dryRun names it without running anything. In a repository with several projects, pass target to check one; with no command at the root, the answer lists the projects.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | build (default), typecheck, tests, lint or codegen. lint and codegen run the declared commands of that kind; lint with none declared runs typecheck. | |
| wait | No | Wait for the result (default true). False returns a job ID to poll. | |
| dryRun | No | Name the command that would run, without running it. | |
| target | No | Project directory inside the workspace to check, e.g. services/api. Omit for the workspace root. | |
| timeoutSeconds | No | Bound on the wait (default 90, max 300). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only destructiveHint=false in annotations, the description carries most of the behavioral load and does so well: it waits by default, returns pass/fail directly, names the command that ran, and dryRun avoids execution. It also explains the no-command-at-root behavior. It stops short of describing the wait=false job-ID flow and lint/codegen behavior, which live only in 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?
Five compact sentences, each contributing a distinct fact: purpose/default kind, command discovery, wait behavior, result/dryRun behavior, and target/no-root behavior. Nothing is redundant and the most important information is front-loaded.
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 5-parameter tool with no output schema and a single sparse annotation, the description covers purpose, default behavior, return shape, and multi-project target handling. The remaining gap is sibling differentiation; otherwise an agent has enough 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 coverage is 100%, so the baseline is 3; the description adds real value beyond the schema by explaining target use in multi-project repos, the no-root fallback, and how dryRun reports the command without running it.
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?
It gives concrete operational guidance: wait by default, pass target for multi-project repos, and the no-root-command fallback lists projects. However, it never says when to prefer arno.check over alternatives like arno.run_tests or arno.run_command, nor what would make this tool the wrong choice.
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 concrete operational guidance: wait by default, pass target for multi-project repos, and the no-root-command fallback lists projects. However, it never says when to prefer arno.check over alternatives like arno.run_tests or arno.run_command, nor what would make this tool the wrong choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a brand-new file, and any missing parent directories. Refuses to overwrite an existing one — use replace_text or apply to modify existing content.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path to create. | |
| content | Yes | File content. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation destructiveHint:false is consistent with the 'refuses to overwrite' behavior, and the description adds key operational details: automatic parent-directory creation and refusal to overwrite. It does not mention what happens on attempt to overwrite (e.g., error type), but for a file creation tool this is adequate. No contradiction.
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 concise sentences with no redundant wording. The refusal to overwrite and the alternative tools are front-loaded, making the most important usage constraint immediately visible.
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 two-parameter file creation tool with a fully descriptive schema and a clear annotation, everything an agent needs to invoke it correctly is present: purpose, behavior, and alternatives. No output schema is needed for a void operation, and the description covers the key edge case (overwrite).
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 both parameters (path, content) are already documented. The description adds no additional meaning beyond the schema, such as format constraints or default behavior. Baseline 3 is appropriate since the schema handles 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 uses a specific verb ('create'), names the resource ('file'), and adds crucial behavior ('any missing parent directories', 'refuses to overwrite'). It explicitly distinguishes itself from siblings by pointing to replace_text and apply for modifying existing content, making it clear what this tool is for.
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 clearly states when to use this tool (creating a brand-new file) and when not to (if the file exists, use replace_text or apply). This explicit alternation gives an agent unambiguous selection criteria without needing to inspect sibling schemas.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Declare a named command in .arno/commands.json — a reproduction, a benchmark — to run with run_command in this and later sessions; the file is reviewed like any change. Declaring an existing name replaces it; do not redeclare one just to run it.
| Name | Required | Description | Default |
|---|---|---|---|
| run | No | Shell command to run from the workspace root. | |
| kind | No | Optional: lint or codegen; check with that kind runs it. | |
| name | Yes | Command name: lowercase letters, digits, ':', '_' or '-'. | |
| remove | No | Delete the named command instead of declaring it. | |
| description | No | Optional note on what the command is for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the key destructive behavior—'Declaring an existing name replaces it'—which goes beyond the destructiveHint annotation. It also notes the file is 'reviewed like any change', implying persistence and code-review implications. This is useful behavioral context.
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 states purpose, scope, and caution without any waste. It is efficient and immediately conveys the tool's core function and constraints.
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 5 parameters but only 1 required, and the description covers the essential behavioral aspects: persistence, replacement, and the caution against unnecessary redeclaration. It does not describe return values, but no output schema exists, and for a side-effect-heavy tool the main concerns are addressed. It is complete enough for an agent to call 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 coverage is 100% with all parameters described. The description adds context about the 'name' parameter (replacement behavior) but does not elaborate on other params. Since the schema already explains them, the description provides minimal extra value beyond the overall purpose.
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 ('Declare a named command') and the target resource ('.arno/commands.json'), and differentiates it from run_command by noting the command is for later use. It also gives context (reproduction, benchmark) that helps an agent understand its role.
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 the command is 'to run with run_command in this and later sessions', indicating when to use it, and warns 'do not redeclare one just to run it', which is a clear when-not. It doesn't name alternative tools, but the context makes the intended use unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a file, not a directory; fails if it does not exist. Reverting to an earlier checkpoint recreates it. To edit content use replace_text or apply.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations only declare destructiveHint, but the description adds non-obvious behavioral details: it rejects directories, fails if the file is absent, and can be reverted via checkpoint recreation. These details meaningfully inform risk and recovery expectations.
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 short sentences deliver the core action first, followed by a failure condition, undo behavior, and relevant alternatives. Every sentence earns its place and there is no redundant wording.
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 one-parameter destructive tool with no output schema, the description covers the operation, failure behavior, recovery path, and alternatives. Nothing necessary for correct invocation is missing.
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 full coverage for the single path parameter with 'File path to delete', and the description adds no additional path-specific semantics. Since schema coverage is 100%, a baseline 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 precise operation and resource, 'Delete a file', then immediately clarifies 'not a directory' and the failure condition when the file does not exist. This makes the tool's purpose unambiguous and distinguishes it from sibling tools without requiring schema inspection.
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 states when not to use the tool by excluding directories and content editing, and names the alternatives for editing: replace_text or apply. This gives an agent clear routing guidance beyond the tool's basic purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Locate declarations by name AND return their source in one call — the fused search-and-read that replaces grep -n 'func X' -A 30. Exact name matches win over substring ones. Use this instead of outline and read_range when you have not located the symbol yet. Pass queries to find several names in one call.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Narrow by kind. func/function, type/struct/class/interface, method, const, var — spellings within a family are equivalent. Empty matches any. | |
| limit | No | Maximum declarations to return (default 5). Prefer budget. | |
| query | No | Symbol name, exact or partial. | |
| budget | No | Size of the answer in tokens. Cut at whole declarations; the rest is behind continue=<handle>. | |
| queries | No | Several symbol names in one call, instead of query. Each is answered as query would be. | |
| continue | No | Handle from a cut answer: its next page. | |
| maxLines | No | Maximum lines of each body (default 40). Prefer budget. | |
| dependency | No | Look in this dependency's source instead of the workspace, read-only: a crate, Go module, npm or Python package name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation is present and the description reinforces it by describing read-only source lookup. It adds meaningful behavior beyond annotations: exact-name matches win over substring matches, and source is returned in the same call. It does not mention no-match behavior or output truncation, but budget and continue parameters partially cover the truncation path.
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 with no waste. The core purpose is front-loaded, followed by matching behavior and routing guidance. 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 an 8-parameter tool, the description supplies the essential decision and invocation context: what it finds, what it returns, when to use it, and how to batch queries. The remaining parameter semantics are fully covered by the 100%-coverage schema, so no critical invocation detail is missing.
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 description adds value by explaining the relationship between query and queries, exactly how multi-name lookup works, and the exact-vs-substring matching precedence. It leaves limit, budget, and maxLines semantics to the schema, which 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 a specific verb and resource: 'Locate declarations by name AND return their source in one call', which clearly differentiates it from read_range, grep, and outline. The fused search-and-read framing states exactly what the tool does, so an agent can select it without opening schemas.
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 routing guidance: 'Use this instead of outline and read_range when you have not located the symbol yet.' It names alternatives, states the condition for choosing this tool, frames it as replacing grep searches, and explains how to batch several names with queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Literal or regex text search across the workspace, returning path:line matches with optional trailing context — the replacement for grep -rn. Use this for anything that is not a declaration name: struct fields, string literals, error messages, config keys, or any search needing a path filter. Use find instead when you want a declaration and its body. Pass queries to search several patterns in one call.
| Name | Required | Description | Default |
|---|---|---|---|
| glob | No | Restrict by path, e.g. *.go or internal/code/*. | |
| limit | No | Maximum matches returned (default 40). The true total is always reported. Prefer budget. | |
| query | No | Text to find. | |
| regex | No | Treat query as a regular expression. grep-style \| alternation and \( \) groups work as in grep. | |
| budget | No | Size of the answer in tokens. Cut at whole matches; the rest is behind continue=<handle>. | |
| context | No | Trailing lines to show per match, like grep -A (max 40). | |
| exclude | No | Skip paths containing this substring, e.g. testdata. | |
| queries | No | Several patterns in one call, instead of query. Each is answered as query would be, with the same filters. | |
| continue | No | Handle from a cut answer: its next page. Other arguments except budget are ignored. | |
| dependency | No | Search this dependency's source instead of the workspace, read-only, at the version the project locks: a crate, Go module, npm or Python package name. Matches read as dep:<name>/<path>, which read_range accepts. | |
| ignoreCase | No | Case-insensitive match. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the safety profile is already known. The description adds meaningful behavioral context beyond that: it returns path:line matches, supports trailing context like `grep -A`, and notes that `dependency` searches are read-only. It also discloses that `continue` ignores other arguments except budget, which is a subtle behavioral trait. It doesn't mention pagination or the 'true total is always reported' behavior in the description, but the schema covers that. A 4 is appropriate because the description adds several useful behavioral details without contradicting the annotation.
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 with zero waste. The core purpose and return shape are front-loaded, the usage guidance follows immediately, and the sibling distinction is packed into the same sentence. Every clause 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 read-only search tool with 11 parameters and no output schema, the description covers the essential decision points: what it searches, what it returns, when to use it, and when to use the sibling. The schema covers parameter details. The only minor gap is that the description doesn't explicitly mention the default limit of 40 or the `continue` pagination flow, but those are in the schema and the tool is simple enough that an agent can infer the flow. A 4 is fair.
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 schema already documents all 11 parameters. The description adds some semantic value by explaining the relationship between `query` and `queries` ('Several patterns in one call, instead of query') and by clarifying that `dependency` searches are read-only. However, most parameter meaning is already in the schema, so the description doesn't need to compensate. Baseline 3 is correct.
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 a specific verb ('search'), a resource ('workspace'), and the return shape ('path:line matches with optional trailing context'). It explicitly positions itself as the replacement for `grep -rn` and distinguishes itself from `arno.find` by saying 'Use find instead when you want a declaration and its body.' This makes the tool's purpose unmistakable and differentiates it from its closest sibling.
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: 'Use this for anything that is not a declaration name: struct fields, string literals, error messages, config keys, or any search needing a path filter.' It also names the alternative (`arno.find`) and the condition that selects it ('when you want a declaration and its body'). This is exactly the kind of routing an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add text to a file without replacing anything — a new function, a new section, an extra case. Use this for additive work instead of rewriting a surrounding symbol. With no anchor it appends to the end of the file; with one it places the text before or after that anchor, refusing if the anchor is absent or matches more than once. Several additions or edits at once belong in apply.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File to add to. | |
| text | Yes | Text to insert. | |
| anchor | No | Optional. Exact, unique text to place the insertion beside. Omit to append to the end of the file. | |
| position | No | Optional. "before" or "after" the anchor. Defaults to after. | |
| expectedDigest | No | Optional. The digest from the read this edit is based on; the edit is refused if the file changed since, by anyone. | |
| expectedRevision | No | Optional. Revision expected before editing; the edit is rejected if the workspace has moved on. Omit for no precondition. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=false), the description discloses append-vs-anchor behavior and refusal conditions (missing anchor, multiple matches). This is concrete behavioral context that the annotations alone do not provide. It doesn't cover permissions, but the schema already documents digest/revision preconditions.
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 with zero filler: purpose, usage, and behavior are cleanly separated. The most important 'add without replacing' is front-loaded, and each sentence contributes new 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?
The description is complete for a single-edit tool with full schema coverage: it covers purpose, usage, anchor semantics, and points to apply for batch work. It does not describe return value behavior, but no output schema exists and the essential preconditions are in the parameter descriptions. For an agent picking and invoking 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?
Schema coverage is 100%, so the bar is moderate, but the description adds real meaning for anchor and position by explaining append default and before/after placement. It also explains refusal on ambiguous anchors, which is not in the schema. ExpectedDigest and expectedRevision are left to their schema descriptions, which is acceptable given full 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?
States a specific verb ('add') and resource ('text to a file') with a clear non-destructive scope, and explicitly distinguishes itself from rewriting (replace_text) and from apply for batch edits. The phrase 'without replacing anything' makes the tool's role 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?
Gives explicit direction: use for additive work instead of rewriting a surrounding symbol, and routes multi-edit work to apply. This tells the agent when to choose this tool and when to pick an alternative, satisfying the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a file verbatim, whole or by line range — the replacement for cat and sed -n. Omit both line numbers to read the whole file, which is how to read go.mod, a Makefile, or any JSON/YAML/TOML config that has no symbols to address. An end line past the end of the file reads to the end. A dependency's source reads as dep:/, read-only. Several ranges, in one file or many, go in one call: {"ranges": [{"path": "a.go", "lines": "280-400"}, {"path": "b.go", "lines": "700-760"}]}.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Repository-relative or workspace-relative file path. | |
| lines | No | Line range: "280-400", "280-" to the end, or "280". Omit to read the whole file. | |
| budget | No | Size of the read in tokens (default 5000). Cut at whole lines; the rest is behind continue=<handle>. | |
| ranges | No | Several reads in one call, instead of path. A range that fails reports its error without failing the others. | |
| continue | No | Handle from a cut read: the rest of it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses useful behavioral details: an end line past EOF reads to the end, dependency reads use a specialized read-only path, and multiple ranges can be batched in one call. It does not mention token budget truncation or the continue mechanism in the natural-language description, though those are documented in 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 front-loaded with the core purpose, then each subsequent sentence adds a distinct, practical detail: whole-file reads, open-ended ranges, dependency paths, and batch syntax. There is no filler or repetition, and the example is compact and directly relevant.
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 tool with no output schema, the description covers the main invocation modes, path forms, and range behavior. The budget and continue parameters are left to the schema, which documents them sufficiently. A small gap is that the natural-language description does not warn about token-limited truncation, but an agent reading the schema would still call 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 input schema already documents all five parameters with 100% coverage, so the baseline is 3. The description adds meaning by explaining the dep:<name>/<path> form for paths, the whole-file behavior when lines is omitted, and a realistic multi-range example. Budget and continue are not enriched, but they do not need to be for 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 first sentence uses a specific verb and resource ('Read a file verbatim, whole or by line range') and immediately positions the tool as a replacement for `cat` and `sed -n`. The concrete examples and dep:<name>/<path> syntax clearly identify what it is for, and the read-only intent distinguishes it from sibling editing tools like arno.insert and arno.replace_text.
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 strong usage guidance: omit line numbers for whole files, use it for config files with no symbols, handle open-ended ranges, and read dependency source via dep:<name>/<path>. It does not explicitly state when to prefer arno.grep or arno.find instead, so it stops short of full 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.
Replace an exact, unique string in a file. An anchor string does not move when the lines around it do, which is why follow-up edits address text rather than line numbers. Refuses when the anchor is absent or matches more than once — extend it with surrounding context to disambiguate. For several sites, use apply: atomic, one validation, no diagnostics from half-done intermediate states.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path to edit. | |
| newText | Yes | Replacement text. | |
| oldText | Yes | Exact text to replace. Must appear exactly once. | |
| expectedDigest | No | Optional. The digest from the read this edit is based on; the edit is refused if the file changed since, by anyone. | |
| expectedRevision | No | Revision expected before editing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond destructiveHint=true, the description adds concrete refusal behavior when the anchor is absent or ambiguous, and explains why text anchors are stable across line changes. It does not state what a successful call returns, and the atomicity note is framed as apply's property rather than this tool's.
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?
Every sentence earns its place: purpose, behavioral rationale, refusal conditions, and routing to apply. It is compact but not bloated, with the core constraint stated up front.
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?
It covers selection and invocation thoroughly: purpose, uniqueness constraints, failure modes, and major alternative. The only gap is that no output schema exists and the description does not mention what a successful edit returns, which could matter for chaining follow-up edits via expectedDigest or expectedRevision.
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, but the description adds real semantics for oldText by introducing the 'anchor' concept, the uniqueness requirement, and disambiguation guidance. The expectedDigest and expectedRevision parameters are already well documented in 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 first sentence names a specific operation, 'Replace an exact, unique string in a file', and the uniqueness qualifier makes the scope clear. It is also distinguished from arno.apply for multiple sites, so an agent can tell which tool applies.
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 states when this tool is appropriate, how to react to refusal by extending the anchor with context, and where not to use it: 'For several sites, use apply'. This gives clear selection guidance against a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a command the repository declares, by name, and wait for the verdict: pass/fail with the decisive output. Use it instead of a shell for anything check does not cover. No name lists the declared commands. Nothing fits? declare_command it once.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Declared command to run. Omit to list the declared commands. | |
| wait | No | Wait for the result (default true). False returns a job ID to poll. | |
| timeoutSeconds | No | Bound on the wait (default 90, max 300). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already carries destructiveHint=true, and the description adds that the tool runs commands and returns a pass/fail verdict. It does not describe side effects or environment impact, but it does not contradict the annotations, so a middle score is appropriate.
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 short and front-loaded with the core action and outcome. Each sentence earns its place, though the phrasing 'No name lists the declared commands' is slightly awkward.
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 covers the core behavior, the alternative for undeclared commands, and the list behavior when name is omitted. Combined with the schema's wait and timeout documentation, an agent has enough to call the tool correctly, though return details are brief.
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?
All three parameters are fully documented in the input schema, including default values and behavior when name is omitted. The description adds little beyond the schema, so it meets but does not exceed 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 clearly states the tool runs a repository-declared command by name and waits for a pass/fail verdict with decisive output. It distinguishes itself from shell use and from check, though it does not explicitly differentiate from the run_tests sibling.
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 guidance: use this instead of a shell for anything check does not cover, and if no matching command exists, declare one once. This names the alternatives and the conditions that select them, leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rerun a failing test, a test file, or changed files' tests; waits for pass/fail and the first failure. Full suite: check kind tests.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Test file to run, for scope=file (Go: its package). With scope=test, limits the name filter to this file. | |
| test | No | Test name, for scope=test: exact in Go, the runner's name filter elsewhere (jest/vitest -t, ava --match, pytest -k, cargo test <name>). | |
| wait | No | Wait for the result (default true). False returns a job ID to poll. | |
| scope | No | all (default), file, test or changed. | |
| timeoutSeconds | No | Bound on the wait (default 90, max 300). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations only indicate destructiveHint=false; the description adds that the tool waits for pass/fail and surfaces the first failure, which is meaningful runtime behavior. It does not detail side effects, but the test-running framing plus the non-destructive hint covers the main safety concern.
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 short, front-loaded, and free of filler, covering the core capability and an important alternative in two sentences. The 'Full suite: check kind tests' fragment is terse and slightly cryptic, which prevents a top score.
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 test-runner tool with only optional parameters and no output schema, the description conveys the essential workflow: rerun, wait, and surface the first failure. It stops short of specifying the exact result payload or how 'changed' is determined, but an agent has enough 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 coverage is 100%, so the schema fully documents all five parameters. The description's scope categories mirror the schema values without adding deeper syntax or format details, so it adds little beyond the structured parameter definitions.
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 names a specific resource (tests) and action (rerun) with explicit target scopes: a failing test, a test file, or changed files' tests. It also distinguishes itself from a full-suite path, so the agent can tell it apart from sibling commands.
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 clear context for when to use the tool — rerunning failing tests or changed scopes — and explicitly points to an alternative for full suites ('Full suite: check kind tests'). It does not exhaustively contrast every sibling, but the main boundary is stated.
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.
v0.0.12arno.applyarno.checkarno.create_filearno.declare_commandarno.delete_filearno.findarno.greparno.insertarno.read_rangearno.replace_textarno.run_commandarno.run_testsjade.applyjade.checkjade.create_filejade.declare_commandjade.delete_filejade.findjade.grepjade.insertjade.read_rangejade.replace_textjade.run_commandjade.run_testsv0.0.11jade.run_tests1 field changedInput schema / properties / scope / descriptionPrevious value: -"One of: all, file, test, changed. Defaults to all."New value: +"all (default), file, test or changed."v0.0.10jade.applyjade.checkjade.create_filejade.declare_commandjade.delete_filejade.findjade.grepjade.insertjade.read_rangejade.replace_textjade.run_commandjade.run_testsScored across 12 tools
Most tools occupy clearly distinct roles: create/read/update/delete file operations, declaration search, text search, batched edits, and validation. The only mild ambiguities are check vs. run_tests vs. run_command, and find vs. grep vs. read_range, but the descriptions do enough to steer an agent toward the right one.
Names are all lowercase and imperative, but the pattern is mixed: several are verb_noun (delete_file, read_range, replace_text, create_file, run_command, run_tests, declare_command) while others are bare verbs (find, insert, apply, check, grep). It is readable and predictable in tone, but not structurally consistent.
Twelve tools is a well-scoped set for a coding-assistant server covering file operations, search, batched edits, and validation. Each tool has a reason to exist, and none feel redundant or like filler.
Core file lifecycle, search, atomic edits, validation, and test reruns are covered, so agents can work through typical multi-step coding tasks without obvious dead ends. Minor gaps such as no explicit directory listing or rename/move operation are easily worked around with grep and read_range.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
