Tool Catalog

All 21 Canopy MCP tools organized by category. For complete input/output schemas and example responses, see Reference: MCP Tools.

Workflow tools

Three composite tools that bundle multiple detail-tool calls into a single actionable result. Use these by default.

Tool	One-line description	Returns
`canopy_prepare`	Pre-modification analysis — everything the agent needs to know before editing a file	Dependents, imports, health, coverage, git activity, GO / CAUTION / STOP
`canopy_validate`	Post-modification verification — check that edits didn’t introduce new problems	Health delta (resolved vs introduced), import validity
`canopy_understand`	Deep comprehension — full structural analysis of a file or symbol for unfamiliar code	Symbols, callers, dependencies, coverage, recent history

Typical sequence:

canopy_prepare(file)   → plan the work
[edit the file]
canopy_validate(file)  → verify nothing broke

Search tools

Find code by concept, keyword, structural pattern, or symbol name.

Tool	One-line description	Notes
`canopy_search`	Full-text keyword search across indexed code chunks	Requires `--with-search` at index time. camelCase-aware: `payment` matches `processPayment`.
`canopy_pattern_search`	Structural AST pattern search (ast-grep syntax)	Use `$VAR` for single-node wildcard, `$$$VAR` for multi-node. Matches code structure, not text.
`canopy_search_symbols`	Symbol name search — find functions, classes, types by name	Available in Community Mode. No search index required.

Example calls:

canopy_search("retry logic")                         → files/snippets mentioning retry
canopy_pattern_search("async function $NAME($$$)")  → all async functions
canopy_search_symbols("PaymentService")              → all symbols named PaymentService

Graph tools

Query the dependency graph for structural relationships between files.

Tool	One-line description
`canopy_trace_imports`	Outbound edges — what does this file import? (direct only or transitive)
`canopy_trace_dependents`	Inbound edges — what files import this file? Call this before any refactor.
`canopy_check_wiring`	Is this file reachable from an entry point? Detects dead modules.
`canopy_find_cycles`	Find circular dependency chains — the root cause of “import not defined” errors
`canopy_dependency_graph`	Full dependency subgraph for a path, returned as JSON or DOT format

Example calls:

canopy_trace_dependents("src/lib/auth.ts")    → who will break if I change this?
canopy_check_wiring("src/utils/legacy.ts")   → is this module actually used?
canopy_find_cycles()                          → are there any cycles in the repo?

Health tools

Tool	One-line description
`canopy_health_check`	Run all health checks and return findings grouped by severity (P0 through info)

The four built-in checks:

Check	What it finds
`broken_imports`	Import paths that resolve to no indexed file
`dead_exports`	Named exports with zero consumers in the dependency graph
`circular_deps`	Import cycles (even indirect ones)
`secret_scan`	Hard-coded API keys, tokens, credentials (regex-based, configurable)

Additional checks can be added via .canopy/plugins/*.yaml. See How-To: Write a Custom Health Check.

Community Mode users can call canopy_health_check — it’s one of the three tools available without a license.

AST tools

Direct access to the parsed symbol table.

Tool	One-line description
`canopy_parse_file`	Return every symbol in a file with type, line number, and export status
`canopy_extract_symbol`	Return the full source text of a named symbol (function, class, type)

Example calls:

canopy_parse_file("src/api/routes.ts")            → [{name: "handleCheckout", type: "function", line: 42, exported: true}, ...]
canopy_extract_symbol("src/api/routes.ts", "handleCheckout")  → the function's full source text

Git tools

Require --with-git at index time.

Tool	One-line description
`canopy_git_history`	Last N commits touching a file — hash, author, date, commit message
`canopy_git_blame`	Per-line authorship for a line range — who wrote what and when

Why these matter for agents: canopy_prepare uses git history automatically to flag recently active files (high concurrent-edit risk). Call canopy_git_history directly when you need to understand why a file is in its current state.

Ingest tools

Tool	One-line description
`canopy_ingest_scip`	Ingest a SCIP index to upgrade heuristic import edges to compiler-resolved edges
`canopy_coverage`	Ingest a coverage report (LCOV, Istanbul JSON, Cobertura XML); enables per-file coverage in workflow tools

SCIP ingestion and coverage are optional but significantly improve the quality of canopy_prepare output. See How-To: Multi-language Repo for SCIP setup.

Index management tools

Tool	One-line description
`canopy_index_status`	Check which index layers are ready (AST, search, git), stale file counts, last index time
`canopy_reindex`	Trigger an incremental re-index of changed files (same as running `canopy index .` from CLI)

canopy_index_status is useful at the start of a session to confirm the index is current before running analysis.

Community Mode availability

Without a license, only three tools are available via CLI (MCP server mode requires a license):

Available in Community Mode	Requires paid license
`canopy_search` (keyword only)	All MCP server tools
`canopy_search_symbols`	`canopy_search` semantic/hybrid mode
`canopy_health_check`	All workflow tools

Run canopy upgrade to start a 14-day free trial that unlocks all 21 tools in MCP server mode.

Full reference

For input schemas, output schemas, example requests/responses, and error codes: Reference: MCP Tools