Navigation and structure tools

Navigation tools move from a resolved source identity to definitions, references, implementations, and call edges. Prefer a producer-issued target_ref; use symbol or location inputs when no target exists yet.

Target inputs

The target-first flow is:

1. Run search or document_symbols.
2. Copy a row’s target_ref unchanged.
3. Pass it as target to navigation or impact_bundle.

target_ref has two strict variants:

{
  "kind": "result_match",
  "result_handle": "<SESSION_HANDLE>",
  "match_id": "m1",
  "target_scope": "<OPAQUE_SCOPE>"
}

{
  "kind": "stable_symbol",
  "repository_id": "<REPOSITORY_ID>",
  "stable_symbol_id": "<SYMBOL_ID>",
  "snapshot_token": "<SNAPSHOT_TOKEN>"
}

Do not combine target with legacy symbol, path, line, or column. A top-level repository_id beside target is only an equality assertion; a mismatch fails instead of retargeting the request.

Common navigation contract

These tools accept target or legacy symbol/location inputs, plus optional repository_id, limit, continuation, response_mode, and include_follow_up_structural:

Tool	Result rows	Important option
find_references	Definitions, declarations, and references with match_kind.	include_definition=false excludes the defining row.
go_to_definition	Definition candidates.	Preferred first jump from a resolved target.
find_declarations	Declaration candidates.	Use when declaration and definition differ.
find_implementations	Implementation edges.	Best for traits/interfaces; ordinary concrete types may have no meaningful implementation set.
incoming_calls	Callers.	Read availability before interpreting an empty set.
outgoing_calls	Callees.	Every edge is provisional; confirm it independently.

Each response reports a navigation mode:

Mode	Interpretation
precise	Precise data answered the request.
precise_partial	Precise data contributed but coverage is incomplete.
heuristic_no_precise	Useful heuristic evidence without precise coverage.
unavailable_no_precise	The request cannot be answered honestly without precise data.

mode describes navigation precision; completeness separately describes cardinality, truncation, and coverage. Call-hierarchy responses also expose availability. Never interpret zero rows as “no calls” when availability says the surface is unavailable.

outgoing_calls.trust is always provisional. Verify material callee edges with read_match, read_file, find_references, or search_structural before asserting them.

target_selection explains whether resolution succeeded or requires disambiguation, how it resolved (result_match, stable_symbol, direct_symbol, or direct_location), and which candidates were considered.

document_symbols

document_symbols returns a bounded hierarchical outline for path.

Parameter	Required	Default	Meaning
path	Yes	—	Canonical repository-relative path.
repository_id	No	session scope	Repository scope.
top_level_only	No	true	Return only the file’s main symbols.
limit	No	bounded server default	Maximum outline rows.
continuation	No	—	Opaque next-page token.
response_mode	No	compact	compact or full.
include_follow_up_structural	No	false	Attach replayable structural suggestions.

Rows can include match_id, target_ref, stable_symbol_id, source spans, signatures, children, and structural follow-ups.

inspect_syntax_tree

Use inspect_syntax_tree to learn the actual Tree-sitter node shape before writing a structural query.

Inputs are path, optional repository_id, 1-based line and column, max_ancestors, max_children, and include_follow_up_structural. The response returns focus, ancestors, and children, with independent ancestors_completeness and children_completeness.

This tool is cursor-sensitive. Move the cursor onto the identifier or call token if punctuation or a wrapper node becomes the focus.

search_structural

search_structural runs a Tree-sitter query over repository source.

Parameter	Required	Default	Meaning
query	Yes	—	Valid Tree-sitter query for the selected grammar.
language	No	inferred where possible	Language grammar.
repository_id	No	session scope	Repository scope.
path_regex	No	—	Restrict canonical paths.
limit	No	bounded server default	Maximum rows.
result_mode	No	matches	Grouped matches or raw captures.
primary_capture	No	automatic	Capture used as the visible grouped anchor.
include_follow_up_structural	No	false	Attach replayable structural suggestions.
continuation	No	—	Opaque deterministic next-page token.

Inspect anchor_capture_name, anchor_selection, and captures before assuming the visible row represents the whole match. inspect_syntax_tree and search_structural are always structured and do not accept response_mode.

Structural follow-ups

Set include_follow_up_structural=true to request typed follow_up_structural payloads that can be passed to search_structural. They are available on syntax/structural tools, document outlines, and the six navigation tools. They are not emitted by search_hybrid or search_symbol.

impact_bundle

impact_bundle resolves one target once and composes typed impact sections. Supply exactly one of:

• target; or
• non-empty legacy symbol.

Optional parameters are repository_id, path_class (default runtime), include_implementations, include_test_mentions (default false), and response_mode.

Sections use a closed vocabulary:

• symbol
• reference
• incoming_call
• implementation
• test_mention

Outgoing calls are intentionally excluded. Each section reports:

• execution: included, omitted_by_policy, or not_run_target_unresolved;
• trust: resolved target, exact literal text, or navigation mode;
• its own completeness;
• rows, a child result handle, and proof targets where available.

Test mentions run only when opted in and use exact literal text under test or tests paths. A zero count in an included section is honest evidence; an omitted or unresolved section is not.

Legacy symbol resolution stops on equal-rank ambiguity and returns disambiguation instead of silently choosing. See run an impact analysis for the target-first workflow.

Source Anchors

• ../frigg/crates/cli/src/mcp/types/navigation.rs
• ../frigg/crates/cli/src/mcp/types/target.rs
• ../frigg/crates/cli/src/mcp/server/navigation_tools.rs
• ../frigg/crates/cli/src/mcp/server/navigation_tools/impact_bundle.rs
• ../frigg/crates/cli/tests/tool_handlers/navigation.rs
• ../frigg/crates/cli/tests/rmcp_protocol.rs