This server exposes repowise's codebase intelligence over MCP: explore architecture, ask evidence-grounded questions, assess change risk, triage files and symbols, find dead code, health issues, and architectural rationale.
get_overview — Get an architecture map, key modules, entry points, and repo-wide health for unfamiliar codebases.
get_answer — Ask how/where/why questions and get cited, evidence-grounded answers.
search_codebase — Hybrid search by concept, symbol, path, or page type.
get_context — Triage cards for files/modules/symbols: summaries, signatures, hotspots, decisions, fix history, relationships.
get_symbol — Return verified, line-numbered source for one symbol, live range, or omission ref.
get_risk — Assess what history says about touching files: bug fixes, churn, owners, dependents; PR mode gives directives and test recommendations.
get_change_risk — Review a commit, range, or uncommitted work: health deltas, impacted tests, prior fixes, branch overlap, change shape.
get_health — Code-health scores, findings, trends, coverage, and refactoring plans.
get_dead_code — Find unused exports, unreachable files, and zombie packages by confidence tier.
get_why — Retrieve architectural decisions, evidence, and git archaeology explaining why code is shaped as it is.
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., "@repowise show the dependency graph for the auth module"
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.
Understand the code | Change it safely | Improve it continuously |
Ask cited questions · explore architecture and execution flows · read always-current docs · recover the decisions behind the code | See symbol-level blast radius · run only the tests a diff exercises · catch missing companion files · detect breaking contracts before merge | Find defect-prone files · separate maintainability from performance risk · remove dead code · hand concrete, graph-aware refactoring plans to an agent |
These are not disconnected scanners. The graph locates what git history flags; code health measures it; tests show what guards it; decisions explain why it exists; and the same evidence reaches your agent, editor, pull request, local dashboard, and cross-repository system map.
If you care about… | Start here |
A coding agent that understands the repository | Repowise finds the right files, returns task-shaped context in fewer calls, and proactively supplies decisions and risk. For agents ↓ |
Safer pull requests and faster test feedback | Get change risk, symbol-level callers, co-change partners, and a measured or graph-inferred test run list before merge. Change intelligence ↓ |
Finding and fixing the code most likely to hurt you | A defect-validated 1–10 health score across defect risk, maintainability, and performance, followed by the concrete refactoring plan. Code health ↓ |
Understanding an estate, not one repository | Match backend and frontend contracts, catch breaking providers, map downstream services, enforce architecture rules, and query every repo through one MCP endpoint. Workspaces ↓ |
Rolling this out across an engineering organization | Keep analysis on your infrastructure, give agents and reviewers the same evidence, and add commercial licensing, security controls, custom extensions, and SLA-backed support. Teams and enterprise ↓ |
Related MCP server: CodeGraph
pip install repowise
cd /path/to/your/repo
repowise init --no-prose -y
repowise serveThat builds the graph, git, decisions, health, dead-code and structural-wiki layers
locally. Connect Claude Code, Codex, Cursor or any MCP host, or open the dashboard.
init wires Claude Code automatically. Then ask your agent: "Use Repowise
get_overview to summarize this repository" or "What breaks if I change
src/auth.py?"
Full setup, every agent, and optional model-written prose →
Every question your agent asks about a repository has an answer that could have been computed ahead of time. Who calls this function? What breaks if I change it? Why is it written this way? Which files are actually dangerous? Without an index, the agent rediscovers that answer on every task: grep, read, re-read, forget.
Repowise exposes ten task-shaped MCP tools to Claude Code, Codex, Cursor, VS Code and anything else that speaks MCP: graph, git, docs, decisions, and ten MCP tools behind one index. See the canonical surface. Most tools are built around data entities (one file, one symbol), which forces agents into long chains of sequential calls. These are built around tasks: pass several targets in one call, get complete context back.
Because the exploration work is already done, that phase mostly disappears. In a
measured agent loop across 43 questions on django/django, Repowise cut the agent's
own output by 31.6% (p<0.0001) and reached the answer in 3.8 tool calls
instead of 7.2. That is the end-to-end result.
One mechanism is much larger but narrower: loading a commit's context through
get_context costs 393 tokens instead of 13,984, or 97.2% less. That is one
retrieval payload, not a claim of 97.2% total agent savings. Both measurements and
every competitor row are published in the benchmark report.
And it arrives without being asked. Optional hooks push
context into the session at the moment it matters: the governing architectural
decision when your agent edits a file that decision covers, a warning when it touches
a file with a run of recent bug fixes, a compact briefing at session start. Repowise
also generates your CLAUDE.md and AGENTS.md from the real index, so even an agent
with no MCP support starts informed.
It learns from how you actually work. Switch on transcript capture
(repowise decision source set session --on) and Repowise reads your own agent
transcripts for the corrections you keep making ("use the shared HTTP client,
not raw requests"), turning the durable ones into tracked decisions it delivers
back later. Transcripts never leave your machine; one batched model call per
update turns the candidates that clear the deterministic gates into records, and
--no-llm keeps the gates and drops that call. The wiki generation budget tilts
toward the modules you and your agent ask about most, with no switch needed.
Foundation | What it contributes |
Graph | File + symbol dependencies across 26 AST-parsed languages, confidence-stamped call resolution, communities, centrality, cycles, and execution flows |
Git | Hotspots, ownership, co-change, bus factor, and bug-fix history: behavioral signals static analysis cannot see |
Docs | A wiki for every module and file, rebuilt incrementally with freshness and confidence scoring plus hybrid search |
Documentation drift | Your own markdown checked against the tree: the claims each document makes, resolved against the graph, and the ones the code refutes |
Decisions | Architectural rationale mined from five index-time sources plus human and agent capture, each claim traced to evidence |
Code health | 51 deterministic detectors across defect risk, maintainability, and performance, followed by concrete refactoring plans |
The structural wiki needs no model. Model-written prose is an optional upgrade, one page or directory at a time. Six of the seven decision sources are deterministic too; only comment archaeology needs a provider.
The intelligence layers → · How the graph earns trust →
Most of what an agent reads back from a shell command is noise: 300 lines of passing
tests wrapped around 4 failures, full commit bodies when it asked "what changed
recently". repowise distill <cmd> compresses command output before the agent reads
it, errors first, exit code preserved.
repowise distill pytest # 61% fewer tokens, all 11 failure lines kept
repowise distill git log -50 # 89% fewer tokens
repowise saved # what distillation saved you, in tokens and dollarsNothing is lost. Every omission leaves an inline [repowise#<ref>] marker that
repowise expand <ref> reverses in full, so the agent can always pull the detail back
without re-running the command. Small outputs pass through untouched. An opt-in hook
rewrites noisy commands automatically, shown to you for approval first.
Full guide: docs/agent/DISTILL.md →
Four deterministic signals, all computed from the graph and git history, no LLM:
Change risk. Score any commit or base..HEAD range 0-10 from the shape of
the diff, ranked against your repo's own recent commits. PR mode returns directives
rather than vibes: may_break, missing_cochanges, missing_tests, tests_to_run.
One command: repowise risk main..HEAD. (reference →)
Bug history. Which files and symbols actually get bug-fixed, and how recently. Doc, test and config commits are filtered out so the count means what it says, and a file with a run of recent fixes gets flagged as a bug magnet while you edit it. (reference →)
Test intelligence. Which tests reach a file and which ones a diff actually exercises, from the call graph, with or without a coverage report. (reference →)
Change coordination. Which other open branches edit the files you are editing,
every row saying why it is listed (same file, or a co-change pair with the commit
counts behind it), and whether the diff in front of you is one change or several
groups the index links nothing between. Both stay quiet when there is nothing to
report. repowise overlap and repowise risk.
(reference →)
Plus the free Repowise PR Bot, which puts all of it on every pull request. Zero LLM calls.
Ingest LCOV, Cobertura or Clover and you get the measured answer. Most repositories never produce one, so the graph answers instead: a test file that imports a source file reaches it, which is a recorded edge rather than the name-shaped guess everything else falls back to.
That fallback fails in both directions, and this repo is the proof. Five of its six worst bug-magnet files have no test named for them and read as untested while the graph names 3 to 23 test files each. The sixth is worse: matching on basename paired the health engine with the distill engine's tests and called it tested.
repowise impacted-tests main..HEAD # only the tests this diff actually exercises
repowise health # untested hotspots, now graph-awareDogfooded against a real coverage run --contexts=test: 95.7% precision on what reaches a file and 97.5% on the run list, at a 100% hit rate, against 72.1% and 94.8% for the one-hop import walk this replaced. The two tiers are never averaged: rows are stamped basis: "measured" or "inferred", measured wins outright where both can answer, and the inferred tier may never produce a percentage. Sound as a floor, unsound as a quantity, and labelled so. Test intelligence →
Install the GitHub App and the index shows up where the decision actually gets made. One comment per pull request, edited in place on every push rather than reposted, and a green PR gets no comment at all.
See a real comment on a real PR, not a mockup: repowise-dev/repowise#1204.
What decides a review is inline. What is context sits behind one fold, so the comment stays about seventeen rows whatever it finds.
Blast radius, at symbol level. The contracts this PR changed and every caller of them in a file the PR does not touch. Importing a module says nothing about whether the function you changed is the one being called, so file-level impact is the wrong altitude for the question a reviewer actually has.
Before you merge. The tests that import your changed files, and the files that changed alongside them in past commits but are missing here.
A Check Run that can gate the merge, with annotations on the specific lines the PR added. Advisory by default.
Change risk, scored against the repository's own commit distribution rather than an absolute scale, so it stays meaningful on a repo whose typical commit is large.
AI vs human authorship of the changed files, with the average health of each.
Then hotspots, hidden coupling, declining health, dead code and the change map, one fold down.
Markdown runs out. The comment shows three callers and says "+6 more"; the page shows all nine. Public, no sign-in, on a repository the reader has never seen.
The page leads with change risk and newly introduced findings, then maps every changed file and outside caller across the repository. See it live →
Install the PR bot → · how it works →
A score that says "this file is risky" is where most tools stop. Repowise scores every file, locates where the risk concentrates, and then names the specific fix.
Every file is scored 1-10 by 51 deterministic detectors (McCabe complexity, brain methods, LCOM4 cohesion, god classes, native Rabin-Karp clone detection, untested hotspots, change entropy, prior-defect history and more), split into three lenses: defect risk, maintainability, and performance: static N+1 and I/O-in-loop risk traced across files through the call graph, where file-local linters found 0 of the cross-function cases and repowise surfaced ~90. Only 26 of the 49 are permitted to move the defect number, because that is the number carrying published accuracy claims.
Zero LLM calls, zero cloud, zero new runtime dependencies. Pure Python over tree-sitter and git data, under 30 seconds on a 3,000-file repo, a budget enforced by a CI test, not an estimate. Marker weights are calibrated against a real defect corpus, not hand-tuned: every file scored at a commit preceding the bug window so nothing leaks backward, and an L2-logistic fit with file size as an explicit control, so a marker only earns weight for defect lift beyond being big. Only the learned constants ship.
It proves itself on your repo, not just on a benchmark. After every index, Repowise checks its own flags against your git history and reports what it found: "16 of the 20 lowest-health files had a bug fix in the last 6 months, 3.3x the 24% baseline." If that number is bad on your codebase, you will see it. (It is an association on your indexed history, not a forward prediction, the leakage-free version is in the benchmarks.)
Then it names the fix. Not "this class is too big", but Extract Class, Extract Helper, Move Method, Break Cycle, Split File, or Extract Method, with the exact methods, edges and symbols that move, the blast radius of callers and co-changing files that have to move with them, and a graph-aware ranking so a fix on a central hub outranks the same fix on a leaf. Extract Method goes down to an intra-procedural dataflow pass that lifts the exact span and infers a behavior-preserving signature.
repowise health # KPIs and lowest-scoring files
repowise health --refactoring-targets # ranked, concrete plans
repowise health --trend # snapshots plus declining-health alertsThe dashboard renders each plan as a card with a copy-to-agent button. An optional LLM step, never in the indexing path and only on request, expands any plan into generated code and a unified diff.
Validated on 21 open-source repos across 9 languages (2,826 files, scored at a fixed point and checked against the following 6 months of bug fixes, keyword-labelled): ROC AUC 0.737 [0.683, 0.787]. The signal is correlated with file size and weakens sharply within a fixed size band, which we report rather than bury. Independently recomputed from the raw data.
Against CodeScene, the leading commercial code-health tool, on the same 2,770 files and the same defect labels, ranking by repowise health surfaces 2.3x the defects under a fixed review budget (paired, p = 0.003). Full head-to-head, methodology and limitations →
Guides: code health · refactoring
repowise serve starts the full web dashboard next to the MCP server. No separate
setup, all local.
Also in there: Chat (ask the codebase in natural language) · Docs (the generated wiki, with Mermaid and a graph sidebar) · Architecture and C4 (Context → Containers → Components) · Knowledge Graph plus a zoomable canvas map · Risk, Hotspots, Coupling and Blast radius · Contributors · Decisions (evidence drawer and evolution timeline) · Symbols · Security · Dead code · Stats · Costs · Workspace.
Every view and what each one answers: docs/start/DASHBOARD.md →
Real systems are not one repository, and the expensive failures live in the gaps between them. Change a backend contract and Repowise can name the frontend calls that consume it, the services downstream, the historical companion files missing from the change, and the architecture rule the new dependency violates before it ships.
Workspace intelligence | What it answers |
Contract map | Which services provide and consume each HTTP, gRPC, event, socket, and data contract? Links retain exact/candidate confidence and the source evidence. |
Cross-repo blast radius | If this provider changes, which downstream services are in structural reach, and which ones may drift through historical co-change? |
Breaking-change guard | Was an endpoint removed or a supported OpenAPI / proto / signature shape changed incompatibly, and which consumer files are linked to that contract? |
Test impact | Which tests in the consumer repos should run for this provider change, measured from coverage or inferred from the call graph, and which links could not be determined? |
Architecture as code | Does the live system graph violate declared dependency rules or contain cycles? |
Architecture health | How coupled is the estate? Track propagation cost, the cyclic core, service roles, and a deterministic 1–10 architecture score. |
Federated context | One dashboard and one MCP server answer across every repository while preserving repo-level evidence. |
The system map models services, not merely repository boxes, and never conflates a real contract with “these files often changed together.” HTTP field-level comparison supports the bounded OpenAPI 3.x JSON subset documented in the workspace guide; matched consumers prove endpoint exposure, not field use or runtime failure.
Workspace guide and exact support matrix →
Worktrees and updates stay lightweight: a linked worktree seeds its index from the base checkout automatically, and post-commit hooks, file watching, webhooks, or polling keep each repository and the cross-repo graph current.
The Repowise VS Code extension puts the index where code actually gets written: know what your change breaks before you push (riskiest files ranked, what is downstream, forgotten companion files, missing tests, suggested reviewers), health in the gutter and status bar, callers and ownership on hover, refactoring plans as CodeLens, and the full dashboards inside the editor. One install also registers the MCP server with VS Code, so the same local index serves both you and your agent, and exposes six tools to GitHub Copilot. Quiet by default, everything toggleable, nothing leaves your machine.
Install from the Marketplace (search Repowise) or Open VSX, then run Repowise: Set Up This Repository. Guide: docs/agent/VSCODE.md →
Six agents wired end to end · two at the Full tier · every other MCP host one paste away.
Full is every surface repowise has: MCP tools, skills, slash commands, a managed instructions file, hook-level interception of tool calls, and transcript mining after the session. Good is the honest half of that: MCP tools and the config to reach them, but no hook-level interception and no transcript mining. A Good-tier agent can ask repowise anything; repowise never sees the tool calls in between. The tier is computed from what each integration actually wires, so this list cannot claim a depth the code does not have.
Everything else that speaks MCP is one snippet away. repowise agents print-config claude-code prints a stdio server entry to paste into Cline, Windsurf, Zed, Gemini
CLI or any other host that keys on mcpServers, and repowise writes nothing.
Adding an agent takes one descriptor file and one registry line, with no changes to the orchestrators. Full matrix and the contributor recipe: docs/agent/INTEGRATIONS.md →
26 languages parsed to AST · 40 on a five-rung ladder · framework-aware where an ecosystem handler exists.
"Do you support X" has five useful answers, not two, so languages land on a ladder and every rung says what it buys you.
Below those two rungs the ladder keeps going, and a language on a lower rung is still doing real work rather than being ignored:
Rung | Languages | What you get |
Full (13) | Python · TypeScript · JavaScript · Svelte · Vue · Java · Kotlin · Go · Rust · C++ · C# · Scala · Ruby | The whole pipeline: AST symbols, import resolution, a resolved call graph, heritage, docstrings, framework edges, and code-health markers |
Good (11) | C · Swift · PHP · Dart · Object Pascal · COBOL · GDScript · VB.NET · Elixir · F# · Objective-C | All of the above except the full health suite, subject to the language-specific ceilings in the full matrix |
Partial (2) | Luau / Roblox · Razor / Blazor | Luau: AST symbols and |
⎯⎯ tree-sitter parsing stops here; the rungs below come from git and imports ⎯⎯ | ||
Lightweight (6) | Clojure · Haskell · Lean 4 · Erlang · HTML · QML | A real file-to-file import graph, and no symbol-level claims |
Structural (8) | R · Zig · Julia · Elm · OCaml · Crystal · Nim · D | Git history: blame, hotspots, co-change, ownership, bug history |
Every language ships in the open-source distribution. None is gated behind the commercial licence, and none will be. COBOL now ships at the Good tier; languages still moving up the ladder are tracked on the roadmap →.
SQL and dbt projects get real ref() / source() lineage, shell scripts get
function-level symbols, HTML pages contribute their <script src> / <link href>
dependencies (including index.html → src/main.ts), and OpenAPI, Protobuf,
GraphQL, Dockerfile, Terraform and friends get dedicated handlers. Anything else is
still tracked through git history: blame, hotspots, co-change.
Every call edge is stamped with how it was resolved and how much to trust it, from
same_file at 0.95 down to a repo-wide name match at 0.50, labelled as the guess it is
(how that works).
Adding a language takes five small steps and no changes to the parser core.
Full matrix: docs/layers/LANGUAGE_SUPPORT.md → · The graph itself: docs/layers/GRAPH.md → · Contributor recipe and internals: docs/architecture/language-support.md →
1. Install
pip install repowise # Windows: python -m pip install repowise
repowise --version2. Index your repo
cd /path/to/your/repo
repowise initBare init asks. It scans the repo first, then offers three ways to index it:
everything (the wiki written by a model), no prose (the same wiki rendered from
your code's structure, no key and no spend), or advanced, which walks through the
indexing and generation knobs. Nothing is spent before you see an estimate and
confirm it.
If you would rather not answer questions, or you are scripting this, name the
mode and add -y:
repowise init --no-prose -y # free, no key, no questions
repowise init --prose -y # model-written subsystem pages, cost pre-approvedEither way you get the dependency graph, git history, code-health scores and dead-code findings in seconds, plus a complete wiki: file, module, layer and cycle pages, the architecture diagram, the repo overview, API and infra pages, and the onboarding collection. On the keyless path every page carries a footer saying it was derived from structure, and the repo overview describes composition, entry points, clusters and dependencies rather than what the project does end to end, because no template can derive that. Full-text search works on this index; semantic search needs an embedder configured (Ollama is the keyless option).
Went keyless and want the wiki written by a model later? You do not have to decide
now. Upgrade it whenever you like with repowise generate, a page, a directory,
or the whole thing at a time, each behind a cost estimate:
export ANTHROPIC_API_KEY="sk-ant-..." # or OPENAI_API_KEY / GEMINI_API_KEY
repowise generate # write the unwritten subsystem pages, behind one cost estimate
repowise generate --path src/api # or just one area first
repowise generate --all # or rewrite the prose on every subsystem pageBare repowise generate prints the wiki's state and writes the unwritten
subsystem (concept) pages behind a single cost estimate. Every other page was
already rendered from structure at index time.
Or pick the provider for the first index directly with repowise init --provider gemini|anthropic|openai.
Resuming an interrupted index. If init is interrupted (timeout, crash,
Ctrl+C), re-run it with --resume and it continues from where it stopped —
pages already written to the vector store are skipped, and only the missing
ones are generated:
repowise init . --resume--resume is a safe no-op on a fully indexed repo, so it is the right thing to
reach for whenever a long run is cut short. It works because pages are written
to LanceDB incrementally, while the SQL generation_jobs row only finalizes at
the end — a hard interrupt can leave LanceDB ahead of SQL, and --resume is
the supported recovery path (repowise doctor flags the drift).
3. Connect your agent. Step 2 already did this for Claude Code: init
writes a repo-root .mcp.json unconditionally and, unless you passed
--no-editor-setup, also registers repowise with ~/.claude/settings.json.
Open a session in this repo and it is already wired; check with repowise agents.
Skipped editor setup, or setting up another machine?
repowise agents add --target=claude-codeThe plugin additionally adds slash commands and skills, which init does not
install:
/plugin marketplace add repowise-dev/repowise
/plugin install repowise@repowiseOr wire the MCP server by hand:
claude mcp add repowise -- repowise mcpOr edit the project .mcp.json init already wrote:
{ "mcpServers": { "repowise": { "command": "repowise", "args": ["mcp"] } } }Add to ~/.codex/config.toml:
[mcp_servers.repowise]
command = "repowise"
args = ["mcp"]Or: codex mcp add repowise -- repowise mcp
4. First real call. Ask your agent: "Use repowise get_overview to summarize this
repo", or "get_context for src/auth.py". You get graph-grounded architecture and
per-file triage instead of a flurry of greps.
get_overviewandget_contextwork in index-only mode with no key, synthesized from the graph, git and health layers.search_codebaseandget_answerread the wiki, which index-only mode does build, but they answer from pages rendered from structure rather than model-written prose, andsearch_codebaseis full-text only until you configure an embedder.
Full walkthrough: docs/start/QUICKSTART.md →
Every response carries an _meta envelope with index_age_days, indexed_commit, and
a stale_warning that fires only when the indexed HEAD diverges from live .git/HEAD,
so your agent always knows how much to trust what it just read.
Tool | What only this tool answers |
| Architecture summary, module map, entry points, git health. The first call on any unfamiliar codebase. |
| Hybrid retrieval (full-text plus vector via RRF), PageRank bias and 1-hop graph expansion into one cited answer with a calibrated |
| Triage card for files, modules or symbols: summary, signatures, |
| Source for one indexed symbol with exact line bounds. Cheaper and safer than |
| Semantic search over the wiki, filterable by kind (implementation / test / config / doc), tagging each result's |
| Hotspots, dependents, co-change partners, ownership, test gaps, bug history. Pass |
| What a commit, range or uncommitted change newly made worse across defect, maintainability and performance, why each finding is attributable to it, the tests coverage proves it touches, and how the diff's shape ranks against recent commits. |
| Architectural decisions and their verbatim evidence spans, stamped exact / fuzzy / unverified. Falls back to git archaeology when no decisions exist. |
| Unreachable code by confidence tier with cleanup-impact estimates, and cross-repo consumer detection in workspace mode. |
| Per-file marker scores across all three signals. |
Ten is a deliberate ceiling rather than a limit we ran into: a small, task-shaped surface is easier for an agent to choose from than a large one. Worked example ("add rate limiting to all API endpoints" in 5 calls instead of ~30 greps and reads), the opt-in tools, and the full reference: docs/agent/MCP_TOOLS.md →
Six open-source agent-context tools, the same repositories, the same pinned commits, the same questions, each one given its own full advertised tool surface. The full page carries the rows we lose beside the rows we win.
Token reduction needs a denominator. If the comparison is one context payload, Repowise reduces 13,984 naive-read tokens to 393, a 97.2% reduction. If the comparison is the agent's complete output across a real task loop, the reduction is 31.6%. Competitor pages often publish the first kind as "token savings"; we publish both and call only the second one agent savings.
The same rule applies to graphs: coverage without correctness rewards fake edges, while precision without recall rewards drawing almost nothing. Our compiler-graded claim is therefore the pair: in all seven comparisons, no tool that recovers as much of the call graph gets more of it right.
Finds the right files. 0.876 file coverage against CodeGraph's 0.610 on a sealed 42-instance split, held out from every improvement round. 19 wins, 1 loss per instance. Deterministic grading, no LLM judge. n=42, sign test p=0.00004. CodeGraph scores the same on both halves to three decimals, so neither half is the easy one.
Less work in a real agent loop. -31.6% output tokens against a bare agent, leaner on 37 of 44 questions. n=43, p<0.0001. CodeGraph is a genuine second at -24.4%: more than one tool here works, and we lead the field rather than being alone in it.
Fewer steps to get there. 3.8 tool calls where the bare agent needed 7.2, and 3.0 files opened instead of 7.2, the mechanism behind the token saving, visible directly rather than inferred.
The full results, the methodology, and the rows we lose →
No single product competes with all of this, so there is no single table. Three axes, three sets of real peers. Rows marked measured are head-to-head numbers, and they link to docs/BENCHMARKS.md where the sample sizes, the tests and the rows we lose all live.
Against the tools doing the same job: index a repository, serve it to a coding agent over MCP.
repowise | CodeGraph | Serena | DeepWiki | |
Self-hostable, open source | ✅ AGPL-3.0 | ✅ | ✅ | ❌ cloud only |
Private repo, no cloud | ✅ | ✅ | ✅ | ❌ OSS forks only |
MCP tools served | 10 core + workspace tools | 1 | 29 | 3 |
Finds the gold files (measured, n=42 sealed) | ✅ 0.876 | 0.610 | not in this run | not measured |
Output tokens vs a bare agent (measured, n=43) | ✅ -31.6% | -24.4% | -14.8% | not measured |
Memory to build the graph (measured, 5 tools, 35 repos) | ✅ 75 MB, lowest on 35 of 35 | 757 MB | not measured | n/a, cloud |
Time to build the graph (measured, same run) | 2.77s, fastest on 14 of 35 | 3.65s, fastest on 16 | not measured | n/a, cloud |
Time to build the full index, django (measured) | ⚠️ 366.8s, slowest here | ✅ 16.4s | not measured | n/a, cloud |
five layers against their one; one-time, updates after it are incremental | ||||
Call-edge precision (measured, 540 rows hand-graded from source) | ✅ 84.8% | 57.0% | not measured | not measured |
Call-edge precision, judged by a compiler (measured, 5 tools, 7 cells, 37,853 edges) | ✅ nothing that finds as much gets more of it right, 7 of 7 | lower precision in 7, and lower recall in 5 | not measured | not measured |
Generated documentation | ✅ | ❌ | ❌ | ✅ |
Proactive agent hooks | ✅ Claude + Codex | ❌ | ❌ | ❌ |
Auto-generated AI instructions ( | ✅ | ❌ | ❌ | ❌ |
Command-output distillation | ✅ reversible | ❌ | ❌ | ❌ |
Learns from your usage (session-mined decisions, demand-weighted docs) | ✅ | ❌ | ❌ | ❌ |
Architectural decision records | ✅ | ❌ | ❌ | ❌ |
Multi-repo workspace intelligence | ✅ contracts, co-change, federated MCP | ❌ | ❌ | ❌ |
The two cost rows answer different questions. Building the call graph, we are
the lightest tool measured, about ten times lighter than the next, and roughly as
fast as the fastest. Building the whole index, CodeGraph is 22x faster than we
are, because by then we have also built the git-history layer, the wiki, the
decisions and the health pass. If a call graph is all you need, that is the right
trade and you should take it. With prose generation on, which is what a default
repowise init costs, it is 135x. Graphify and
code-review-graph were in the same measured field and are on the benchmarks page.
The precision row cuts the other way and is worth stating as plainly: of the call
edges we draw, about fifteen percent are wrong, and on seastar CodeGraph
grades better than we do. Nine languages were read on both sides, four separate,
five are statistical ties.
The compiler row exists because we graded the hand-read one ourselves. On Go and
TypeScript the answer key is the Go team's own RTA call graph and the tsc
checker's own resolution, which we neither wrote nor can tune.
Read that row carefully, because it is a claim about two numbers. Precision alone is easy to win by drawing almost nothing, and two of the five tools score above us that way, one of them at 0.997 from a graph holding 17% of the calls in the repository. Recall alone is easy to win by drawing everything, and the tool that leads it emits, on the largest repository measured, more than a third of its edges as calls that do not exist. What we claim is the pair: in all seven cells, no tool that recovers as much of the call graph as we do gets more of it right. The column we lose is still there and is still ours to lose: the tool with the highest recall in every Go cell is not us.
Measured against CodeGraph 1.5.0, Graphify 0.9.31, Serena 1.6.2.dev0,
code-review-graph 2.3.7, on repowise 081a59fa (between v0.37.0 and v0.38.0),
August 2026. Unmarked rows are capability presence, not measurements.
repowise | CodeScene | |
Self-hostable, open source | ✅ AGPL-3.0 | ⚠️ on-prem Docker, proprietary |
Code health score (1-10) | ✅ 51 detectors, 26 scoring | ✅ 25-30 |
Brain Method / LCOM4 / god class | ✅ | ✅ |
Defects found at a 20% review budget (measured, 2,770 files) | ✅ 0.173 | 0.074 |
Effort-aware ranking, Popt (measured, p=0.003) | ✅ 0.607 | 0.462 |
Precision at that budget (measured) | 0.580 | ✅ 0.636, a shorter list |
Discrimination, ROC AUC (measured, paired) | 0.731 | 0.705, p=0.054, not significant |
Defect-prediction AUC, published and reproducible | ✅ 0.737 over 21 repos, held-out 0.76-0.78 | ✅ Code Red study |
Business impact (resolution time) | ❌ we could not replicate this on open data | ✅ Code Red study |
Git intelligence (hotspots, ownership, co-change) | ✅ | ✅ |
Pre-merge change-risk scoring | ✅ 0-10 + directives | ✅ |
Health trend + declining alerts | ✅ rolling snapshots | ✅ |
Bus factor analysis | ✅ | ✅ |
Concrete cross-file refactoring plans | ✅ graph-aware + blast radius | ⚠️ within-function only |
Dataflow-verified within-function plans | ✅ CFG + reaching definitions | ⚠️ LLM-generated, unverified |
Test-coverage intelligence | ✅ LCOV/Cobertura/Clover | ❌ |
Untested-hotspot detection | ✅ coverage × hotspot | ❌ |
Dead code detection | ✅ | ❌ |
Serves it to an AI agent over MCP | ✅ | ✅ |
Local dashboard | ✅ | ✅ |
CodeScene is the only other vendor in this category with a published empirical defect study, which is why it is the one we ran head to head against. It flags about 27 files where we flag 132, so if you want a short list to action rather than the ranking that catches the most defects, its threshold is the better fit.
DeepWiki, Google Code Wiki and Swimm generate documentation from a repository, which overlaps one of our five layers. We have not measured against them, so there is no table here rather than a table of checkmarks. DeepWiki appears above because it also serves an agent over MCP, which is a job we can be measured on.
Repowise PR Bot | CodeRabbit | Greptile | |
LLM calls per PR | ✅ zero | ❌ every review | ❌ every review |
Same diff, same review | ✅ deterministic | ❌ sampled output | ❌ sampled output |
Your code sent to a model provider | ✅ never | ❌ yes | ❌ yes |
Symbol-level blast radius (changed contracts → their callers) | ✅ call graph | ❌ | ⚠️ prose, from context |
Co-change partners missing from the PR | ✅ git history | ❌ | ❌ |
Change risk vs the repo's own distribution | ✅ 0-10 + percentile | ❌ | ❌ |
Public analysis page per PR, no sign-in | ✅ | ❌ | ❌ |
Silent on a clean PR | ✅ by default | ⚠️ configurable | ⚠️ configurable |
Cost on public repos | ✅ free, uncapped | ⚠️ free tier | ⚠️ free tier |
Self-hostable | ✅ AGPL-3.0 | ❌ | ❌ |
The axis where this is not close is the first two rows. An LLM reviewer is a different product with a different failure mode: it can read intent, and it can also be wrong in a new way on every run. This one does set arithmetic over a call graph and a git history, so there is nothing to hallucinate and nothing to prompt-inject, and pushing the same diff twice produces the same review twice.
Repowise is the intersection: an agent-native context layer and behavioral git intelligence and a defect-validated health score with the fix attached, all out of one index, self-hostable and open source. Full side-by-side comparisons: repowise.dev/compare →
AI makes producing a change cheaper; it does not make understanding its consequences cheaper. In a large estate, the answer crosses repositories, ownership boundaries, service contracts, test suites, and years of architectural history. Repowise gives developers, agents, reviewers, and platform teams the same evidence about what exists, what depends on it, what is risky, and what will break.
That is the engineering reason to deploy it. The security reason is structural: graph, git, health, change risk, tests, dead code, and PR review make zero LLM calls. Documentation prose is optional and can use your provider contract or run fully offline through Ollama.
Status | Enterprise capability |
Shipping now | Five deterministic intelligence layers, ten MCP tools, multi-repo workspaces, contract extraction and blast radius, test intelligence, architecture conformance, local dashboard, auto-sync, and full-history secret scanning. |
GA commercially | Hosted graph-aware security, CVE prioritization, CycloneDX SBOM and VEX, PCI-DSS and SOC 2 evidence reports, audit exports and webhook stream, Jira and Confluence, customer-infrastructure HA topology, custom extensions, SLA support, and IP indemnification. |
Rolling out | GitHub Enterprise, Azure DevOps, GitLab and Bitbucket integrations; SAML/OIDC SSO and SCIM; engineering-leader dashboards. |
Planned | RBAC and multi-tenancy, packaged air-gap install bundle, and the Helm chart. |
Self-host with pip install or run the API, workers, dashboard, Postgres, and
LanceDB/pgvector containers on your infrastructure. Deterministic analysis needs no
provider. When optional prose is enabled, provider choice is per repository. Stored
data includes the graph, embeddings, wiki pages, and git metadata; raw source is
processed transiently and is not persisted.
Past one repository. Workspaces index an estate as one unit: API contracts matched producer to consumer so a breaking change is caught before it ships, cross-repo co-change, and one federated MCP endpoint that answers across all of it. (Estate-scale dashboards: in development.)
Not on git? Only the history layer needs a commit log. Point repowise init
at a plain directory, an export, or a Perforce or SVN workspace and the graph,
documentation, decisions and code-health layers all build normally; what is
missing is hotspots, ownership, co-change and bug history until the history layer
learns to read your system.
(Perforce, SVN, Endevor and ChangeMan on the roadmap →)
The complete capability matrix is maintained in COMMERCIAL.md, with every item labelled GA, rolling out, in development, or planned.
repowise.dev runs the same engine fully managed, at feature parity with self-hosted. We run it on our own codebase in the open: live snapshot → · explore public repos →.
Commercial detail and pricing models → · Security review pack → · Roadmap → · hello@repowise.dev · security@repowise.dev
Deterministic or offline mode: with --no-prose, code-derived content stays on
your infrastructure. The CLI reports anonymous, opt-out usage telemetry
(command names and coarse environment only); disable it with repowise telemetry disable, DO_NOT_TRACK=1, or by running fully offline.
What's collected →
Optional LLM features: generated prose, decision extraction and code-generating refactoring can send code-derived prompts directly to the provider configured with your own key. Repowise does not proxy those calls; provider handling and retention follow your account and provider terms.
What's stored: the graph, embeddings, generated wiki pages, and git metadata. Raw source is processed transiently and never persisted. See the security review pack for the threat model and data-flow boundaries.
Fully offline: Ollama plus a local embedding model means zero external calls.
Doing a security review? docs/business/SECURITY_COMPLIANCE.md →
repowise init [PATH] # index a codebase (one-time; asks, or --no-prose -y needs no LLM)
repowise generate [PATH] # write wiki pages with a model, on demand (upgrade a keyless wiki)
repowise serve [PATH] # MCP server + local dashboard
repowise update [PATH] # incremental update (seconds; --workspace for every repo)
repowise watch # auto-sync daemon, re-index on file change
repowise search "<q>" # hybrid search (fulltext / semantic / symbol / path)
repowise ask "<q>" # a synthesized answer with citations
repowise context <files> # triage card: layer, hotspot, fix history, freshness
repowise symbol <id> # one symbol's body, with verified line bounds
repowise why <q|path> # decisions, rationale, git archaeology
repowise health # code-health KPIs and lowest-scoring files
repowise risk main..HEAD # score a branch or PR range for defect risk
repowise risk -t <file> # what history says about touching a file
repowise impacted-tests # only the tests a diff actually exercises
repowise dead-code # unreachable-code report
repowise doc-drift # documentation the code no longer supports
repowise decision list # architectural decisions
repowise export --format structurizr # the architecture as Structurizr DSL, no LLM
repowise distill pytest # compact, errors-first, reversible command output
repowise saved # tokens and dollars saved by distillation
repowise savings # the full agent savings ledger, priced per event
repowise workspace add # multi-repo workspace management
repowise doctor # check setup, API keys, index drift
repowise uninstall # remove what repowise wrote, and say what it leftEvery command and flag: docs/reference/CLI_REFERENCE.md · config: docs/reference/CONFIG.md · examples: examples/
git clone https://github.com/repowise-dev/repowise
cd repowise
uv sync --all-packages
uv run repowise --version
uv run pytest tests/unit/New here? You do not have to read 3,000 files to start. We keep a public index of this repo built by repowise itself, re-indexed on every push: explore repowise with repowise → (architecture, hotspots, ownership, decisions, and a ranked refactoring backlog you are welcome to pick from).
Full guide, including how to add languages and LLM providers: CONTRIBUTING.md · architecture: docs/architecture/
AGPL-3.0. Free for individuals, teams and companies using repowise internally.
For commercial licensing (the enterprise security and compliance layer, SSO/SCIM, RBAC, workflow integrations, priority support and SLA, or embedding repowise in a product without AGPL obligations), see docs/business/COMMERCIAL.md or contact hello@repowise.dev.
Built for engineers who got tired of watching their AI agent cat the same file for the fourth time.
Answer a how, where, or why question in one evidence-grounded call.
High confidence is content-grounded and may be used directly. Medium
confidence keeps the smallest verification evidence; low confidence leads
with an actionable local conclusion and ranked evidence. Provider keys and
network access are optional: local source, symbols, FTS, rationale, and
data-shape evidence remain usable when embeddings or synthesis fail.
Responses fit 24,000 serialized characters. Pass ``include=["evidence"]``
for the deduplicated expanded projection, capped at 32,000. Reductions carry
totals, emitted counts, reasons, and an exact one-call recovery.
Args:
question: Developer question.
scope: Optional repository-relative path prefix.
repo: Usually omitted; a workspace alias when needed.
include: Optional ``["evidence"]`` expanded projection.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | ||
| scope | No | ||
| include | No | ||
| question | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses confidence tiers, evidence grounding, optional provider keys/network, fallback behavior, response size caps, reduction details, and recovery semantics. This is far beyond a basic 'answers questions' statement.
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?
Although long, every sentence earns its place: purpose, confidence behavior, offline fallbacks, size limits, reduction recovery, and parameter semantics. The description is front-loaded with the core purpose and organized with clear sections; nothing is wasted.
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 4 parameters, no annotations, and an output schema. The description covers purpose, usage scope, param meaning, behavioral guarantees, failure/recovery paths, and output constraints. There is no obvious missing information an agent needs to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description's Args section adds meaningful semantics for every parameter: 'question: Developer question', 'scope: Optional repository-relative path prefix', 'repo: Usually omitted; a workspace alias when needed', and 'include: Optional ["evidence"] expanded projection'. This compensates fully for the absent schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Answer a how, where, or why question in one evidence-grounded call.' This clearly distinguishes the tool from siblings like get_health or get_risk, which target different query types. The phrase 'how, where, or why' anchors exactly when this 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 gives clear context on when to use the tool for how/where/why questions, and it excludes general change-risk/health/overview concerns implicitly. It does not explicitly name sibling alternatives or state 'when not to use this vs. X', but the question-type framing is strong enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Review a commit, base..head range, or uncommitted work.
Leads with ``directive`` (what to do) and ``health_delta`` (what this
change newly made worse). A finding is reported only when the diff explains
it, and each names its ``attribution`` basis; findings the change wrote
sort above pre-existing ones it only touched.
Trust ``health_delta.status``: ``partial`` means files were skipped and the
change is not cleared.
``impacted_tests`` keeps measured coverage and inferred candidates distinct.
``fix_history`` is the changed files' bug-fix record, ``overlap`` the past
fixes on these exact lines. ``branch_overlap`` names other branches editing
them. ``diff_shape`` is one line on size, not a danger verdict. An empty
diff returns ``status: "nothing_to_score"`` and names the tree it read.
Args:
revspec: Commit or ``base..head`` range. Omit to review uncommitted
work, or ``HEAD`` when the tree is clean.
repo: Repository alias in workspace mode; omit for the default.
extensions: File suffixes to count, e.g. ``[".py", ".ts"]``.
exclude_patterns: Gitignore-style paths to omit, e.g. ``["tests/"]``.
baseline: Recent commits sampled for percentile ranking; 0 disables it.
include: ``"findings"`` for every change finding, ``"diagnostics"`` for
raw score mechanics, ``"scales"`` for units. All identical on
repeat, so ask once.
finding_id: Expand one ``health_delta`` finding by its id.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | ||
| include | No | ||
| revspec | No | ||
| baseline | No | ||
| extensions | No | ||
| finding_id | No | ||
| exclude_patterns | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so exceptionally. It exposes important behavioral nuances: 'partial means files were skipped and the change is not cleared,' findings are 'reported only when the diff explains it,' and 'diff_shape is one line on size, not a danger verdict.' This prevents misinterpretation and gives the agent actionable caution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well organized: a one-line scope summary, a short output-semantics section, and a clear Args list. Every sentence adds operational value, and the most important behavioral warnings are 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?
Given seven parameters, zero schema descriptions, and no annotations, this description is remarkably complete. It explains output fields, edge cases like empty diffs, and parameter interactions. The output schema fills in formal return types, so no critical invocation information 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 0%, but the description fully compensates by explaining every parameter in meaningful terms. It gives concrete examples for extensions and exclude_patterns, clarifies revspec modes, defines baseline behavior, and explains include values and repeat-call stability.
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: 'Review a commit, base..head range, or uncommitted work.' It clearly distinguishes this tool's scope from generic health/overview tools. However, it does not explicitly differentiate from the sibling 'get_risk', despite the similar names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context for the main modes: 'Omit to review uncommitted work, or HEAD when the tree is clean.' It also gives parameter-level guidance such as '0 disables' baseline and explains include modes. It does not name alternatives or state when not to use this tool in favor of a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Triage card for files / modules / symbols — relationships, not source bytes.
Returns title, summary, signatures with line numbers, hotspot bit, and
decision_record titles. fix_history appears only on files with counted bug
fixes (count, age, bug_magnet); hotspot is churn. Either one is a cue to
call get_risk. episodes counts the dated records bound to a target — what
happened here and why — and appears only when there is at least one;
get_why serves the bodies. A symbol target is counted as its file, and a
module aggregates everything beneath it.
Batch targets in one call. No source bytes by default: pass
include=["skeleton"] for the whole file body-elided and line-verified in
ONE call, or Read it. Do not call get_symbol per signature.
Default responses fit 24,000 serialized chars; nonempty ``include`` uses
32,000. Reductions carry counts and ``_meta.omitted`` recovery refs;
``_meta.recovery_unavailable`` names a storage failure.
Include-gated blocks are projections, not omissions.
Args:
targets: file paths, module paths, or "path::Symbol" ids.
include: opt-in blocks: full_doc | ownership | last_change | callers
| callees | metrics | community | decisions | skeleton | health
| doc_drift (documents naming this file).
An unrecognised key is named in ignored_arguments.
compact: default True; False adds structure+imports+docstrings.
repo: usually omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | ||
| compact | No | ||
| include | No | ||
| targets | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses 'No source bytes by default', response size limits ('Default responses fit 24,000 serialized chars; nonempty include uses 32,000'), conditional fields ('fix_history appears only...', 'episodes... appears only when there is at least one'), and error recovery ('_meta.omitted recovery refs', '_meta.recovery_unavailable names a storage failure').
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 a clear purpose, then structured into return-field semantics, usage guidance, size constraints, and an Args section. Each sentence adds a distinct operational fact; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, many include options) and that an output schema is present, the description covers input semantics, conditional outputs, size limits, and guidance to alternatives. An agent can invoke it correctly without further documentation.
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 add meaning. It explains each arg: targets are 'file paths, module paths, or path::Symbol ids', include lists allowed blocks, compact toggles extra structure, and repo is 'usually omitted'. It also notes unknown include keys are named in ignored_arguments.
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 'Triage card for files / modules / symbols — relationships, not source bytes' and then enumerates returned fields. It explicitly names sibling tools: 'call get_risk', 'get_why serves the bodies', and warns 'Do not call get_symbol per signature', distinguishing it from related 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?
It states 'Either one is a cue to call get_risk' and 'get_why serves the bodies' to route to alternatives. It tells the agent to 'Batch targets in one call' and not to call get_symbol per signature. It also advises passing include=['skeleton'] for body instead of separate read.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unused exports, unreachable files, zombie packages — tiered by confidence.
Run before a cleanup sprint, not a targeted fix. Findings tier
high/medium/low with per-directory and per-owner rollups; workspace
mode lowers confidence on findings other repos import.
Args:
repo: usually omitted.
kind: unreachable_file | unused_export | unused_internal | zombie_package.
An unrecognised value is dropped and named in ignored_arguments,
never applied as a filter that matches nothing.
min_confidence: floor, default 0.4 (0.7 = cleanup-ready only). Also
accepts a tier name: "high" (0.8) | "medium" (0.5) | "low" (0.0).
safe_only: deletion-ready findings only (no runtime-load risk).
limit: max findings per tier (clamped to 25).
tier: "high" (>=0.8) | "medium" | "low".
directory: path-prefix filter.
owner: primary-owner filter.
group_by: "directory" | "owner" rollup.
include_internals: also scan private symbols (more false positives).
include_zombie_packages: monorepo package findings (default true).
no_unreachable: skip file-level reachability findings.
no_unused_exports: skip public-export findings.
finding_id: stable ``id`` emitted by a dead-code finding.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| repo | No | ||
| tier | No | ||
| limit | No | ||
| owner | No | ||
| group_by | No | ||
| directory | No | ||
| safe_only | No | ||
| finding_id | No | ||
| min_confidence | No | ||
| no_unreachable | No | ||
| include_internals | No | ||
| no_unused_exports | No | ||
| include_zombie_packages | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does an excellent job: it discloses how invalid 'kind' values are handled, that 'limit' is clamped, that min_confidence accepts numeric values or tier names, that safe_only means deletion-ready findings, and that workspace mode lowers confidence. These are meaningful behavioral traits that an agent would not otherwise know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but appropriately so for 14 undocumented parameters, and it front-loads the core use case before the parameter list. Each argument line is terse and informative; there is minor redundancy in repeating tier thresholds across min_confidence and tier, but it's justified because both parameters accept tier concepts.
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 14 parameters, no annotations, and no schema-level descriptions, the definition is strikingly complete: it covers every parameter, explains non-obvious behaviors, provides usage context, and mentions rollups and confidence-lowering behavior in workspace mode. Since an output schema exists, the lack of detailed return-value documentation is not a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate, and it does: every one of the 14 parameters gets its own explanation with defaults, allowed values, and edge-case behavior. For example, min_confidence is documented with both numeric thresholds and tier-name equivalents, and kind documents what happens with unrecognized input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource: dead code (unused exports, unreachable files, zombie packages) and communicates the core capability of tiering findings by confidence. It does not use a single explicit verb like 'return' or 'list', and it doesn't explicitly distinguish itself from sibling tools, but the dead-code focus makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The line 'Run before a cleanup sprint, not a targeted fix' explicitly states when to use and when not to use the tool, which is strong usage guidance. However, it doesn't name alternative sibling tools for targeted fixes, so the guidance is clear on timing/context but lacks explicit alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code-health scores and findings from stored analysis.
No ``targets`` returns a dashboard; targets rank files and findings.
Never recomputes health: commit, then run ``repowise update``.
Every block and accepted value: docs/agent/MCP_TOOLS.md.
Args:
targets: file paths or ``module:<name>``; unmatched ones land in
``unresolved``.
include: ``biomarkers``|``refactoring``|``trend``|``coverage``|
``accuracy``|``signals``|``churn_complexity``|``doc_drift``,
or a dimension incl. ``advisory``; ``performance`` and
``refactoring`` add queues.
only: keys to keep; identity, totals, recovery survive.
``biomarkers``/``accuracy``/``refactoring`` alias their block key;
``performance``/``defect``/``maintainability``/``advisory``
do not: they filter rows into ``unknown_only_keys``.
repo: usually omitted.
limit: max rows per ranked list, ``0`` for none.
cursor: zero-based offset into a ranked list.
finding_id/plan_id: stable ``id`` from a finding or plan.
opportunity_id: ``perf...``/``refop...``: the unit, its steps or
plan, evidence paged by ``only=["*_evidence"]``.
refactoring_view: ``diversified`` (default)|``canonical``|
``file_spread``; _type/_confidence/_effort filter.
performance_view/_context/_boundary/_confidence/_sort: queue
projection and filters; the facets list them.
scope / counts: default ``all``/``everything``. ``production`` drops
test files; ``code_shape`` drops the git-derived half of the
score and its findings.| Name | Required | Description | Default |
|---|---|---|---|
| only | No | ||
| repo | No | ||
| limit | No | ||
| scope | No | all | |
| counts | No | everything | |
| cursor | No | ||
| include | No | ||
| plan_id | No | ||
| targets | No | ||
| finding_id | No | ||
| opportunity_id | No | ||
| performance_sort | No | ||
| performance_view | No | ||
| refactoring_type | No | ||
| refactoring_view | No | diversified | |
| refactoring_effort | No | ||
| performance_context | No | ||
| performance_boundary | No | ||
| performance_confidence | No | ||
| refactoring_confidence | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it invests that space in real behavior: stored analysis only, never recomputes, unmatched targets landing in `unresolved`, `only` aliasing/filtering into `unknown_only_keys`, and scope effects like `production` dropping test files or `code_shape` dropping the git-derived half. No contradiction with annotations exists, and the read-only nature is clearly implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but proportionately so for a 20-parameter tool. It front-loads the core behavior before the argument list, uses compact grouped notation for related parameters, and points to docs for exhaustive accepted values. Some phrases like 'identity, totals, recovery survive' are dense enough to require unpacking, but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 20 parameters, no annotations, and no enums in the schema, the description documents every parameter group, special defaults, pagination semantics, and the no-recompute read pattern. The output schema covers return-value shape, so not describing it here is appropriate; the docs pointer covers exhaustive enum-style values without bloating the definition.
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 Args block is the only meaning-bearing documentation for all 20 parameters. It explains target matching, include values, the tricky `only` alias/filter behavior, pagination via limit/cursor, stable IDs, and groups the performance/refactoring filters compactly. This is far more useful than the raw 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 lead sentence names a precise resource ('code-health scores and findings') and its source ('stored analysis'), and the very next sentence clarifies the two invocation modes: no targets gives a dashboard, targets rank files and findings. The code-health focus is distinct enough from siblings like get_risk and get_overview, and the 'stored analysis' framing separates it from computation/recompute flows.
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 this tool applies: no targets means dashboard, targets means ranked files/findings, and 'Never recomputes health' explicitly tells the agent when not to expect recomputation and directs it to `repowise update`. It does not explicitly compare against sibling MCP tools such as get_overview or get_risk, so it misses the full 'alternatives' criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Architecture map for an unfamiliar repo — first call when you don't know your way around.
Returns the synthesised overview summary, key modules, entry points,
architecture layers, code health, and repo-wide git health (hotspot count,
churn trend, bus-factor distribution).
Skip this on subsequent calls — once you have the map, jump straight to
``get_context`` / ``get_answer``.
Compact by default: ``content_md`` carries only the overview essay's summary
section, and the outline, onboarding, ownership and graph blocks ship only
on request. The response's ``more`` field names them.
Defaults fit 24,000 chars; nonempty ``include`` uses 32,000. Reductions
carry counts and recovery status in ``_meta``.
Include-gated blocks are projections, not omissions.
In workspace mode:
- Omit ``repo`` for the default repo's overview plus a workspace footer.
- ``repo="all"`` returns the cross-repo topology (co-changes, package deps,
API contracts) — no single-repo detail.
- ``repo="<alias>"`` targets one specific repo.
Args:
repo: Repository alias, path, or ID. Use ``"all"`` for workspace overview.
include: Opt-in extras, any combination of:
``"content"`` — the full overview essay instead of its summary.
``"outline"`` — the stored wiki page tree, two rungs deep.
``"tour"`` — ``guided_tour`` + ``reading_order`` onboarding walks.
``"decisions"`` — ``key_decisions``; ``get_why`` is richer.
``"graph"`` — ``community_summary``, code-community clusters.
``"ownership"`` — ``knowledge_map``: top owners, knowledge silos.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | ||
| include | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full disclosure burden and does so thoroughly. It reveals compact-by-default output, the `more` field, char-limit behavior, `_meta` reduction reporting, and the "projections, not omissions" semantics for gated blocks. This gives an agent an accurate mental model of side effects, output shape, and cost implications beyond the raw 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 its core value proposition and then organized into clear sections: returns, when-to-skip, default behavior, workspace modes, and args. It is long, but nearly every detail earns its place; minor redundancy exists between workspace mode bullets and the repo arg line, though this does not meaningfully hurt clarity.
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 an output schema exists and both parameters are thoroughly documented in prose, the description supplies all essentials: what the tool returns, how to request extras, how workspace scoping changes results, and how large payloads are managed. No critical operational information required to invoke or interpret the tool appears to be 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 coverage is 0%, but the description fully compensates with an Args section explaining repo as alias/path/ID and "all", and enumerating every include value with the exact block each one activates. The semantic meaning is far richer than the bare schema, which only says two nullable fields with defaults.
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 crisp job statement — "Architecture map for an unfamiliar repo" — and enumerates the concrete contents: overview summary, key modules, entry points, architecture layers, code health, and git health. It also distances itself from later-stage siblings by naming get_context / get_answer as follow-ups, so the tool's place in a workflow is unmistakable.
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 explicit: this is the "first call when you don't know your way around," and it should be skipped once the map exists in favor of get_context / get_answer. Workspace-mode behavior is fully specified for omitted repo, repo="all", and repo="<alias>", leaving no ambiguity about when each call shape is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What history says about touching these files — bug fixes, churn, owners.
Fuses git temporal signals (``hotspot_score``/``owner_pct`` are 0-1; trend;
bus factor) with graph topology. ``dependents`` are directed structural
reach (source depends on target), ``consumers`` require typed contract links,
and ``co_change_partners`` are historical correlation only. Those counts
are a floor over the indexed graph. Structural reach is not proof of
runtime breakage. The response also includes security
findings. Pass changed_files for PR mode: the response leads with a
directive block (may_break, missing_cochanges, missing_tests,
tests_to_run) — read it first. Each test_recommendations row carries a
measured or inferred basis, and coverage availability is explicit. To
score a commit or ``base..head`` range instead, use ``get_change_risk``.
In PR mode ``structural_impact_score`` is an uncalibrated 0-10 structural
heuristic, never a runtime-breakage probability; ``overall_risk_score`` is
its deprecated exact alias.
Default responses fit 24,000 serialized chars; nonempty ``include`` uses
32,000. Reductions carry counts and ``_meta.omitted`` recovery refs;
``_meta.recovery_unavailable`` names a storage failure.
Include-gated blocks are projections, not omissions.
Args:
targets: file paths to assess.
repo: usually omitted.
changed_files: PR-changed files for blast-radius mode.
include: opt-in blocks - "graph", "churn", "scales" (units and
calibration for every scalar; identical per call, so ask once).
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | ||
| include | No | ||
| targets | Yes | ||
| changed_files | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so extensively: it discloses response size limits (24,000 default, 32,000 with include), truncation semantics ('Reductions carry counts and _meta.omitted recovery refs; _meta.recovery_unavailable names a storage failure'), that include-gated blocks are projections rather than omissions, and the epistemic caveats ('Structural reach is not proof of runtime breakage'; 'structural_impact_score is an uncalibrated 0-10 structural heuristic, never a runtime-breakage probability'; 'overall_risk_score is its deprecated exact alias'). This is unusually rich behavioral context for a large-payload read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded well, but the body is dense and repetitive: PR mode is introduced twice, structural_impact_score is discussed in two separate places, and the exact character-budget figures plus recovery-ref mechanics occupy substantial space. Much of it earns its place, but the redundancy and length keep it below the top scores.
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 four-parameter, output-schema-backed tool with zero annotation coverage, the description covers inputs, output shape, metadata/recovery semantics, and the meaning of the headline scores. An output schema exists, so it needn't restate return fields, and it appropriately focuses on the epistemic and truncation caveats an agent needs to interpret results 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% (the schema only supplies titles and types), so the description must compensate and does: it explains targets, why repo is 'usually omitted', the role of changed_files in PR mode, and enumerates include values ('graph', 'churn', 'scales' with units/calibration). It stops short of format-level detail (e.g., path conventions for targets), so a 4 rather than a 5.
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 opening sentence states the resource and the evidence it fuses ('What history says about touching these files — bug fixes, churn, owners'), which is a concrete, non-tautological purpose. It explicitly distinguishes itself from the sibling get_change_risk ('To score a commit or base..head range instead, use get_change_risk'), so an agent can route between them. The only mild weakness is that the 'verb' is diffuse — the description reads more like a data-fusion contract than a crisp action.
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 names a concrete trigger ('Pass changed_files for PR mode') and points to the divergent sibling for a different scope (commit or base..head → get_change_risk). It also tells the caller to 'read [the directive block] first' and that 'scale' includes are call-invariant ('ask once'). It does not spell out when NOT to call it or prerequisites, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Follow-up read of one symbol whose id another response already gave you.
**Not an entry point.** ``get_answer`` already ships ``symbol_bodies``, and
for a whole file ``get_context(include=["skeleton"])`` or a plain Read is
one call instead of many. Reach here for a body that was elided, or for a
``continuation`` / omission ref. Never walk a file symbol by symbol.
Returns verified, line-numbered source for one indexed symbol, live range,
or omission ref. Ambiguity returns every candidate; an index miss returns
live fallback lines. A truncated result carries the exact continuation to
pass straight back.
Args:
symbol_id: "path/to/file.py::Name", "path/to/file.py:140-180" for a
live range, or an omission ref.
context_lines: extra lines before/after (0-50).
repo: usually omitted.
query: omission refs only, regex/substring filter on lines.
id: accepted alias for ``symbol_id``.
depth: 1 (default) is this symbol alone; 2-3 also returns the bodies
it calls, transitively, in ``callee_bodies``.
reference: structured source reference emitted by this tool. Its id
and repository are accepted together without caller translation.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| repo | No | ||
| depth | No | ||
| query | No | ||
| reference | No | ||
| symbol_id | No | ||
| context_lines | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains return contents, ambiguity resolution, fallback behavior for index misses, truncation/continuation handling, and depth semantics, all beyond what the bare schema shows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but excellently structured: purpose and exclusions first, return behavior second, and a compact argument list. Every sentence adds value, and the not-an-entry-point warning earns its prominent placement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 optional parameters, no annotations, and subtle modes like omission refs and depth expansion, the description covers use cases, routing, input formats, edge cases, and continuation handling. The output schema exists, so return-structure details need no extra explanation, but the description still provides them where relevant.
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 fully compensate, and it does. Every parameter is explained: symbol_id formats, context_lines bounds, repo's usual omission, query's restriction to omission refs, id alias, depth behavior, and reference usage.
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 verb and resource: a follow-up read of one symbol whose id was already provided by another response. It explicitly distinguishes itself from get_answer, get_context, and plain Read, so an agent can select it correctly without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states clearly when to use this tool: for elided bodies, continuations, or omission refs, not as an entry point. It names alternative tools and even warns against walking a file symbol by symbol, giving strong routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Why this code is shaped this way — decision records + evidence commits.
Call before refactors or pattern divergences. Query modes: a question
("why is auth using JWT?"), a file path (governing decisions + origin
story + alignment score), a question anchored to targets, or no query
(decision health dashboard). Falls back to git archaeology when no
decisions exist for a path — never empty. Evidence-bearing rows carry an
explicit ``provenance`` and self-contained ``evidence_refs``; matching ids
mean shared evidence, not independent corroboration. Every decision row
carries ``authority``: ``accepted`` means somebody signed it, ``candidate``
means nobody has yet. ``answer_basis`` names the strongest lane the response
rests on (decision, episode, rationale, archaeology, documentation,
candidate); only ``decision`` is a ruling, and ``candidate`` is the weakest
-- it means nothing cleared that bar.
Args:
query: question, file/module path, or omit for the dashboard.
targets: optional file paths to anchor the search, or to ask about on
their own when there is no query.
repo: usually omitted.
id: decision or ``ev_...`` evidence id emitted by this or another tool.
reference: structured evidence reference. Its id and repository are
accepted together without caller translation.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| repo | No | ||
| query | No | ||
| targets | No | ||
| reference | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly discloses fallback behavior ('Falls back to git archaeology when no decisions exist for a path — never empty'), evidence semantics ('matching ids mean shared evidence, not independent corroboration'), and the meaning of authority and answer_basis fields. This is rich, transparent 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 long but every sentence earns its place. It is front-loaded with purpose and usage, followed by behavioral nuances, then a structured Args section. The information density is high without redundancy, making it well-suited for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 optional parameters, no annotations, 0% schema coverage), the description is remarkably complete. It covers all parameters, explains output semantics (authority, answer_basis, provenance), and describes fallback behavior. The presence of an output schema further relieves the need to detail return values, so nothing critical 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 0%, so the description must compensate entirely. It does so admirably, explaining each parameter in the Args block: query (question, path, or omit), targets (anchor or standalone), repo (usually omitted), id (decision or ev_... format), and reference (id and repository accepted together). This goes far beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it retrieves decision records and evidence commits explaining why code is shaped a certain way. It also gives a specific use case ('Call before refactors or pattern divergences'). However, it does not explicitly differentiate from sibling tools like get_context or get_answer, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context with 'Call before refactors or pattern divergences' and explains the various query modes (question, file path, anchored targets, no query). It does not, however, mention when not to use the tool or explicitly compare to alternatives, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find code by concept, symbol, or path — hybrid codebase search.
For QUESTIONS ("how does X work", "where is Y handled", "why is Z like
this"), call get_answer instead: it runs this same hybrid retrieval
internally and synthesizes a cited answer, so searching first is a wasted
round-trip. Use this tool when you want the raw ranked hits themselves —
enumerating matches, resolving an identifier to a symbol_id, or scoping a
later get_context call.
mode="auto" (default) routes the query: identifier-shaped queries search
the indexed symbols (returns symbol_id/file/line bounds — pipe into
get_symbol), path-shaped queries resolve files (pipe into get_context),
and conceptual queries run wiki-semantic search. Mixed queries run hybrid,
symbol hits first. Decision records rank below file pages unless the query
is why-shaped.
`candidates` lists up to `limit` distinct openable file paths, best first.
Some results are pages, not files; this is what to Read.
Args:
query: identifier, path, or natural-language query.
limit: max results (default 5).
page_type: restrict to one page type. Common: file_page (per-file
docs, always present) or module_page (subsystem/concept pages).
Any stored type filters (repo_overview, layer_page, scc_page,
api_contract, infra_page, symbol_spotlight).
kind: implementation | test | config | doc (concept/symbol modes).
repo: alias, or "all" for workspace-wide.
mode: auto | concept | symbol | path | hybrid.
symbol_kind: filter symbol hits by kind (function|class|method|...).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| mode | No | auto | |
| repo | No | ||
| limit | No | ||
| query | Yes | ||
| page_type | No | ||
| symbol_kind | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so thoroughly. It explains mode routing heuristics, decision-record ranking, candidates semantics (up to limit, best first), and that some results are pages rather than files. It also notes that this result set is what to Read, providing context for downstream actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but highly organized: a one-line summary, a clear usage-orientation paragraph, a mode-behavior paragraph, a candidates paragraph, and a terse bullet-style Arg list. No redundant fluff; every sentence adds value. The structured flow aids scanability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, multiple modes, output schema), the description covers usage boundaries, mode routing, filtering, return semantics, and integration with sibling tools. It is complete enough for an agent to select and invoke the tool correctly without additional 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 coverage is 0%, but the description's Args section explains every parameter with meaningful details—e.g., page_type gives common valid values, mode enumerates auto|concept|symbol|path|hybrid. It compensates fully for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Find code by concept, symbol, or path — hybrid codebase search,' specifying a precise verb and resource. It clearly distinguishes the tool from the sibling get_answer by framing it as the raw-hit retrieval tool rather than a question-answering tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance says to avoid this tool for factual questions ('call get_answer instead... searching first is a wasted round-trip') and directs use when 'you want the raw ranked hits themselves' or need to resolve symbol IDs or scope later get_context calls. This is concrete and actionable.
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.50.0get_health2 fields changedInput schema / properties / countsAdded value: +{
+ "default": "everything",
+ "title": "Counts",
+ "type": "string"
+}Input schema / properties / scopeAdded value: +{
+ "default": "all",
+ "title": "Scope",
+ "type": "string"
+}v0.48.0get_answer1 field changedInput schema / properties / includeAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Include"
+}get_change_risk2 fields changedInput schema / properties / finding_idAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Finding Id"
+}Input schema / properties / includeAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Include"
+}get_dead_code1 field changedInput schema / properties / finding_idAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Finding Id"
+}get_health13 fields changedInput schema / properties / cursorAdded value: +{
+ "default": 0,
+ "title": "Cursor",
+ "type": "integer"
+}Input schema / properties / finding_idAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Finding Id"
+}Input schema / properties / opportunity_idAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Opportunity Id"
+}Input schema / properties / performance_boundaryAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Performance Boundary"
+}Input schema / properties / performance_confidenceAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Performance Confidence"
+}Input schema / properties / performance_contextAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Performance Context"
+}Input schema / properties / performance_sortAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Performance Sort"
+}Input schema / properties / performance_viewAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Performance View"
+}Input schema / properties / plan_idAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Plan Id"
+}Input schema / properties / refactoring_confidenceAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Refactoring Confidence"
+}Input schema / properties / refactoring_effortAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Refactoring Effort"
+}Input schema / properties / refactoring_typeAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Refactoring Type"
+}Input schema / properties / refactoring_view / defaultPrevious value: -"canonical"New value: +"diversified"get_risk1 field changedInput schema / properties / includeAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Include"
+}get_symbol1 field changedInput schema / properties / referenceAdded value: +{
+ "anyOf": [
+ {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Reference"
+}get_why2 fields changedInput schema / properties / idAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Id"
+}Input schema / properties / referenceAdded value: +{
+ "anyOf": [
+ {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Reference"
+}list_reposv0.45.0get_health1 field changedInput schema / properties / refactoring_viewAdded value: +{
+ "default": "canonical",
+ "title": "Refactoring View",
+ "type": "string"
+}v0.44.0get_change_risk3 fields changedInput schema / properties / revspec / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / revspec / defaultPrevious value: -"HEAD"New value: +nullInput schema / properties / revspec / typeRemoved value: -"string"get_dead_code2 fields changedInput schema / properties / min_confidence / anyOfAdded value: +[
+ {
+ "type": "number"
+ },
+ {
+ "type": "string"
+ }
+]Input schema / properties / min_confidence / typeRemoved value: -"number"v0.41.0get_symbol1 field changedInput schema / properties / depthAdded value: +{
+ "default": 1,
+ "title": "Depth",
+ "type": "integer"
+}v0.39.0get_answerget_dead_code1 field changedInput schema / properties / min_confidence / defaultPrevious value: -0.5New value: +0.4get_health1 field changedInput schema / properties / onlyAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Only"
+}list_repossearch_codebasev0.33.0generate_refactoring_codeget_answerget_change_risklist_repossearch_codebasev0.31.0get_symbol5 fields changedInput schema / properties / idAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Id"
+}Input schema / properties / symbol_id / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / symbol_id / defaultAdded value: +nullInput schema / properties / symbol_id / typeRemoved value: -"string"Input schema / requiredRemoved value: -[
- "symbol_id"
-]v0.1.0generate_refactoring_codeget_answerget_contextget_dead_codeget_healthget_overviewget_riskget_symbolget_whylist_repossearch_codebaseScored across 10 tools
Each tool targets a distinct analytical concern: health scores, change risk, context triage, decision rationale, question answering, dead code, overview, history risk, symbol bodies, and raw search. Where overlap exists (get_answer vs get_why vs search_codebase, get_health vs get_risk), the descriptions explicitly carve out boundaries and direct callers to the right tool.
Nine of ten tools follow a consistent get_<subject> pattern, making the set predictable and easy to navigate. search_codebase breaks the pattern slightly, though it is still readable and uses a clear verb-object structure.
Ten tools is well-scoped for a code intelligence and health analysis server. Each tool covers a distinct capability with no obvious redundancy, and the count is squarely in the comfortable range for an MCP server.
The surface covers the full read-only exploration lifecycle: orient with get_overview, search with search_codebase, answer questions with get_answer, drill into context/symbols, assess health/risk/dead code, and understand rationale with get_why. There are no obvious dead ends, and the tools are designed to chain together coherently.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Codebase graphs, caller impact analysis, and recorded project context for AI coding agents.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
