One Tool: canopy_answer

Canopy’s MCP surface is exactly one tool: canopy_answer. You ask a question in natural language; a deterministic router maps it to a structural recipe; the recipe executes the whole retrieval chain server-side against the prebuilt index; one compact answer comes back. One call, one turn.

The same call exists on the command line — canopy answer "<question>" — with the repo auto-detected from your working directory.

Why one tool

Canopy v1 exposed a 31-tool catalog: search tools, graph tools, health tools, git tools, workflow composites. v2 replaced all of it with the single routed call, because the catalog was a context tax, not a capability.

The evidence is a control benchmark: an agent handed Canopy’s full v1 tool catalog and left to orchestrate it spent 2.3×–5.8× more tokens than plain shell — worse than having no tools at all. Tool schemas consume context before the first question is asked, and every choose-a-tool, read-the-result, choose-again cycle is a model turn.

The single routed call removes both costs. The agent makes one call; the tool selection, graph traversal, ranking, and formatting all happen inside Canopy. On the same benchmark suite, that design answers at +76% correctness (0.932 vs 0.530) and −69% tokens versus the shell loop. The lift is the single routed call — not tool access.

The question shapes

Phrasing picks the recipe. Fourteen question shapes cover the surface; name the entity type and put paths and symbols in backticks so the router locks on.

Shape	Ask it like this
Locate a symbol	where is the function/struct/class `Sym` defined?
Extract a symbol’s code	show `Sym` in `path`
Explain a file	what does `path` do?
Public surface	public surface of `path`
Dependents / blast radius	what depends on `path`? · what calls `Sym`?
Imports	what does `path` import?
Ownership	who last changed `path`?
Test coverage	what tests cover `path`? · coverage of `path`
Wiring / dead code	is `path` reachable? · is `path` dead code?
Import cycles	`are there import cycles?`
Pre-edit dossier	what should I know before editing `path`?
Filtered symbols	list functions defined in `dir/`
Architecture	`architecture overview`
Concept fallback	`how does <concept> work?`

The concept fallback is the weakest recipe — a semantic search over the chunk index. Prefer a specific shape whenever you can name a file or symbol. See Phrasing Picks the Recipe for good/bad phrasing pairs per shape.

How routing works

The router is a deterministic classifier — a pure function of the question text:

No LLM call, no network. Routing costs zero model turns and never varies run to run. The same question always routes to the same recipe.
Corpus-validated. The router is regression-tested against a labelled question corpus and currently routes 360/360 to the correct recipe.
Signal-driven. It keys on the entity type you name (“the function”, “the file”) and on backticked paths and symbols. Questions without those signals fall through to the concept fallback.

Once routed, the recipe runs the entire chain server-side — symbol lookup, dependency-graph traversal, full-text or semantic retrieval, ranking, formatting — and returns a structured answer. The agent never orchestrates intermediate steps.

Honest no-match

When nothing in the index clears the calibrated relevance floor, Canopy says so:

No strong match in this repository for …

It does not relay tangential files to look busy. An empty answer is signal, not noise — usually it means the thing doesn’t exist in this repo, or the phrasing needs a backticked path or symbol and an entity type.

Availability by tier

Every tier ships canopy_answer and the MCP server. Community runs the keyword recipes over the full local AST and full-text index. Solo and above add semantic search (embeddings) — the answer-quality lever.

Full reference

For the tool’s input schema and answer formats: Reference: MCP Tools