Search tools

Frigg separates exact lookup, known-symbol lookup, ranked discovery, and multi-hypothesis search. Pick the narrowest tool that matches what you already know.

Need	Tool	Trust model
Known literal or regex	`search_text`	Exhaustive within reported scope when `completeness.complete=true`.
Known API or identifier	`search_symbol`	Indexed symbol candidates with explicit completeness.
Broad natural-language discovery	`search_hybrid`	Ranked candidate pivots, never an exhaustive corpus claim.
Several independent hypotheses	`search_batch`	Per-probe trust plus deterministic consensus/RRF merge.

`search_text`

search_text is the repository-aware replacement for common rg and grep source scans.

Parameter	Required	Default	Meaning
`query`	Yes	—	Literal or regex pattern. The legacy alias `pattern` is accepted.
`pattern_type`	No	`literal`	`literal` or `regex`.
`repository_id`	No	session scope	Restrict to one repository.
`path_regex`	No	—	Regex over canonical repository-relative paths.
`glob` / `exclude_glob`	No	—	Repository-relative inclusion or exclusion globs.
`include_hidden`	No	`false`	Include hidden path segments.
`case_sensitive` / `ignore_case`	No	backend default	Explicit case policy.
`word`	No	`false`	Match whole words.
`context_lines`	No	`0`	Include surrounding source in each row.
`files_with_matches`	No	`false`	Return at most one row per matching file.
`count_only`	No	`false`	Return counts and intentionally omit match rows.
`max_count_per_file`	No	—	Cap rows retained from each file.
`collapse_by_file`	No	`false`	Collapse repeated paths into file rows.
`limit`	No	bounded server default	Maximum returned rows.
`continuation`	No	—	Opaque next-page token.
`response_mode`	No	`compact`	`compact` or `full`.
`include_context_efficiency`	No	`false`	Include narrowing and source-byte estimates.

total_matches is the exact raw eligible occurrence count only when coverage is complete. The authoritative completeness.unit changes with shaping: it can describe occurrences or files. When count_only=true, matches[] is intentionally empty; read the count and completeness fields.

Rows can include match_id and target_ref. Pair match_id with the response result_handle for read_match.

`search_symbol`

Use search_symbol when you know a type, function, method, trait, class, module, or other identifier.

Parameter	Required	Default	Meaning
`query`	Yes	—	Symbol name to search.
`repository_id`	No	session scope	Restrict to one repository.
`path_class`	No	runtime-first policy	`runtime`, `project`, `support`, or opt-in `any`.
`path_regex`	No	—	Restrict canonical paths.
`limit`	No	bounded server default	Maximum rows.
`continuation`	No	—	Opaque next-page token.
`response_mode`	No	`compact`	`compact` or `full`.

Symbol search locates candidates; it does not prove that an inline test module or overloaded name is the intended runtime definition. Confirm important rows with go_to_definition, document_symbols, or a proof read.

`search_hybrid`

Use search_hybrid for broad questions when you do not yet have a stable symbol, string, or path anchor.

Parameter	Required	Default	Meaning
`query`	Yes	—	Natural-language or code-shaped discovery query.
`repository_id`	No	session scope	Restrict to one repository.
`language`	No	—	Restrict candidates to one language.
`limit`	No	bounded top-k	Maximum ranked pivots.
`weights`	No	runtime defaults	Optional lexical, graph, and semantic channel weights.
`semantic`	No	runtime policy	Enable or disable the semantic channel for this request.
`response_mode`	No	`compact`	`compact` or `full`.
`include_context_efficiency`	No	`false`	Keep the efficiency slice of metadata.

Hybrid search is ranked discovery. Its completeness has no exact total, reports complete=false, and includes ranked_discovery. It does not accept continuation.

Compact mode retains ranking_note and best_pivot_path. Request full mode only when you need channel health, ranking attribution, semantic capability, or cache diagnostics. Move from a promising row to exact text, symbol, navigation, or source-read evidence before making a factual claim.

`search_batch`

search_batch tests 2–8 independent hypotheses concurrently. Each probe runs as a complete text, symbol, or hybrid search; Frigg does not turn them into one shared multi-query walk.

Batch parameters:

Parameter	Required	Default	Meaning
`probes`	Yes	—	Array of 2–8 typed probes.
`repository_id`	No	session scope	Shared scope for probes that omit their own repository.
`limit`	No	bounded server default	Maximum merged rows.
`response_mode`	No	`compact`	`compact` or `full`.
`continuation`	No	—	Opaque token bound to every probe, scope, and snapshot.

Each probe contains:

Field	Required	Meaning
`id`	Yes	Stable request-local identifier echoed in evidence and summaries.
`kind`	Yes	`text`, `symbol`, or `hybrid`.
`query`	Yes	Query for the selected search kind.
`repository_id`	No	Per-probe override.
`path_regex`	No	Text or symbol path scope.
`glob`	No	Text-probe include glob.
`path_class`	No	Symbol scope; echoed for text when supplied.
`pattern_type`	No	Text mode, defaulting to `literal`.

The merge is fixed reciprocal-rank fusion: sum(1 / (60 + rank_one_based)). Rows sort by consensus count, RRF score, derived match strength, and stable source coordinates. Interpret:

evidence[] for the contributing probe, rank, and trust;
consensus_count for independent probe agreement;
probe_summary[].trust for the search substrate, not completeness;
each probe summary’s own completeness, zero-hit reason, and recovery actions.

The compatibility input merge=rank_by_probe_hit_strength is accepted temporarily and normalized to fixed RRF, but it is hidden from the public schema. New clients must omit it.

Compact and full responses

The four search tools accept response_mode. Compact mode removes bulky metadata and note fields but retains authoritative completeness, handles, targets, recovery, and next_actions. Full mode is for diagnosis, not a prerequisite for safe follow-up.

Source Anchors

../frigg/README.md
../frigg/crates/cli/src/mcp/types/search.rs
../frigg/crates/cli/src/mcp/server/search_tools/text.rs
../frigg/crates/cli/src/mcp/server/search_tools/hybrid.rs
../frigg/crates/cli/src/mcp/server/search_tools/symbol.rs
../frigg/crates/cli/src/mcp/server/search_tools/batch.rs
../frigg/crates/cli/tests/tool_handlers/search_batch.rs

Search tools

search_text

search_symbol

search_hybrid

search_batch