MIMRY’s MCP server lets coding agents query a local, deterministic code index to find the files, symbols, relationships, and tests relevant to a task without reading the whole repository.
mimry_status — check MIMRY initialization and index freshness, optionally re-hashing every file.
mimry_preflight — get task-specific readiness/context, with optional semantic matching and forced refresh.
mimry_find — rank files for a query, paginate results, filter by language/path, and optionally return bounded live-source snippets.
mimry_related — find files connected to a query through graph-aware ranking.
mimry_symbol — search indexed symbols or file names; optionally trace callers/callees up to depth 3 and disambiguate by file or line.
mimry_path — find a relationship path between two files, symbols, or queries.
mimry_impact — identify what a change touches: callers, importers, and tests to run, using a target symbol/file or working-tree changes.
mimry_why — explain why a file or symbol ranked for a task query.
mimry_feedback — record local feedback such as opened, changed, missed, ignored, or suggested files to improve future ranking.
Integrates with Amp as an MCP server, providing local repository memory, ranked files, context packs, and a code relationship graph to help coding agents find relevant files and navigate tasks.
Integrates with Hermes as an MCP server, offering local repo memory, ranked files, context packs, and code relationship graph for coding agent workflows.
Click on "Deploy 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., "@mimry what files should I read first to fix the login redirect bug?"
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.
MIMRY is a command-line tool that tells AI coding agents which files, and which lines in them, to read for a task. It parses a repository into symbols and a dependency graph, keeps the index on your machine, and ranks the files that matter for a task described in plain words. The index is deterministic: the same code gives the same graph, rankings and context pack on Windows, Linux and macOS, and no LLM is involved in building it. Agents call it from the shell or through its MCP server.
uv tool install mimryRequires Python 3.11 or newer on Windows, Linux or macOS.
pipx install mimry also works.
On distros that block system pip, see Without uv.
The first index downloads the tree-sitter grammars it needs, once per user, and keeps them in a cache.
To upgrade, runmimry upgrade.
On Windows, mimry upgrade refuses while MIMRY servers run, and mimry upgrade --stop-servers stops them first.
uv is the recommended way to install MIMRY, but it is not required. MIMRY needs Python 3.11 or newer in an environment of its own. pipx and a venv use the Python 3 on your PATH, which must be 3.11 or newer.
pipx: install pipx with sudo pacman -S python-pipx on Arch or sudo apt install pipx on Debian and Ubuntu, then run pipx install mimry.
A plain virtual environment: on Debian and Ubuntu, install python3-venv first with sudo apt install python3-venv.
Run python3 -m venv ~/.local/share/mimry-venv, then ~/.local/share/mimry-venv/bin/pip install mimry.
Put the command on your PATH with mkdir -p ~/.local/bin and then ln -s ~/.local/share/mimry-venv/bin/mimry ~/.local/bin/mimry.
On distros that block system pip, a plain pip install mimry fails with externally-managed-environment.
These include Arch, CachyOS, Debian 12 and later, and Ubuntu 23.04 and later, so one of the options above is needed there.
Do not use --break-system-packages.
On Arch, sudo pacman -S uv also works.
An AUR package is coming, see #64.
mimry upgrade uses the same tool that installed MIMRY, so run it the same way.
The image ghcr.io/jbacalso24/mimry has every tree-sitter grammar built in, so indexing needs no network.
Tags are latest, the full version such as 1.2.3, and the minor line such as 1.2.
Mount your repo at /repo and keep the index in a named volume at /cache.
Without the volume, each container starts with no index.
On Linux, add --user "$(id -u):$(id -g)" so the .mimry/ folder MIMRY writes in your repo belongs to you.
docker run --rm -v "$PWD:/repo" -v mimry-cache:/cache ghcr.io/jbacalso24/mimry init
docker run --rm -v "$PWD:/repo" -v mimry-cache:/cache ghcr.io/jbacalso24/mimry index
docker run --rm -v "$PWD:/repo" -v mimry-cache:/cache ghcr.io/jbacalso24/mimry find "<query>"For an agent, run the MCP server over stdio with the same mounts:
docker run -i --rm -v "$PWD:/repo" -v mimry-cache:/cache ghcr.io/jbacalso24/mimry mcpIn an MCP client config, use the repo's absolute path, because $PWD is not expanded there:
{
"mcpServers": {
"mimry": {
"command": "docker",
"args": ["run", "-i", "--rm", "-v", "/absolute/path/to/repo:/repo", "-v", "mimry-cache:/cache", "ghcr.io/jbacalso24/mimry", "mcp"]
}
}
}In Claude Code, the plugin gives the agent the MIMRY skill, the hooks and the MCP server in one step.
It needs uv on your PATH and nothing else.
/plugin marketplace add jbacalso24/mimry
/plugin install mimry@mimryIt replaces mimry install --platform claude-code, so use one or the other.
It installs the skill only; for the MCP server and hooks, run mimry install --platform <name> (see Supported agents).
npx skills add jbacalso24/mimryfind can also match on meaning, so a task that describes a behaviour in other words still reaches the file that names it differently.
It is off until you install the extra and download the model:
uv tool install "mimry[embed]"
mimry embed downloadmimry embed download fetches a 64 MB MIT-licensed model (minishlab/potion-code-16M) from Hugging Face once, checks it, and keeps it in MIMRY's cache.
Every search after that runs locally, with no network calls.
It applies to long task descriptions (20 or more distinct words), where it raised SWE-bench Verified Acc@10 from 81.4% to 83.2%; short queries rank as before.
Set MIMRY_EMBED=0 to turn the signal off, and run mimry embed status to see whether it is ready.
Related MCP server: ProjectMind MCP
Run mimry preflight in your repository with a task description.
The first run builds the index.
mimry preflight "Fix session cookie not refreshed when SESSION_REFRESH_EACH_REQUEST is set"Output on the Flask repository:
Start with
1 src/flask/sessions.py
name matches · path matches · connected to other matches
read first: lines 202-206 (get_cookie_secure), 233-247 (should_set_cookie)
2 src/flask/ctx.py
name matches · connected to other matches
read first: lines 154-206 (copy_current_request_context), 395-403 (session)
3 src/flask/testing.py
name matches · connected to other matches
read first: lines 135-183 (session_transaction), 193-202 (_request_from_builder_args)The same result is written to .mimry/mimry-out/context/latest.md as a context pack for the agent, with the matched symbols, related files and the project's test commands.
To have your agent use MIMRY on its own, install it for that agent:
mimry install --platform claude-codeAdd--always-on --hooks so the agent reaches for MIMRY without being told: --always-on adds the rules to its always-read file, and --hooks suggests mimry find when it starts a broad search of the repository, at most three times a session, answers a grep for a known symbol with its definition and callers, and outlines a large file when the agent reads it whole. The hooks also refresh the index in the background when a session starts and after each file edit, and restore the files it was working on after the context is compacted.
--prompt-hook adds a prompt hook next to --hooks in Claude Code.
When you submit a task, the hook ranks it against the index and adds a short note naming the files MIMRY ranks first, with the lines to read.
The note stays under 800 characters, and the hook prints nothing for a slash command, a prompt under five words, a chat prompt that names no code, a prompt repeated in the same session, or a repo over 3000 indexed files or with a graph over 8 MB.
A prompt names code when it has an identifier, a source file name, or a word that appears in an indexed file path.
It is off unless you add it:
mimry install --platform claude-code --project --hooks --prompt-hookOn a small repo it adds about half a second to each prompt, most of it loading the search code.
Set MIMRY_PROMPT_HOOK=0 in the environment Claude Code starts in to turn it off without removing it.
Running mimry install --platform claude-code --project --hooks again without --prompt-hook removes it.
The --hooks install also adds a Stop hook.
When a turn ends it closes that turn's feedback window and writes the session's feedback, so the record does not wait for your next command.
mimry stats shows the tokens MIMRY saved in this session and across the repo.
It counts a ranged Read (one with offset or limit) of a file MIMRY named in the session, as the tokens of the rest of the file.
A search the hooks answer from the index counts as one search, never as tokens.
Tokens are estimated as characters / 4, so every number is about, not exact.
To show the session total in Claude Code's status line, set this in your Claude Code settings:
{"statusLine": {"type": "command", "command": "mimry stats --statusline"}}Feature | Description |
Ranked lookup | Ranks files by name, path, content, symbol and graph matches, and shows why each one ranked |
Line ranges | Names the functions, classes or sections to read first in each file |
Code graph | Parses 41 languages with tree-sitter: symbols, imports, calls and inheritance for code, and the names you search by for markup, style and data files |
Deterministic | The same code gives the same symbols, graph, rankings and context pack on every machine; CI checks every change against committed golden values (how) |
Documents | Indexes Markdown, text, PDF, Word, Excel and PowerPoint files alongside code |
Incremental indexing | Re-reads only changed files, and refreshes the index before the main lookups answer |
Feedback | Ranks files recorded as useful higher for similar tasks |
MCP server | Exposes every lookup as an MCP tool |
Local | Runs without an LLM, API key or telemetry, and keeps your code on your machine |
MIMRY parses these languages with tree-sitter. Programming languages give symbols, imports, calls and inheritance; markup, style and data formats give the names an agent searches them by, described below the table.
Language | Extensions |
Python |
|
JavaScript |
|
TypeScript |
|
Go |
|
Rust |
|
C# |
|
Java |
|
PHP |
|
C |
|
C++ |
|
Ruby |
|
Kotlin |
|
Scala |
|
Groovy |
|
Swift |
|
Bash |
|
PowerShell |
|
Lua |
|
Perl |
|
Dart |
|
Objective-C |
|
Zig |
|
Elixir |
|
Haskell |
|
OCaml |
|
R |
|
Julia |
|
Solidity |
|
Fortran |
|
Pascal |
|
CSS |
|
SCSS |
|
HTML |
|
Vue |
|
Svelte |
|
SQL |
|
JSON |
|
YAML |
|
TOML |
|
XML |
|
Terraform (HCL) |
|
Fortran is read in free form only. Fixed-form .f and .for files do not parse with the grammar MIMRY uses, so they get no symbols or edges.
.pp and .m are checked first, because most .pp files are Puppet and most .m files are MATLAB.
A .pp file is Pascal only when it has a unit, program or library line, and a .m file is Objective-C only when it has an @interface, @implementation, @protocol or #import line.
Any other .pp or .m file is indexed as searchable text with no symbols.
The markup and style languages get what an agent searches them by.
CSS and SCSS give their class and id selectors, custom properties, keyframes, Sass mixins, functions, placeholders and variables, with @import, @use and @forward as imports.
HTML gives each element id and the local stylesheets and scripts it loads.
Vue and Svelte give each component (named after its file) and run the JavaScript or TypeScript and CSS or SCSS passes over their <script> and <style> blocks, so their line numbers match the file.
MIMRY also indexes Markdown (headings, links, frontmatter), plain text, PDF, Word, Excel and PowerPoint files. Results name the page, section, sheet or slide that matches.
Some files get more structure than their text:
SQL: .sql files give their schema objects and the tables they touch, see below. Python string literals keep their CREATE TABLE names, and Alembic migrations keep their revision lineage.
Groovy and Gradle: .groovy, .gradle and .gvy files give their classes, interfaces, traits, enums, methods and functions, and the task entries of a Gradle build, see below.
Manifests: package.json, pyproject.toml, tsconfig.json, vite.config.*, next.config.*, app.json, app.config.*, .env.example, CLAUDE.md, AGENTS.md and README.md give their commands, frameworks, entry points and env variable names, never values.
The data formats get the names an agent looks them up by.
JSON, YAML and TOML give their keys to depth two, named by path, such as services.web or tool.ruff.line-length, and TOML also gives each table header.
A YAML document that is a Kubernetes object also gives a <kind>/<name> resource, such as Deployment/web.
XML gives each element with an id or name attribute, and a Maven pom.xml gives its groupId:artifactId.
MSBuild project and props files give each property in a PropertyGroup and each Target name, with each ProjectReference as an import, a plist gives the keys of its top-level dict, and XAML gives each x:Name and x:Key.
Terraform gives each resource, data, module, variable, output, provider and locals entry under the name it is referenced by, such as aws_s3_bucket.b, data.aws_iam_policy_document.p, module.bucket, var.region and local.name.
A var.region reference finds the variable in the same folder, and a module's local source links to its folder.
Values are never symbols, so a secret stored as a value is never indexed.
Lock files and files over 256 KiB get no symbols, and manifests keep their own adapter above.
Every data file is also indexed as text, so mimry find matches its content.
SQL files name each schema object as the source writes it, such as public.users: tables, views, materialized views, indexes, sequences, schemas and types, and functions, procedures and triggers.
A view, function, trigger or index that reads or writes a table gets a call edge to it, and so does a foreign key's REFERENCES target.
A plain query or an ALTER TABLE belongs to no object, so it adds no edge.
A statement the parser does not know costs only itself, and the objects around it are kept.
A trigger written with a BEGIN ... END body gives its name and table, but its body is not read.
Files over 256 KiB get no symbols, so a large dump stays text-searchable.
Groovy and Gradle files name each class, interface, trait, enum, method and top-level def function as the source writes it.
A Spock feature method keeps its string, such as adds two numbers, as its name.
A Gradle task name or tasks.register("name") gives a task, and plugins {} and dependencies {} entries are not symbols.
An import of a Groovy class links exactly to the file that declares it, and a wildcard import such as a.b.* links to every file of package a.b.
A static wildcard such as import static a.b.C.* links to the file of class C.
Calls inside a method body, and the extends and implements clauses of a type, give call and inheritance edges, and a paren-less name arg call counts only for a method of the same file.
A piece of a file the parser cannot read costs only itself, so an annotated type such as @Service(Book) keeps its methods.
Closure-assigned fields and operator methods such as << are not symbols.
Other extensions can be mapped to a supported language in mimry.toml, see Configuration.
mimry install --platform <name> installs a skill that teaches the agent when to use MIMRY, and registers the MCP server where the agent supports it.
Agent | Platform name | Skill | MCP server |
Claude Code |
| ✅ | ✅ |
Codex |
| ✅ | ✅ |
GitHub Copilot CLI |
| ✅ | ✅ |
GitHub Copilot in VS Code |
| ✅ | ✅ |
Gemini CLI |
| ✅ | ✅ |
OpenCode |
| ✅ | ✅ |
Kiro |
| ✅ | ✅ |
Cursor |
| ✅ | ✅ |
Amp |
| ✅ | ✅ |
Devin |
| ✅ | ✅ |
Factory Droid |
| ✅ | ✅ |
Kimi |
| ✅ | ✅ |
Kilo Code |
| ✅ | |
Antigravity, CodeBuddy, Hermes, OpenClaw, Trae | see | ✅ | |
Trae CN |
| ✅ | |
Aider, Pi Agent | see | ✅ | none |
Agent Skills |
| ✅ | none |
Windsurf |
| ✅ | |
Cline |
| ✅ | |
Roo Code |
| ✅ | |
Zed |
| ✅ | ✅, or printed to paste in when its settings file has comments |
JetBrains Junie |
| ✅ | ✅ |
Grok Build |
| ✅ | not yet |
✅ means mimry install sets it up, and manual means you add the MCP server by hand.
none means the agent has no MCP support, so the skill alone covers it.
not yet means mimry install does not register an MCP server for the agent yet.
See docs/agents.md for where each agent's files go and how its MCP server is registered.
Option | Description |
| Install into the current repository only, instead of for every repository |
| Add a short rules block to the agent's always-read file, such as |
| Suggest |
| With |
| Install the skill without registering the MCP server |
| Do not add |
claude mcp add --scope user mimry -- mimry-mcp # Claude Code
codex mcp add mimry -- mimry-mcp # CodexOther MCP clients:
{
"mcpServers": {
"mimry": { "command": "mimry-mcp" }
}
}uvx mimry mcp runs the server without installing it.
By default the server lists 9 core tools: mimry_status, mimry_preflight, mimry_find, mimry_related, mimry_symbol, mimry_path, mimry_impact, mimry_why and mimry_feedback.
The other tools stay off by default to keep the tool list small, so use the CLI for them unless you ask for them.
Set MIMRY_MCP_TOOLS=all in the server's environment to list all 24 tools, or give a comma-separated list of tool names, such as MIMRY_MCP_TOOLS=mimry_find,mimry_path.
Commands with no tool, such as mimry callers, mimry callees, mimry bench, mimry doctor, mimry report and mimry install, stay CLI-only.
An unknown name prints one line to stderr and falls back to the core tools.
MIMRY is listed in the MCP Registry as io.github.jbacalso24/mimry.
mimry preflight "<task>" # list the files and lines to read first, and write a context pack
mimry find "<query>" # rank files for a query
mimry symbol <name> # find where a function, class or heading is defined
mimry callers <name> # list the functions that call a function, from the graph
mimry callees <name> # list the functions a function calls, from the graph
mimry related "<query>" # list files connected through imports and calls
mimry explain "<task>" # show the key files and symbols, and how they connect
mimry why <file> --query "<task>" # explain why a file ranked
mimry feedback ... # record which files helped
mimry status # check whether the index is current
mimry doctor # diagnose the install and the indexSee docs/commands.md for every command and option. When something misbehaves, see docs/troubleshooting.md.
A mimry.toml at the repository root controls which files are indexed.
Commit it so everyone on the team gets the same index.
[index]
include = ["src/**", "docs/**"] # index only these paths
exclude = ["**/fixtures/**", "legacy/**"] # never index these paths
max_file_bytes = 2_000_000 # size limit per file (default 1 MB)
[index.languages]
".inc" = "php" # parse .inc files as PHP
".h" = "cpp" # parse .h headers as C++ instead of CMIMRY always skips folders named build, bin, obj, dist, target, node_modules and vendor, at any depth, along with caches and virtual environments.
include does not bring them back, so MSBuild project and props files in build/, such as build/Common.props, get no symbols.
These numbers come from a scripted retrieval benchmark, not from complete agent sessions.
Two scripted agents get the same task text and a budget of 10 file reads: one starts with mimry preflight, the other with grep.
Each follows fixed rules, and the benchmark counts the tokens it reads before it has read every file the pull request changed.
A model-driven agent chooses its reads differently, so treat these as a measure of retrieval, not a saving you are guaranteed in your own sessions.
Measured with MIMRY 0.8.4 on 44 merged pull requests from 6 open-source projects, the set rerun for every release:
How the agent reads files | Tokens saved with MIMRY | Tasks located, MIMRY / grep |
The line ranges MIMRY names first | 71.2% | 32 / 28 |
Whole files | 50.8% | 33 / 28 |
| 48.6% | 31 / 27 |
See benchmarks/tokens for the method, per-project results and how to reproduce them.
On the 500 issues of SWE-bench Verified, one mimry find with the issue text puts every file the fix changes in the top 10 for 81.4% of issues, in the top 5 for 71.8%, and first for 44.8%.
With the optional embeddings, those are 83.2%, 75.6% and 48.0%.
See benchmarks/localization for the protocol and per-repository results.
To measure MIMRY on your own repository's merged pull requests, run mimry bench; see Benchmark your repository.
Task fastapi/typer#1820 from the holdout2 run, as the scripted agents read it: "Respect wait=False when launching URLs with xdg-open".
The fix changed typer/main.py.
Its 75.3% saving is the median for that run, so it is a typical task, not the best one.
Without MIMRY
The agent runs seven keyword searches for respect, wait, false, launching, urls, xdg and open, which cost 1,927 tokens.
It then reads typer/main.py from the top, up to the benchmark's 2,000-line limit per read, which costs 13,491 tokens.
Total: 15,418 tokens.
With MIMRY
mimry preflight "Respect wait=False when launching URLs with xdg-open" costs 1,876 tokens.
The agent then reads six line ranges in the order of the context pack, which cost 1,937 tokens:
File | Lines read | Tokens |
| 44-52, 119-134 | 184 |
| 6-9 | 28 |
| 10-20 | 105 |
| 111-136, 333-368 | 536 |
| 306-309, 345-414 | 476 |
| 1474-1482, 1932-2009 | 608 |
Total: 3,813 tokens.
MIMRY opened six files instead of one and still read 75.3% fewer tokens: 3,813 against 15,418.
The numbers come from results.holdout2.ranges.0.4.1.json, measured with MIMRY 0.4.1 in token benchmark run 38884765315.
To reproduce them, see Running it.
Index. MIMRY parses each file into symbols and edges for imports, calls and inheritance, and stores the index in your user cache directory, outside the repository.
Rank. MIMRY matches a task against file names, paths, content, symbols and the graph, and drops imports it cannot resolve rather than guessing.
Refresh. Like Git, MIMRY compares file metadata and re-reads only the files that changed.
See docs/how-it-works.md for details.
Indexing and search run locally.
Credential files are skipped.
In code files, a secret-looking value is redacted before it reaches the index when it sits in an assignment such as password = "..." or cfg["password"] = "...", in a comparison such as if token == "...", in a comment, or in a URL's password or credential query.
A file is skipped when its secret cannot be redacted cleanly.
Feedback text is redacted too.
Untracked files named in .gitignore are not indexed.
Bug reports and pull requests are welcome. See CONTRIBUTING.md for setup and checks. MIMRY is in public alpha, and its interfaces may change before 1.0.
Thanks to everyone who has contributed:
Record local agent usage feedback for future ranking.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | ||
| notes | No | ||
| query | Yes | ||
| missed | No | ||
| opened | No | ||
| changed | No | ||
| context | No | ||
| ignored | No | ||
| outcome | No | unknown | |
| suggested | No | ||
| verification | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It only implies local persistence and ranking influence, but does not disclose auth needs, idempotency, error handling, or what exactly is recorded. This is a significant gap for a write/feedback 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?
The single sentence is concise and front-loaded, but it is drastically undersized for an 11-parameter tool. Brevity here reflects missing information rather than effective conciseness.
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?
Although an output schema exists and removes the need to describe return values, the description is completely inadequate for this tool's complexity. It provides no parameter semantics, no usage context, and no behavioral details despite having no annotations.
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 11 parameters with 0% description coverage, and the description mentions none of them. An agent cannot infer the meaning of fields like root, missed, opened, changed, ignored, suggested, or verification from either source.
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 (Record), resource (local agent usage feedback), and purpose (future ranking). It is clear enough to understand the tool's basic function, but it does not differentiate this feedback tool from its sibling mimry retrieval/status tools.
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?
No explicit guidance is given about when to call this tool versus alternatives. The phrase 'for future ranking' implies a post-interaction context, but there are no conditions, exclusions, or sibling references to help an agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search files, optionally with bounded live-source snippets.
Pass offset=0 on page one.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | ||
| limit | No | ||
| query | Yes | ||
| offset | No | ||
| semantic | No | ||
| snippets | No | ||
| languages | No | ||
| path_globs | No | ||
| exclude_globs | No | ||
| snippet_chars | No | ||
| snippet_lines | No | ||
| snippet_total_chars | No | ||
| snippet_total_lines | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that snippets are 'bounded' and gives the offset=0 pagination contract, but says nothing about read-only nature, what the semantic flag changes, or how the many snippet-size limits interact.
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 sentences with the core function front-loaded and no filler. But for a 13-parameter tool the treatment is under-sized rather than genuinely concise, and 'Pass offset=0 on page one' is vaguely worded.
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?
An output schema exists, so return values needn't be described. Still, a 13-param tool with no annotations and 0% schema coverage leaves the majority of inputs undocumented, so the definition is not complete enough for confident 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?
13 parameters at 0% schema description coverage, so the schema provides only names, types, and defaults. The description touches only 'snippets' and 'offset', leaving semantic, root, languages, path_globs, exclude_globs, and all snippet-size params unexplained in both the schema and the text.
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+resource ('Search files') and hints at the snippet capability via 'bounded live-source snippets'. However, it never distinguishes itself from siblings like mimry_symbol or mimry_path, so an agent cannot tell which search tool to pick from the text alone.
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 only instruction is 'Pass offset=0 on page one', which is a pagination mechanic, not routing guidance. There is no indication of when to prefer this over mimry_symbol, mimry_path, or mimry_related, so the agent gets no help choosing among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What a change touches: callers, importers and tests to run.
target is a symbol name (file picks one when several share it, and line picks by the line it starts on or spans) or a repo-relative file path. changed=True uses the working tree against HEAD instead. depth is 1 to 5, how many calls back to follow.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | ||
| line | No | ||
| root | No | ||
| depth | No | ||
| target | No | ||
| changed | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral load, and it does add real context: depth defaults to 3, is bounded to 1-5, and changed=True switches the comparison baseline to the working tree against HEAD. However it does not say whether this is a read-only analysis, how expensive it is, or what the traversal returns beyond an output schema it never mentions.
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 core purpose is front-loaded in one sentence, and the parenthetical follows immediately with target resolution rules. It is compact and every clause carries parameter or behavioral information, with only light parenthetical nesting reducing readability.
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 6-parameter tool with zero schema descriptions and no annotations, the description supplies resolution semantics, depth bounds, and the changed-mode alternative. An output schema exists so return values need not be explained, but root remains entirely undefined and the relationship to sibling analysis tools is 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?
Schema coverage is 0%, so the description is the only source of parameter meaning, and it covers target (symbol vs file path), file/line disambiguation when several symbols share a name, changed, and depth bounds. Only root goes undocumented, which is a minor gap against five well-explained 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?
Opens with a concrete verb-like framing ("What a change touches") and enumerates the exact outputs: callers, importers and tests to run. That is specific enough to separate it from mimry_related or mimry_why, though it never explicitly names those siblings as 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?
It explains how to invoke it (target as symbol or file path, changed=True to use working tree vs HEAD) but never states when this tool is preferable to mimry_why, mimry_related, or mimry_preflight. Usage is implied by the input-shape explanation rather than stated as guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a relationship path between two files/symbols/queries.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | ||
| source | Yes | ||
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only implies a read-only traversal via 'Find'. It does not disclose path semantics (e.g., dependency vs. call graph), directionality, performance, error conditions, or any side effects.
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?
A single sentence with no wasted words, front-loading the operation and the two endpoints. It is efficient but too terse to provide structure or scannable guidance, keeping it from 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?
An output schema exists, so return values need not be explained. However, for a 3-parameter tool with 0% schema coverage and no annotations, the description omits essential input semantics, usage context, and sibling differentiation, leaving the agent under-informed.
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 should compensate. It vaguely identifies source and target ('two files/symbols/queries') but gives no format, syntax, or examples, and the optional 'root' parameter is completely unmentioned.
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 ('Find') and resource ('relationship path between two files/symbols/queries'), which is clearer than a tautology. However, it does not differentiate this tool from siblings like mimry_related, mimry_route, or mimry_why, so an agent cannot tell them apart without further 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?
Provides no when-to-use guidance, no prerequisites, and no alternatives. The agent is left to infer that this is the path-finding option, but nothing in the description confirms that or excludes other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fast readiness check and task context, matching CLI preflight.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | ||
| query | Yes | ||
| semantic | No | ||
| force_refresh | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only hints that the tool is 'fast' and involves a 'readiness check'. It does not say whether the operation is read-only, whether it mutates state, what permissions are needed, or how force_refresh and semantic affect behavior. This leaves significant gaps for a tool with four parameters and no structured 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 single sentence is short but under-specified rather than appropriately concise. The second clause 'matching CLI preflight' does not earn its place because it adds no actionable information, and the overall size is inadequate for a tool with four parameters and no schema documentation.
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 a required query parameter, three optional parameters with zero schema descriptions, and no annotations, the description is completely inadequate. While an output schema exists and need not be explained, the description leaves the agent without any information about parameter meaning, required permissions, side effects, or usage 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 0%, so the description must compensate for four undocumented parameters, yet it provides no meaning for root, query, semantic, or force_refresh. The phrase 'task context' vaguely gestures at query but does not clarify format or intent, leaving the agent unable to use any parameter correctly without experimentation.
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 two vague functions ('readiness check' and 'task context') but does not specify a concrete verb+resource or distinguish this tool from its many siblings like mimry_status or mimry_find. 'Matching CLI preflight' is an opaque reference that provides no additional clarity for an agent that has not used the CLI.
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?
There is no guidance on when to use this tool versus alternatives such as mimry_find, mimry_status, or mimry_why. The description neither states prerequisites nor excludes any scenarios, leaving the agent to guess at the tool's role.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return MIMRY initialization and index freshness for a root.
Freshness trusts unchanged file metadata, like git; verify
re-hashes every file.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | ||
| verify | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It does disclose a meaningful behavioral trait, that default freshness trusts unchanged file metadata (git-like) while 'verify' re-hashes every file, implying a cost/thoroughness tradeoff. It stops short of covering permissions, latency, or what 'initialization' state actually reports.
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 tight sentences: the purpose is front-loaded, then the freshness/verify caveat follows. No filler, and the second sentence earns its place by explaining the key behavioral difference between the two modes.
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?
An output schema exists, so return values need not be described. The description adequately conveys the mechanism and the verify distinction, but with zero annotation coverage, 0% schema coverage, and no usage guidance, it is only minimally complete for a tool an agent must decide when to call.
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 explains 'verify' well (re-hashes every file) and mentions 'root', but does not clarify what root refers to or what the default null root means (cwd? inferred?), leaving half the parameter semantics implicit.
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 ('Return') and resource ('MIMRY initialization and index freshness') with scope ('for a root'), which reads clearly as a read-only status check. It is distinguishable from siblings like mimry_reindex, mimry_refresh, and mimry_init, though no sibling is named explicitly.
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 implied by the purpose: it is a status/diagnostic read, so an agent can infer it is for checking index state. However, there is no explicit 'use this when...' guidance and no routing to alternatives such as mimry_refresh or mimry_init when the index is stale.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search indexed symbols by name, falling back to file names.
Set relations to "callers" (what calls the symbol) or "callees" (what it calls), with depth 1 to 3 for how many calls away to follow. file picks one symbol when several share the name, and file may end in ":N" to pick by line; line picks the symbol that starts on that line, or else spans it. Without relations this only searches.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | ||
| line | No | ||
| name | Yes | ||
| root | No | ||
| depth | No | ||
| relations | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the depth bound (1 to 3), the meaning of the relations values, and the disambiguation rules for file/:N/line, which goes beyond the bare schema. It does not state that the operation is read-only/non-mutating, nor mention permissions, indexing requirements, or result limits.
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?
Front-loaded with the core action and free of filler; the fallback and the default-mode caveat are placed where they matter. The middle sentences about file/line disambiguation are dense and slightly run-on, but every clause carries 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?
An output schema exists, so return values need no explanation, and the description covers five of six parameters plus the traversal semantics. The unexplained root parameter and the absence of any read-vs-write statement are the remaining gaps for a six-parameter 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 0%, so the description must compensate, and it largely does: it explains name, file (including the ':N' line suffix), line (starts-on or spans semantics), relations, and depth. The only unexplained parameter is root, whose meaning must be inferred.
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+resource ("Search indexed symbols by name") and adds a fallback behavior ("falling back to file names") plus a distinct traversal mode. It does not name or contrast itself with siblings like mimry_find, mimry_related, or mimry_path, so an agent must infer the boundary from schemas alone.
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 conditional guidance for the relations parameter ("Set relations to 'callers'... or 'callees'...") and clarifies the default mode ("Without relations this only searches"). However, it never states when to prefer this tool over mimry_find, mimry_related, or mimry_impact, 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.
Explain why a file or symbol ranked for a task query.
| Name | Required | Description | Default |
|---|---|---|---|
| root | No | ||
| limit | No | ||
| query | Yes | ||
| surface | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not state that this is a read-only inspection, whether it requires a prior index/reindex, whether results are deterministic, or what the explanation contains. 'Explain' implies a read, but nothing is confirmed.
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?
A single front-loaded sentence with no waste, but it is under-specified rather than concise — the brevity costs needed detail instead of trimming 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?
An output schema exists so return-value explanation is not required, but with zero annotation coverage, 0% parameter documentation, and an undefined required 'surface' argument, the definition is not sufficient for an agent to invoke this tool 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% across 4 parameters, including the required 'surface' and 'query'. The description loosely maps 'file or symbol' and 'task query' onto two of them, but 'surface', 'root', and 'limit' are left entirely undefined and their formats are unguessable.
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 verb ('Explain') and a resource ('why a file or symbol ranked for a task query'), which is more than a tautology, but it never distinguishes itself from close siblings like mimry_explain, mimry_find, or mimry_route. An agent cannot tell from this text alone which of those to pick.
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?
There is no when-to-use guidance, no preconditions, and no mention of alternatives, despite the tool sitting in a cluster of overlapping read/explain siblings. The agent must infer the triggering context entirely.
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.6.1mimry_preflight1 field changedInput schema / properties / semanticAdded value: +{
+ "default": false,
+ "type": "boolean"
+}v0.5.0mimry_impactmimry_symbol1 field changedInput schema / properties / lineAdded value: +{
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null
+}v0.3.4mimry_briefmimry_contextmimry_digestmimry_explainmimry_feedback1 field changedInput schema / properties / outcome / enumAdded value: +[
+ "passed",
+ "failed",
+ "blocked",
+ "partial",
+ "unknown"
+]mimry_find9 fields changedInput schema / properties / exclude_globsAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null
+}Input schema / properties / languagesAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null
+}Input schema / properties / offsetAdded value: +{
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null
+}Input schema / properties / path_globsAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null
+}Input schema / properties / snippet_charsAdded value: +{
+ "default": 800,
+ "type": "integer"
+}Input schema / properties / snippet_linesAdded value: +{
+ "default": 8,
+ "type": "integer"
+}Input schema / properties / snippet_total_charsAdded value: +{
+ "default": 4000,
+ "type": "integer"
+}Input schema / properties / snippet_total_linesAdded value: +{
+ "default": 40,
+ "type": "integer"
+}Input schema / properties / snippetsAdded value: +{
+ "default": false,
+ "type": "boolean"
+}mimry_initmimry_list_adaptersmimry_plan_checkmimry_plan_digestmimry_plan_listmimry_plan_treemimry_refreshmimry_reindexmimry_routemimry_semanticmimry_symbol3 fields changedInput schema / properties / depthAdded value: +{
+ "default": 1,
+ "type": "integer"
+}Input schema / properties / fileAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null
+}Input schema / properties / relationsAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null
+}v0.2.1mimry_briefmimry_contextmimry_digestmimry_explainmimry_feedbackmimry_findmimry_initmimry_list_adaptersmimry_pathmimry_plan_checkmimry_plan_digestmimry_plan_listmimry_plan_treemimry_preflightmimry_refreshmimry_reindexmimry_relatedmimry_routemimry_semanticmimry_statusmimry_symbolmimry_whyScored across 9 tools
Most tools have distinct purposes (impact=change effects, path=relationship route, why=ranking explanation, feedback=telemetry), but there is mild overlap between mimry_preflight and mimry_status (both readiness/state checks) and between mimry_find and mimry_related (both return files for a query). The descriptions largely disambiguate these, but an agent could still hesitate on which readiness or file-retrieval call to pick.
All tools share a uniform mimry_ prefix and single lowercase word style, which is predictable and readable. However the words mix nouns (impact, path, status, symbol) and verbs (find, why, feedback), so it is consistent in form but not a strict verb_noun pattern.
Nine tools is well-scoped for a code-graph/search server, with each tool covering a distinct facet (search, symbols, relationships, impact, status, feedback). No filler or redundant entries.
The surface covers search, symbol lookup, graph relationships, change impact, ranking explanation, and readiness/freshness well. The one notable gap is a dedicated index build/reindex operation, since status/preflight only report freshness rather than triggering indexing.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Project memory, semantic code search, and grounded agent context.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Search indexed code, trace dependencies, assess change impact, and recall repository memory.