repowise is a codebase intelligence MCP server that provides AI coding agents with deep, graph-aware understanding of a repository through specialized tools — replacing dozens of file reads and greps with single, curated, high-context calls.
get_overview(): Synthesized architecture map, key modules, entry points, git health signals (hotspots, churn, bus factor), and community summaries — ideal as the first call on an unfamiliar codebase.
get_answer(question): Ask natural-language questions and get cited, confidence-rated answers backed by hybrid FTS + vector retrieval and graph expansion.
get_context(targets, include?): Triage cards for files, modules, or symbols — summaries, signatures, hotspot flags, governing architectural decisions, and symbol IDs — batched in a single call.
get_symbol(symbol_id): Fetch raw source for a single indexed function, class, or constant with live-verified line bounds — cheaper and safer than a raw file read.
search_codebase(query, mode?): Hybrid semantic + BM25 search by concept, symbol name, or file path, with automatic routing.
get_risk(targets, changed_files?): Git-temporal health (churn, ownership, blast radius) fused with graph topology and security findings. Pass changed files for PR mode to get actionable directives (will_break, missing_cochanges, missing_tests).
get_why(query?, targets?): Architectural decision records with evidence commits and supersession lineage; falls back to git archaeology when no formal ADRs exist.
get_health(targets?, include?): Per-file scores across defect risk, maintainability, and performance from 25 deterministic markers, with optional refactoring plans, trend alerts, and repo-wide KPI dashboards.
get_dead_code(...): Unused exports, unreachable files, and zombie packages tiered by confidence, with per-directory and per-owner rollups.
generate_refactoring_code(suggestion_id): Turn a deterministic refactoring plan from get_health into actual generated code and a unified git-style diff (opt-in, requires LLM config).
list_repos(): Enumerate all repos configured in workspace mode for multi-repo intelligence.
All tools return minimal context by default, with opt-in detail blocks to keep tool calls few and focused.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@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. Repowise reads your own agent transcripts for the corrections you keep making ("use the shared HTTP client, not raw requests") and turns the durable ones into tracked decisions it delivers back later. The wiki generation budget tilts toward the modules you and your agent ask about most. All local, all deterministic, no extra LLM calls.
Foundation | What it contributes |
Graph | File + symbol dependencies across 19 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 |
Decisions | Architectural rationale mined from five index-time sources plus human and agent capture, each claim traced to evidence |
Code health | 49 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 →
Three 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 →)
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 49 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 will break through structural dependencies, and which ones may drift through historical co-change? |
Breaking-change guard | Was an endpoint removed or a typed contract changed incompatibly, and which exact consumer files call it? |
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.” Field-level breaking diffs currently require a gRPC schema; HTTP supports endpoint-level removal detection.
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 →
19 languages parsed to AST · 35 on a five-rung ladder · framework-aware across all of them.
"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 (5) | C · Swift · PHP · Dart · Object Pascal | All of the above except the full health suite |
Partial (1) | Luau / Roblox | AST symbols and |
⎯⎯ tree-sitter parsing stops here; the rungs below come from git and imports ⎯⎯ | ||
Lightweight (7) | Elixir · Clojure · Haskell · Lean 4 · Erlang · F# · HTML | A real file-to-file import graph, and no symbol-level claims |
Structural (9) | Objective-C · 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. Languages on the way up the ladder, including COBOL, are 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) | ✅ 49 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 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 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 across defect, maintainability, and performance).
Both sides are analysed from their own content, so a finding present at
head is only reported when the diff explains it; every finding names its
``attribution`` basis and confidence.
Trust ``health_delta.status``: ``partial`` means files were skipped and the
change is not cleared. ``scope`` counts what was actually compared.
``impacted_tests`` keeps measured coverage and inferred candidates distinct.
``prior_fixes`` counts past fixes overlapping this diff. ``change_shape``
ranks the diff's size and spread against recent commits.
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 succeeds richly. It explains the comparison logic (findings reported only when the diff explains them), the meaning of health_delta.status=partial, scope counting, impacted_tests separation, prior_fixes semantics, and the idempotent include behavior. This is far beyond minimum disclosure.
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 section earns its place: a front-loaded purpose statement, behavioral semantics, and then a clean Args list. Formatting is scannable, and there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given seven optional parameters, an output schema, and complex change-risk semantics, this description covers all invocation aspects, return field meanings, status interpretation, and edge cases like clean trees and skipped files. Nothing essential for correct selection or invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining all seven parameters with concrete examples and behavioral details. revspec, repo, extensions, exclude_patterns, baseline, include, and finding_id each receive meaningful semantics beyond their schema types and 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 clearly identifies the tool's job: reviewing a commit, base..head range, or uncommitted work, and it details what the output leads with (directive, health_delta). It is specific about the resource and operation, though it never explicitly distinguishes this from the sibling get_risk, so the differentiation is inferred rather than stated.
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 invocation context: how to pass revspec, when to omit it, how to control include modes, and how to expand findings. However, it does not say when to prefer this tool over alternatives like get_risk, nor does it state exclusions or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
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?
With no annotations, the description carries the full behavioral burden and meets it thoroughly. It discloses conditional fields (fix_history only on counted fixes, episodes only when records exist), the default no-source-bytes behavior, size limits, reduction counts with _meta.omitted recovery refs, _meta.recovery_unavailable storage failure, and explicitly clarifies that include-gated blocks are projections, not omissions.
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, the description is dense with high-value information and well-structured: a headline, a returns paragraph, conditional behavior, batching advice, size limits, error signaling, and an Args block. Every sentence earns its place, and the core scoping statement is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex with 4 parameters and no annotation support, yet the description covers target formats, include-block semantics, conditional fields, batching, output sizing, reduction recovery, and error indications. Since an output schema exists, returning to explain shell return values is unnecessary; nothing an agent needs to call this correctly 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 fully compensate, and it does. It explains targets as file paths, module paths, or "path::Symbol" ids; enumerates all include block keys; defines compact's default and its effect; and clarifies repo is usually omitted. Every parameter receives meaningful semantics 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 opens with a specific verb and resource: "Triage card for files / modules / symbols — relationships, not source bytes." It clearly enumerates what is returned (title, summary, signatures, hotspot bit, decision_record titles) and distinguishes itself from siblings like get_symbol, get_risk, and get_why without needing to inspect their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing guidance: "Either one is a cue to call get_risk," "get_why serves the bodies," and "Do not call get_symbol per signature." It also advises batching targets and using one call with include=["skeleton"] instead of reading files separately, covering both when and when-not to use alternatives.
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 return ranked files and findings.
Never recomputes health: commit changes, then run ``repowise update``.
Every block and accepted value: docs/agent/MCP_TOOLS.md.
Args:
targets: file paths or ``module:<name>``. Empty means dashboard;
unmatched ones land in ``unresolved``, surviving ``only``.
include: ``biomarkers`` | ``refactoring`` | ``trend`` | ``coverage`` |
``accuracy`` | ``signals`` | ``churn_complexity``, or a dimension.
``performance`` and ``refactoring`` add their queues.
only: keys to keep; identity, counts and recovery survive.
``biomarkers``, ``accuracy`` and ``refactoring`` alias their block
key. ``performance``, ``defect`` and ``maintainability`` do not:
they filter rows and land in ``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: stable ``id`` from a health finding.
plan_id: stable ``id`` from a refactoring plan.
opportunity_id: ``perf...`` or ``refop...`` id from a directive or
queue: the unit, its steps or plan, and evidence paged by
``only=["*_evidence"]``. Excludes the two ids above.
refactoring_view: ``diversified`` (default) | ``canonical`` |
``file_spread``; refactoring_type / _confidence / _effort filter.
performance_view / _context / _boundary / _confidence / _sort: queue
projection and filters; the facets list them.| Name | Required | Description | Default |
|---|---|---|---|
| only | No | ||
| repo | No | ||
| limit | No | ||
| 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 reveals key behaviors: read-only over stored data, dashboard vs ranked-file modes, 'unmatched ones land in unresolved, surviving only', 'only' alias/filter effects, and the exclusive nature of opportunity_id. This goes well beyond a generic 'get health data' 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?
The description is long but every sentence is information-dense and earns its place. It front-loads purpose and the most important behavioral caveat, then presents parameters in a consistent terse format that avoids filler for an 18-parameter tool.
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 highly complex tool with no annotations, this is remarkably complete: it discloses storage/read behavior, update prerequisite, special identifiers, view modes, filters, and fallback fields like unresolved and unknown_only_keys. Because an output schema exists, the lack of a return-format explanation 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 coverage is 0%, but the description compensates by explaining every parameter: targets accepts file paths or module:<name>, include lists accepted facets and queue side-effects, only explains key persistence and aliasing, and the refactoring_/performance_ parameters describe projections and filters. The docs pointer 'docs/agent/MCP_TOOLS.md' also fills in accepted values.
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 line 'Code-health scores and findings from stored analysis' names a specific domain and return type, and the next sentence sharpens behavior: 'No targets returns a dashboard; targets return ranked files and findings.' This differentiates get_health from sibling tools such as get_overview or get_risk by its health-analytics focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it reads stored analysis and 'Never recomputes health', with the explicit prerequisite 'commit changes, then run repowise update' when freshness is needed. It does not compare against sibling MCP tools by name, but the stored-analysis caveat is enough to steer an agent away from using this as a computational tool.
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. 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 behavioral burden and does so thoroughly. It discloses that structural reach is not proof of runtime breakage, that structural_impact_score is uncalibrated and never a probability, that overall_risk_score is a deprecated alias, and that include-gated blocks are projections rather than omissions.
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 adds a distinct fact and it is well structured with an opening purpose, signal definitions, PR-mode directives, caveats, response limits, and an Args section. It could be trimmed, but the density is justified for a tool with many behavioral caveats.
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 zero annotations, zero schema descriptions, and a complex response surface, this description is complete. It covers purpose, selection criteria, parameter semantics, response shape, size limits, recovery metadata, and safety caveats, leaving nothing essential for correct invocation unexplained.
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 Args section compensates by explaining all four parameters: targets as file paths, repo as usually omitted, changed_files as PR-changed files for blast-radius mode, and include as opt-in blocks with concrete values like 'graph', 'churn', and 'scales'. This fully covers the parameter semantics gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line, 'What history says about touching these files — bug fixes, churn, owners,' states the tool's purpose with a specific verb and resource. It further clarifies by describing the fused signal types and explicitly distinguishing get_risk from get_change_risk, which handles commit/range scoring.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: pass changed_files for PR mode, read the directive block first, and use get_change_risk instead for commits or base..head ranges. It also notes that repo is 'usually omitted,' giving the agent practical invocation context.
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. ``answer_basis`` names
the strongest lane the response rests on (decision, episode, rationale,
archaeology, documentation); only a decision is a ruling, the rest are
evidence to weigh.
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, the description carries the full behavioral disclosure burden. It reveals key behaviors: fallback to git archaeology when no decisions exist, never-empty results, provenance/evidence_refs semantics, shared evidence meaning, and the answer_basis lane distinction. This is substantially more transparent than typical tool descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place, covering purpose, usage timing, query modes, behavioral semantics, and arguments. The backtick-wrapped terms add mild noise, but the structure is logical and front-loaded with the core purpose.
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 five parameters, no annotations, and complex multimodal behavior, the description is remarkably complete. It explains all query modes, fallback behavior, result semantics, and parameter roles. The output schema exists, so not detailing the exact response format is acceptable; the agent has enough information to invoke and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents all five parameters (query, targets, repo, id, reference) with functional meaning and even notes caller conveniences like accepting id and repository together. Some entries are terse (e.g., "repo: usually omitted"), but overall the parameter semantics are well covered.
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 explains code decisions and evidence ("Why this code is shaped this way — decision records + evidence commits") and enumerates concrete query modes. It does not explicitly differentiate from siblings like get_answer or get_context, but its purpose is specific and not confusable after reading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit trigger condition ("Call before refactors or pattern divergences") and describes all invocation modes. It does not name alternative sibling tools or state when not to use it, but the usage context is clear enough for an agent to decide.
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.
Most tools have clearly distinct purposes, and the descriptions actively cross-reference each other to prevent misrouting (e.g., search_codebase defers to get_answer, get_symbol is explicitly not an entry point). However, get_risk, get_change_risk, and get_health are adjacent in meaning and could be confused without reading the descriptions closely.
Nine of ten tools follow the exact get_<noun> pattern, and the one outlier, search_codebase, still follows verb_noun in the same snake_case style. The naming is highly predictable and easy to navigate.
Ten tools is a well-scoped size for a code-intelligence and analysis server. Each tool earns its place, covering orientation, retrieval, Q&A, risk, health, and dead-code analysis without feeling bloated or thin.
The tool surface covers the full analysis workflow: get_overview for orientation, get_context/get_symbol/search_codebase for exploration, get_answer for questioning, get_risk/get_change_risk for risk, get_health for maintenance, and get_why for design rationale. Obvious lifecycle gaps like updating stored analysis are intentionally handled outside the MCP surface, so no dead ends remain for the agent.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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.
Repo intel for AI coding agents: overview, PRs, contributors, hot files, CI, deps. Remote MCP.
Package intelligence MCP for AI agents — 22 tools, 19 ecosystems, AGPL SDK, free.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/repowise-dev/repowise'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
