Tool Catalog

import { Aside } from ‘@astrojs/starlight/components’;

All 21 Forge 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
`forge_prepare`	Pre-modification analysis — everything the agent needs to know before editing a file	Dependents, imports, health, coverage, git activity, GO / CAUTION / STOP
`forge_validate`	Post-modification verification — check that edits didn’t introduce new problems	Health delta (resolved vs introduced), import validity
`forge_understand`	Deep comprehension — full structural analysis of a file or symbol for unfamiliar code	Symbols, callers, dependencies, coverage, recent history

Typical sequence:

forge_prepare(file)   → plan the work
[edit the file]
forge_validate(file)  → verify nothing broke

Search tools

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

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

Example calls:

forge_search("retry logic")                         → files/snippets mentioning retry
forge_pattern_search("async function $NAME($$$)")  → all async functions
forge_search_symbols("PaymentService")              → all symbols named PaymentService

Graph tools

Query the dependency graph for structural relationships between files.

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

Example calls:

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

Health tools

Tool	One-line description
`forge_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 .forge/plugins/*.yaml. See How-To: Write a Custom Health Check.

Community Mode users can call forge_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
`forge_parse_file`	Return every symbol in a file with type, line number, and export status
`forge_extract_symbol`	Return the full source text of a named symbol (function, class, type)

Example calls:

forge_parse_file("src/api/routes.ts")            → [{name: "handleCheckout", type: "function", line: 42, exported: true}, ...]
forge_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
`forge_git_history`	Last N commits touching a file — hash, author, date, commit message
`forge_git_blame`	Per-line authorship for a line range — who wrote what and when

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

Ingest tools

Tool	One-line description
`forge_ingest_scip`	Ingest a SCIP index to upgrade heuristic import edges to compiler-resolved edges
`forge_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 forge_prepare output. See How-To: Multi-language Repo for SCIP setup.

Index management tools

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

forge_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
`forge_search` (keyword only)	All MCP server tools
`forge_search_symbols`	`forge_search` semantic/hybrid mode
`forge_health_check`	All workflow tools

Run forge 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