MCP tools: overview

Most MCP servers expose tools that mirror data entities: one file, one symbol, one diff. That forces the agent into long sequential chains. Repowise exposes a small, curated set of task-shaped tools instead. Pass multiple targets in one call. Get complete context (docs, ownership, metrics, history, decisions) back. Same answer, fewer round-trips, fewer tokens.

The core tools#

These ten tools are the documented core surface, available in both single-repo and workspace modes:

get_risk and get_change_risk are the pair people mix up. get_risk scores indexed files by path and can report blast radius. get_change_risk scores the shape of a live diff, so it catches risky small changes that a file-level view misses.

One more tool is on by default, in workspace mode only: list_repos lists every workspace repo and which one is the default, so aliases are discoverable. A single-repo server is already bound to its only repository, so it does not advertise it. Ten tools by default in single-repo mode, eleven in a workspace.

18 tools are registered in total. The other seven are opt-in and covered below.

In workspace mode, every tool accepts a repo parameter naming a single repo. Only four tools also accept repo="all": search_codebase, get_dead_code, get_overview, and get_why in its workspace search mode. Every other tool returns an error for "all" and asks you to name one repo.

Seven opt-in tools#

Seven registered tools ship off by default in every mode. Three of them are workspace-scoped: they answer cross-repo questions that have no single-repo equivalent, and naming them outside a workspace does nothing, since they cannot do useful work there.

The two workspace tools with their own page are documented in full on the Workspace MCP mode page. get_conformance findings still surface automatically in get_risk's PR-mode directive (conformance_violations / dependency_cycles) without opting the tool itself in.

set_finding_status is the only tool on the whole surface that writes. Everything else reads.

Turning them on#

Turn any of them on per repo in .repowise/config.yaml:

mcp:
  tools: ["+get_execution_flows", "+get_dependency_path", "+generate_refactoring_code"]

or per launch with repowise mcp --tools "+get_execution_flows". See Configuring the tool surface for the full +/- delta syntax and the explicit-allowlist / all shapes.

generate_refactoring_code has a second gate on top of the tool-surface one: even opted in, it returns an error unless refactoring.llm.enabled is also set in .repowise/config.yaml.

Reading a response: the envelope#

Every tool answers inside the same envelope, and the envelope is where a response says how far to trust it. An agent that reads only the payload will over-read some answers and under-read others. Four things are worth checking.

Which commit the answer describes. _meta.indexed_commit is the 12-character SHA the index was built against, and index_age_days is how long ago that was. live_head carries your current checkout when .git/HEAD is readable, and index_behind says whether the two have diverged. stale_warning fires only on a real signal: HEAD moved and the files it moved are files this response served, or git is unreachable and the index is over roughly 90 days old. Two commits with identical trees report index_behind with no warning, because nothing served actually changed. Silence on stale_warning means the index is current. Do not infer staleness from its absence.

Whether anything broke or was capped. _meta.state appears only when something fired. degraded: true comes with degraded_reasons, which maps each contributing key to the reason behind it: a failed artifact read, a synthesis reason string, the retrieval legs that broke. That distinction matters, because it turns an empty result from "there is nothing here" into "this read failed". state.truncated means a field was capped when it was built, and state.partial that part of the answer is missing.

What it cost, and what it dropped. _meta.response_budget is always present and carries limit_chars (the ceiling that applied), tier (default or expanded, chosen by whether the call passed an expansion argument such as include), and serialized_chars (what was delivered under it). The default ceiling is 24,000 characters and an expanded call gets 32,000, lowered further when the host's own output cap is tighter, so a response can never reach the host's spill-to-file path and cost the agent a Read. Responses size themselves by content class: characters convert to tokens at a different measured rate for paths, code bodies, JSON structure and prose, so a budget is not one flat divisor. Each tool declares its own cheapest-loss-first shed order, so the block that goes first is the one worth least. When a response is trimmed it says what it dropped, in *_omitted counts and *_reason fields beside the collection they came from. Dropped content is recoverable: _meta.omitted lists refs (repowise#<12-hex>) that resolve via get_symbol or repowise expand <ref> from a shell. See Distill for the reversibility model.

What the answer did not look at. _meta.scope_hint, on get_answer and get_context, fires when knowledge-graph layers exist that contain none of the paths served. It names up to three of them with file counts. An answer about the ingestion pipeline that never touched the CLI layer will tell you so, which is the difference between "not relevant" and "not looked at".

A zero carries its basis#

An empty callers list reads the same whether the resolver bound nearly every call site in that language or guessed at most of them. So an empty one never ships alone. When get_context returns an empty callers, callees or used_by, it attaches a matching *_basis for that target's language:

A populated list gets no basis, since the rows are their own evidence. get_dead_code carries the same thing repo-wide as call_resolution_basis in its summary, one entry per language.

Read the basis before deleting anything.

Connecting#

repowise init automatically writes .mcp.json at the project root and (for Claude Code) registers the server in ~/.claude/settings.json. You don't need to do anything else.

To wire up another editor manually:

{
  "mcpServers": {
    "repowise": {
      "command": "repowise",
      "args": ["mcp", "/path/to/your/project"]
    }
  }
}

A real five-call task#

"Add rate limiting to all API endpoints." Without repowise, an agent greps and reads files for ~30 calls. With repowise, five:

get_overview()
get_context(targets=["middleware", "api/routes", "payments"])
get_risk(targets=["middleware/auth.ts"])
get_why(query="rate limiting")
search_codebase(query="rate limit OR throttle OR retry")

That's the design point. Each call returns a task-shaped slice of the codebase, not a single file or symbol, so the agent reaches a decision in one or two passes instead of ten.

How to compose these#

Most tasks aren't a single call. These are the hand-offs that come up most often: what a tool's output points you to next.

Why a curated surface#

Repowise's internal modules expose more graph navigation primitives (callers/callees, dependency paths, graph metrics, execution flows, community detection). Most of that surfaces as include options on the core tools rather than separate calls; two of the primitives (get_dependency_path, get_execution_flows) are real MCP tools but ship off by default, because every extra tool in the schema is overhead on tasks that don't need it.

The public tools are deliberately one level up. get_context absorbs callers, callees, metrics, and community into a single call via its include parameter. get_risk rolls up hotspot, dependents, co-changes, reviewers, and test gaps. get_why covers natural-language search, path lookup, and the global health dashboard. get_health rolls up the three-signal marker scores plus targeted findings.

If you're building on top of repowise programmatically, the packages/server Python API exposes the lower-level primitives. The MCP surface is what AI agents see, and AI agents do better with fewer, richer tools.