Tool Reference

Tool Reference

SymForge exposes 32 MCP tools. They are grouped by the job an agent is trying to do.

Use this page for

picking the right tool after SymForge is installed and connected.

Orientation

Tool	Purpose
health	Full index, watcher, parse, runtime, sidecar, capability, git temporal, and routing status
health_compact	Smaller health summary for tight context budgets
get_repo_map	Bounded repository map with language/file/symbol summaries
explore	Concept-driven exploration across symbols, files, and patterns
ask	Natural-language codebase question routed to the right internal path, with route confidence and rationale; tool-recommendation questions return a workflow-grouped tool catalog
conventions	Detect local coding, test, naming, and error-handling conventions
context_inventory	Show what files/symbols have already been loaded this session
investigation_suggest	Surface likely gaps in the current investigation

Reading

Tool	Purpose
get_file_context	Start here for source files: outline, imports, references, consumers, and git activity
get_file_content	Exact raw content, line ranges, chunks, match excerpts, and symbol excerpts
get_symbol	Full source of one or more symbols
get_symbol_context	Symbol body plus callers, callees, type dependencies, and edit-prep context
inspect_match	Deep-dive one search match in enclosing symbol context

Search

Tool	Purpose
search_symbols	Find symbols by name, kind, language, or path prefix
search_text	Search text with enclosing symbol context; supports literal, OR terms, regex, and structural AST patterns
search_files	Find/rank paths, resolve exact or ambiguous paths, and optionally use frecency or co-change ranking

Impact And Change Inspection

Tool	Purpose
find_references	Call sites, imports, type usages, implementations, and qualified usages
find_dependents	File-level dependency graph
what_changed	Changed files by git ref, timestamp, or working tree
diff_symbols	Symbol-level diff between git refs
analyze_file_impact	Reindex one file and report changed symbols and affected dependents
validate_file_syntax	Syntax diagnostics with line/column locations for supported code/config files

Editing

Tool	Purpose
edit_plan	Inspect impact and recommend an edit sequence
replace_symbol_body	Replace an entire symbol body by name
edit_within_symbol	Scoped find/replace inside one symbol
insert_symbol	Insert code before or after a named symbol
delete_symbol	Delete a symbol and attached docs
batch_edit	Apply multiple symbol-scoped edits atomically
batch_insert	Insert before or after multiple symbols
batch_rename	Rename a symbol and update references project-wide

Indexing And Checkpointing

Tool	Purpose
index_folder	Reindex a repository from scratch, with optional idempotency_key for safe retries
checkpoint_now	Atomically write the in-memory index to .symforge/index.bin, optionally verifying after write; in daemon-proxy mode the checkpoint runs against the daemon's authoritative index, and a degraded local fallback discloses itself in the receipt

Deprecated Compatibility

trace_symbol remains only as a daemon compatibility alias for older clients. Generated client allow-lists should not grant it. Use:

• get_symbol_context for multi-hop symbol context;
• find_references for callers, imports, type usages, and implementations.

Result Status Metadata

Core tool responses include machine-readable status metadata where the MCP transport can carry it. This lets agents distinguish:

• found
• not found
• ambiguous
• invalid request
• empty result
• internal failure

The human-readable text remains, but agents should prefer the stable status metadata when deciding whether a step succeeded.

Ranking Options

search_files ranks path matches by default.

Frecency:

{
  "query": "cache",
  "rank_by": "frecency"
}

Co-change:

{
  "query": "routes",
  "rank_by": "path+cochange",
  "anchor_path": "src/auth/routes.rs"
}

Use debug_ranking=true when you need an explanation of the ordering.

Structural Search

search_text can use AST patterns when structural=true.

search_text(query="fn $NAME($$$) { $$$ }", structural=true, language="Rust")

$NAME captures one AST node. $$$ captures zero or more nodes.

Edit Behavior

SymForge edit tools are intended to replace raw text-copy editing for source code. Important behaviors:

• symbol-addressed range resolution
• doc-comment-aware ranges
• automatic indentation where supported
• tee snapshots: the pre-write file is preserved under .symforge/tee/ before every edit lands
• atomic writes, then reindexing from the persisted on-disk bytes (never the in-memory buffer)
• optional idempotency_key: same key + same canonical request replays the stored result; same key + different request is a deterministic conflict
• result-status metadata and per-operation batch statuses
• optional explicit working_directory routing into sibling git worktrees; routed responses self-describe with wrote_to, indexed_path, and rerouted

Worktree routing details

• Routed single-symbol edits compound correctly: when the worktree target has diverged from the indexed copy (for example, after an earlier routed edit), the edit base is re-read and re-parsed from the target bytes, and the envelope reports Source authority: worktree target (rebased).
• Routed writes never overwrite the index entry for the indexed copy — the index keeps describing the indexed root truthfully.
• Routed batch tools (batch_edit, batch_insert, batch_rename) fail closed with an actionable error when the worktree target has diverged, because their splices are resolved against the index snapshot; use the single-symbol tools for sequential routed edits to the same file.

Prompts

SymForge also exposes MCP prompts for higher-level workflows:

• symforge-review
• symforge-architecture
• symforge-triage
• symforge-onboard
• symforge-refactor
• symforge-debug

These prompts return procedure-oriented instructions and resource links that tell the agent which SymForge tools to call next.

Resources

Static resources:

• symforge://repo/health
• symforge://repo/outline
• symforge://repo/map
• symforge://repo/changes/uncommitted
• symforge://tools/catalog — workflow-grouped index of SymForge's tools

Resource templates:

• symforge://file/context?path={path}&max_tokens={max_tokens}
• symforge://file/content?...
• symforge://symbol/detail?path={path}&name={name}&kind={kind}
• symforge://symbol/context?name={name}&file={file}

Practical Defaults

• Use get_file_context before reading source files.
• Use search_symbols, search_text, or search_files before broad raw scans.
• Use get_file_content for exact docs/config prose.
• Use edit_plan before non-trivial edits.
• Use analyze_file_impact after targeted edits.
• Use index_folder after broad multi-file work or root changes.