MCP API Reference

Complete reference for all 11 customer-facing Maguyva MCP tools. Each tool includes parameters, usage guidance, and best-for recommendations.

API Overview#

The Maguyva MCP API currently exposes 11 customer-facing tools across 4 main categories:

Core Search Tools - Advanced search capabilities across your codebase
Structural & Graph Tools - AST queries, symbol lookup, and dependency analysis
Code Analysis Tools - Deep code analysis and relationship mapping
System & Utility Tools - Repository context, deterministic compute, and guidance

All tools use a consistent repository identifier format: "owner/repo:branch". Branch defaults to main if not specified.

Omit repository when your MCP client supplies a request default or the key can access exactly one repository; otherwise pass it explicitly. Use repository_context(action="info", repository="owner/repo") to inspect how a repository resolves.

Repository Parameter Format#

All MCP tools use this repository identifier format:

With branch: "owner/repo:branch" - e.g., "owner/repository:develop"
Default branch: "owner/repo" - uses main branch when no branch is specified "owner/repository"
Request or sole-repository default: Omit repository when the MCP client supplies a request default or the key can access exactly one repository; otherwise pass it explicitly

Example prompts:

Ask about a specific repo:  "Search owner/my-repo for authentication middleware"
List accessible repos:      "What repositories can this Maguyva key access?"
Override for one query:     "Search owner/other-repo:develop for auth patterns"

Language Filtering#

All search tools support filtering results by programming language:

language_filter="python" - Filter to Python files only
language_filter="typescript" - Filter to TypeScript files only
Case-sensitive: Use lowercase language names
Default: Empty string (no filtering) - returns results from all languages
Supported coverage: Language filters work across the full 279+ supported languages and text-based technologies. See compatibility for the full list.

"Find authentication middleware in Python files only"
"Search for database connections in TypeScript"

API reference generated from source on July 22, 2026.

Core Search Tools#

intelligent_searchStable

Start here for any codebase question. Give it a natural-language query (e.g. "how does auth work", "where is billing handled") and it auto-routes across semantic, symbol, structural, and dependency search of the indexed repo. Prefer this over the Explore agent and Grep/Glob for exploration and planning — it searches the whole indexed repo at once instead of scanning files.

Parameters:

queryRequired

Type: str
Description: Search query

repositoryOptional

Type: str
Description: Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.

modeOptional

Type: Literal[auto, hybrid, semantic, text, structural, ast, graph]
Default: auto
Description: Search mode

limitOptional

Type: int
Default: 10
Description: Maximum results in this ranked top-K window

language_filterOptional

Type: str
Description: Language filter

path_filterOptional

Type: str
Description: Filter by file path prefix

boost_by_importanceOptional

Type: bool
Default
Description: Opt-in: re-rank by centrality using per-symbol graph metrics (is_articulation_point, bridge_count, k_core, centrality, etc.). Default off for agent-safe ranking (global hubs can drown implementation hits); enable for architecture tours. Applies across all 4 modalities when each result carries symbol linkage.

branchOptional

Type: str
Description: Branch override

qualityOptional

Type: Literal[quick, balanced, thorough]
Default: balanced
Description: Search quality preset

include_contentOptional

Type: bool
Default: true
Description: Include content in results

explain_routingOptional

Type: bool
Default
Description: Include routing decision explanation

importance_weightOptional

Type: float
Default: 0.3
Description: Weight for importance boosting (0=none, 1=full)

orphansOptional

Type: bool
Default
Description: Include orphan symbols (no incoming references)

include_community_contextOptional

Type: bool
Default
Description: Include related symbols from same code community

community_depthOptional

Type: int
Default: 1
Description: Depth of community context expansion

graph_viewOptional

Type: Literal[dependency, type, data_flow, control_flow]
Default: dependency
Description: Graph view for metrics

seed_symbol_idsOptional

Type: list[str]
Description: Tier-1 task seeds: symbol IDs central to the current task. When set, re-ranks fused hits by Approach A depth-decay proximity (exact seed match + graph-edge hops). Additive — omit for global ranking.

seed_file_pathsOptional

Type: list[str]
Description: Tier-1 task seeds: indexed file paths the agent has open or just edited. When set, re-ranks fused hits by path proximity with 1/(1+d) depth-decay (same file → same dir → nearby packages). Additive — omit for global ranking.

Parameter	Type	Required	Default	Description
`query`	`str`	Yes	-	Search query
`repository`	`str`	No	-	Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.
`mode`	`Literal[auto, hybrid, semantic, text, structural, ast, graph]`	No	`auto`	Search mode
`limit`	`int`	No	`10`	Maximum results in this ranked top-K window
`language_filter`	`str`	No	-	Language filter
`path_filter`	`str`	No	-	Filter by file path prefix
`boost_by_importance`	`bool`	No		Opt-in: re-rank by centrality using per-symbol graph metrics (is_articulation_point, bridge_count, k_core, centrality, etc.). Default off for agent-safe ranking (global hubs can drown implementation hits); enable for architecture tours. Applies across all 4 modalities when each result carries symbol linkage.
`branch`	`str`	No	-	Branch override
`quality`	`Literal[quick, balanced, thorough]`	No	`balanced`	Search quality preset
`include_content`	`bool`	No	`true`	Include content in results
`explain_routing`	`bool`	No		Include routing decision explanation
`importance_weight`	`float`	No	`0.3`	Weight for importance boosting (0=none, 1=full)
`orphans`	`bool`	No		Include orphan symbols (no incoming references)
`include_community_context`	`bool`	No		Include related symbols from same code community
`community_depth`	`int`	No	`1`	Depth of community context expansion
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	No	`dependency`	Graph view for metrics
`seed_symbol_ids`	`list[str]`	No	-	Tier-1 task seeds: symbol IDs central to the current task. When set, re-ranks fused hits by Approach A depth-decay proximity (exact seed match + graph-edge hops). Additive — omit for global ranking.
`seed_file_paths`	`list[str]`	No	-	Tier-1 task seeds: indexed file paths the agent has open or just edited. When set, re-ranks fused hits by path proximity with 1/(1+d) depth-decay (same file → same dir → nearby packages). Additive — omit for global ranking.

Best For:

Index-wide or cold-start exploration when the right tool is unclear
Multi-modal fused ranking across semantic, text, structural, and graph

Not Recommended For:

A known symbol name — use find_symbol directly
A known path on disk — use local Read/Grep first

semantic_searchStable

Find code by meaning, not exact text. Use for conceptual queries like "retry logic" or "user onboarding flow" when you don't know the keyword or symbol name. Returns the most relevant code chunks ranked by importance. Prefer over Grep when the search is conceptual.

Parameters:

queryRequired

Type: str
Description: Search query (conceptual, meaning-based)

repositoryOptional

Type: str
Description: Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.

limitOptional

Type: int
Default: 5
Description: Maximum results in this ranked top-K window

similarity_thresholdOptional

Type: float
Default: 0.6
Description: Minimum similarity score

language_filterOptional

Type: str
Description: Language filter (python, typescript, etc.)

path_filterOptional

Type: str
Description: Filter by file path prefix

boost_by_importanceOptional

Type: bool
Default
Description: Opt-in: re-rank by PageRank centrality (default off for agent-safe ranking; enable for architecture tours)

branchOptional

Type: str
Description: Branch override (default: from repository param or main)

include_contentOptional

Type: bool
Default: true
Description: Include chunk content in results

graph_viewOptional

Type: Literal[dependency, type, data_flow, control_flow]
Default: dependency
Description: Graph view for metrics

Parameter	Type	Required	Default	Description
`query`	`str`	Yes	-	Search query (conceptual, meaning-based)
`repository`	`str`	No	-	Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.
`limit`	`int`	No	`5`	Maximum results in this ranked top-K window
`similarity_threshold`	`float`	No	`0.6`	Minimum similarity score
`language_filter`	`str`	No	-	Language filter (python, typescript, etc.)
`path_filter`	`str`	No	-	Filter by file path prefix
`boost_by_importance`	`bool`	No		Opt-in: re-rank by PageRank centrality (default off for agent-safe ranking; enable for architecture tours)
`branch`	`str`	No	-	Branch override (default: from repository param or main)
`include_content`	`bool`	No	`true`	Include chunk content in results
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	No	`dependency`	Graph view for metrics

Best For:

Conceptual queries ("how does auth work?", "caching strategy")
Cross-package similarity search

Not Recommended For:

A known symbol name — use find_symbol instead
Exact strings or error messages — use text_pattern_search

text_pattern_searchStable

Search indexed content. Exact and regex modes grep the full file/blob corpus; fuzzy content mode searches the bounded semantic chunk corpus. File and symbol scopes are fuzzy-only. Use local Grep for a tight directory already on disk.

Parameters:

queryRequired

Type: str
Description: Text pattern to search for

repositoryOptional

Type: str
Description: Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.

modeOptional

Type: Literal[fuzzy, exact, regex]
Default: exact
Description: Search mode

search_scopeOptional

Type: Literal[content, symbols, files]
Default: content
Description: What to search

limitOptional

Type: int
Default: 5
Description: Maximum results returned in this page

offsetOptional

Type: int
Description: Deprecated compatibility offset. Prefer cursor from pagination.next_cursor.

cursorOptional

Type: str
Description: Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged.

language_filterOptional

Type: str
Description: Language filter

path_filterOptional

Type: str
Description: Filter by file path prefix

case_sensitiveOptional

Type: bool
Default
Description: Case-sensitive matching

branchOptional

Type: str
Description: Branch override

fuzzy_algorithmOptional

Type: Literal[hybrid, trigram, levenshtein]
Default: hybrid
Description: Fuzzy matching algorithm

thresholdOptional

Type: float
Default: 0.05
Description: Minimum similarity threshold for fuzzy

semantic_fallbackOptional

Type: bool
Default
Description: Fall back to semantic search if no results

Parameter	Type	Required	Default	Description
`query`	`str`	Yes	-	Text pattern to search for
`repository`	`str`	No	-	Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.
`mode`	`Literal[fuzzy, exact, regex]`	No	`exact`	Search mode
`search_scope`	`Literal[content, symbols, files]`	No	`content`	What to search
`limit`	`int`	No	`5`	Maximum results returned in this page
`offset`	`int`	No	-	Deprecated compatibility offset. Prefer cursor from pagination.next_cursor.
`cursor`	`str`	No	-	Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged.
`language_filter`	`str`	No	-	Language filter
`path_filter`	`str`	No	-	Filter by file path prefix
`case_sensitive`	`bool`	No		Case-sensitive matching
`branch`	`str`	No	-	Branch override
`fuzzy_algorithm`	`Literal[hybrid, trigram, levenshtein]`	No	`hybrid`	Fuzzy matching algorithm
`threshold`	`float`	No	`0.05`	Minimum similarity threshold for fuzzy
`semantic_fallback`	`bool`	No		Fall back to semantic search if no results

Best For:

Exact strings, error messages, and regex
Trigram fuzzy matching for near-miss text

Not Recommended For:

A known path on disk — prefer local Grep
Conceptual queries — use semantic_search

Structural & Graph Tools#

structural_searchStable

Prefer preset=functions|classes|methods|imports|variables (or free pattern=). Find code by AST shape (not text). Mid-tier filters: name_pattern, node_type, decorator, parent_child. Path/ltree/call filters are advanced — set advanced=true when using them deliberately; flat advanced keys still accepted for back-compat. Supply at least one structural selector.

Parameters:

repositoryOptional

Type: str
Description: Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.

presetOptional

Type: Literal[functions, classes, methods, imports, variables]
Description: Preferred structural selector. Expands to cross-language AST node types — functions (function/arrow/method definitions across languages); classes (class/struct/impl definitions); methods (method definitions (and function_definition for languages without a method node)); imports (import/use/include statements); variables (variable/let/const/static declarations). Prefer over free-form pattern/node_type for browse-style queries.

patternOptional

Type: str
Description: Free-form pattern when presets are too coarse (auto-detected: 'def foo(' → node_type + name_pattern). Prefer preset= for browse queries.

name_patternOptional

Type: str
Description: Symbol name pattern (shell wildcard, bounded POSIX regex, or fuzzy text; max 256 characters)

node_typeOptional

Type: str
Description: AST node type (function_definition, class_definition, etc.) — prefer preset= for common shapes

decoratorOptional

Type: str
Description: Decorator name filter

base_classOptional

Type: str
Description: Base class filter

language_filterOptional

Type: str
Description: Language filter (python, typescript, etc.)

limitOptional

Type: int
Default: 20
Description: Maximum results returned in this page

offsetOptional

Type: int
Description: Deprecated compatibility offset. Prefer cursor from pagination.next_cursor.

cursorOptional

Type: str
Description: Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged.

path_filterOptional

Type: str
Description: Filter by file path prefix

branchOptional

Type: str
Description: Branch override

query_typeOptional

Type: Literal[node_type, name_pattern, parent_child]
Description: Explicit query type

parent_typeOptional

Type: str
Description: Parent AST node type filter

relationshipOptional

Type: Literal[parent, ancestor]
Default: parent
Description: For parent_child queries: direct parent only, or any ancestor (use ancestor for class methods nested under a class body/block)

has_modifierOptional

Type: str
Description: Filter by modifier (export, async, static, etc.)

advancedOptional

Type: bool
Default
Description: Set true when intentionally using advanced path/ltree/call filters (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Default false keeps the agent surface preset-first; flat advanced keys still work for back-compat with a metadata warning.

callee_textOptional

Type: str
Description: Advanced — prefer preset=functions|classes|methods|imports|variables. Call expression callee text filter. Set advanced=true when intentionally using path/ltree/call filters.

callee_nameOptional

Type: str
Description: Advanced — prefer preset=functions|classes|methods|imports|variables. Call expression callee name filter. Set advanced=true when intentionally using path/ltree/call filters.

field_roleOptional

Type: str
Description: Advanced — prefer preset=functions|classes|methods|imports|variables. AST field role filter. Set advanced=true when intentionally using path/ltree/call filters.

ltree_ancestorOptional

Type: str
Description: Advanced — prefer preset=functions|classes|methods|imports|variables. AST ltree ancestor path filter. Set advanced=true when intentionally using path/ltree/call filters.

ltree_descendantOptional

Type: str
Description: Advanced — prefer preset=functions|classes|methods|imports|variables. AST ltree descendant path filter. Set advanced=true when intentionally using path/ltree/call filters.

definition_nameOptional

Type: str
Description: Advanced — prefer preset=functions|classes|methods|imports|variables. Definition name filter. Set advanced=true when intentionally using path/ltree/call filters.

min_depthOptional

Type: int
Description: Advanced — prefer preset=functions|classes|methods|imports|variables. Minimum AST depth. Set advanced=true when intentionally using path/ltree/call filters.

max_depthOptional

Type: int
Description: Advanced — prefer preset=functions|classes|methods|imports|variables. Maximum AST depth. Set advanced=true when intentionally using path/ltree/call filters.

Parameter	Type	Required	Default	Description
`repository`	`str`	No	-	Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.
`preset`	`Literal[functions, classes, methods, imports, variables]`	No	-	Preferred structural selector. Expands to cross-language AST node types — functions (function/arrow/method definitions across languages); classes (class/struct/impl definitions); methods (method definitions (and function_definition for languages without a method node)); imports (import/use/include statements); variables (variable/let/const/static declarations). Prefer over free-form pattern/node_type for browse-style queries.
`pattern`	`str`	No	-	Free-form pattern when presets are too coarse (auto-detected: 'def foo(' → node_type + name_pattern). Prefer preset= for browse queries.
`name_pattern`	`str`	No	-	Symbol name pattern (shell wildcard, bounded POSIX regex, or fuzzy text; max 256 characters)
`node_type`	`str`	No	-	AST node type (function_definition, class_definition, etc.) — prefer preset= for common shapes
`decorator`	`str`	No	-	Decorator name filter
`base_class`	`str`	No	-	Base class filter
`language_filter`	`str`	No	-	Language filter (python, typescript, etc.)
`limit`	`int`	No	`20`	Maximum results returned in this page
`offset`	`int`	No	-	Deprecated compatibility offset. Prefer cursor from pagination.next_cursor.
`cursor`	`str`	No	-	Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged.
`path_filter`	`str`	No	-	Filter by file path prefix
`branch`	`str`	No	-	Branch override
`query_type`	`Literal[node_type, name_pattern, parent_child]`	No	-	Explicit query type
`parent_type`	`str`	No	-	Parent AST node type filter
`relationship`	`Literal[parent, ancestor]`	No	`parent`	For parent_child queries: direct parent only, or any ancestor (use ancestor for class methods nested under a class body/block)
`has_modifier`	`str`	No	-	Filter by modifier (export, async, static, etc.)
`advanced`	`bool`	No		Set true when intentionally using advanced path/ltree/call filters (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Default false keeps the agent surface preset-first; flat advanced keys still work for back-compat with a metadata warning.
`callee_text`	`str`	No	-	Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. Call expression callee text filter. Set advanced=true when intentionally using path/ltree/call filters.
`callee_name`	`str`	No	-	Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. Call expression callee name filter. Set advanced=true when intentionally using path/ltree/call filters.
`field_role`	`str`	No	-	Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. AST field role filter. Set advanced=true when intentionally using path/ltree/call filters.
`ltree_ancestor`	`str`	No	-	Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. AST ltree ancestor path filter. Set advanced=true when intentionally using path/ltree/call filters.
`ltree_descendant`	`str`	No	-	Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. AST ltree descendant path filter. Set advanced=true when intentionally using path/ltree/call filters.
`definition_name`	`str`	No	-	Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. Definition name filter. Set advanced=true when intentionally using path/ltree/call filters.
`min_depth`	`int`	No	-	Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. Minimum AST depth. Set advanced=true when intentionally using path/ltree/call filters.
`max_depth`	`int`	No	-	Advanced — prefer preset=functions\|classes\|methods\|imports\|variables. Maximum AST depth. Set advanced=true when intentionally using path/ltree/call filters.

Best For:

AST-level structure: classes, decorators, function/method presets
Finding code by shape rather than by text

Not Recommended For:

Plain-text or conceptual queries — use semantic_search or intelligent_search

dependency_searchStable

Primary blast-radius / graph surface. Answer "what calls this?" / "what does this use?" via the real call/import graph. For impact before edit: analysis_type="dependents" or analysis_type="impact" (incoming, shallow default for impact), include_metrics=false by default (opt in for centrality + refactor_risk). PR/diff impact (P1-8): pass changed_paths and/or patch (unified diff) — resolves symbols per path and returns a compact shallow-incoming dependents payload without requiring a symbol name. After an edit, set verify_after_edit=true with targets and/or changed_paths for a compact multi-root re-query of impacted symbols. Also supports dependencies, centrality, and orphans. analyze_dependencies is a thin alias for the impact path — prefer this tool for new agents.

Parameters:

repositoryOptional

Type: str
Description: Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.

queryOptional

Type: str
Description: Symbol name or search term

targetOptional

Type: str
Description: Symbol name (alias for query)

changed_pathsOptional

Type: list[str]
Description: Repo-relative paths for PR/diff impact (default) or, with verify_after_edit=true, post-edit verify roots. PR/diff: resolves symbols per path and walks shallow incoming dependents; may be combined with patch=. Verify: resolves up to 5 symbols per path as verify roots (capped lower inside verify mode). Does not require query/target for PR/diff impact.

patchOptional

Type: str
Description: PR/diff impact: unified diff / git patch text. Paths are parsed from diff --git / --- / +++ headers; same compact impact path as changed_paths.

analysis_typeOptional

Type: Literal[centrality, dependencies, dependents, impact, orphans]
Default: dependencies
Description: Analysis mode. impact = blast radius (incoming dependents; shallow depth when depth omitted). dependents also answers impact. When changed_paths or patch is set, analysis is forced to PR/diff impact. centrality/orphans do not require a target.

depthOptional

Type: Literal[shallow, balanced, deep]
Default: balanced
Description: Traversal depth. For analysis_type=impact and PR/diff impact the effective default is shallow unless you set depth explicitly.

limitOptional

Type: int
Default: 20
Description: Maximum results returned in this page

offsetOptional

Type: int
Description: Deprecated compatibility offset. Prefer cursor from pagination.next_cursor.

cursorOptional

Type: str
Description: Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged.

path_filterOptional

Type: str
Description: Restrict target symbol resolution by file path prefix; returned graph relationships may cross outside that path

language_filterOptional

Type: str
Description: Filter target resolution and browse results by language

directionOptional

Type: Literal[outgoing, incoming, both]
Description: Traversal direction (overrides analysis_type inference)

relationship_typesOptional

Type: list[str]
Description: Filter edge types (CALL, IMPORT, INHERITS_FROM, etc.). A non-empty list overrides graph_view defaults.

exclude_test_pathsOptional

Type: bool
Default: true
Description: Default true: exclude test, fixture, vendor, and example paths from traversal and centrality results. Set false to include them. Orphan analysis always applies its own stricter noise exclusions.

exclude_generated_pathsOptional

Type: bool
Default
Description: Exclude generated declarations plus build, coverage, cache, source-map, and minified artifact paths from traversal results

include_module_symbolsOptional

Type: bool
Default
Description: Default false: drop edges whose from_name or to_name is the synthetic __module__ symbol (module-level noise). Set true to include module-level edges in dependents/dependencies results.

branchOptional

Type: str
Description: Branch override

per_hop_limitOptional

Type: int
Description: Maximum relationships per hop (1-300)

include_metricsOptional

Type: bool
Default
Description: Opt-in graph metrics on result rows (compacted with refactor_risk). Metrics are also fetched internally when min_centrality>0 but not returned unless this is true.

metrics_detailOptional

Type: Literal[summary, full]
Default: summary
Description: When include_metrics=true: summary (default) returns decision signals + refactor_risk; full returns the larger curated metric set

include_edge_metadataOptional

Type: bool
Default
Description: Include raw edge metadata and weights (large). Compact impact payloads leave this off.

symbol_typesOptional

Type: list[str]
Description: Filter returned symbols by kind (function, class, method, etc.)

exact_matchOptional

Type: bool
Default
Description: Require exact symbol name match

find_similar_patternsOptional

Type: bool
Default
Description: Find similar usage patterns

min_centralityOptional

Type: float
Default: 0
Description: Minimum PageRank score. Metrics are fetched internally for filtering; graph_metrics are returned only when include_metrics=true.

graph_viewOptional

Type: Literal[dependency, type, data_flow, control_flow]
Default: dependency
Description: Graph view used for traversal relationship defaults, metrics, and centrality ranking; orphan analysis is calculated across all views

verify_after_editOptional

Type: bool
Default
Description: P2-7 post-edit verify mode: re-query the indexed impact graph for recently edited symbols in one compact multi-root response. Requires targets and/or changed_paths (or target/query). Defaults to shallow incoming dependents; results reflect the indexed graph (may lag live edits). When true, takes precedence over PR/diff impact on the same changed_paths.

targetsOptional

Type: list[str]
Description: When verify_after_edit=true: symbol names to re-verify (callers/dependents). Merged with target/query if both are supplied.

Parameter	Type	Required	Default	Description
`repository`	`str`	No	-	Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.
`query`	`str`	No	-	Symbol name or search term
`target`	`str`	No	-	Symbol name (alias for query)
`changed_paths`	`list[str]`	No	-	Repo-relative paths for PR/diff impact (default) or, with verify_after_edit=true, post-edit verify roots. PR/diff: resolves symbols per path and walks shallow incoming dependents; may be combined with patch=. Verify: resolves up to 5 symbols per path as verify roots (capped lower inside verify mode). Does not require query/target for PR/diff impact.
`patch`	`str`	No	-	PR/diff impact: unified diff / git patch text. Paths are parsed from diff --git / --- / +++ headers; same compact impact path as changed_paths.
`analysis_type`	`Literal[centrality, dependencies, dependents, impact, orphans]`	No	`dependencies`	Analysis mode. impact = blast radius (incoming dependents; shallow depth when depth omitted). dependents also answers impact. When changed_paths or patch is set, analysis is forced to PR/diff impact. centrality/orphans do not require a target.
`depth`	`Literal[shallow, balanced, deep]`	No	`balanced`	Traversal depth. For analysis_type=impact and PR/diff impact the effective default is shallow unless you set depth explicitly.
`limit`	`int`	No	`20`	Maximum results returned in this page
`offset`	`int`	No	-	Deprecated compatibility offset. Prefer cursor from pagination.next_cursor.
`cursor`	`str`	No	-	Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged.
`path_filter`	`str`	No	-	Restrict target symbol resolution by file path prefix; returned graph relationships may cross outside that path
`language_filter`	`str`	No	-	Filter target resolution and browse results by language
`direction`	`Literal[outgoing, incoming, both]`	No	-	Traversal direction (overrides analysis_type inference)
`relationship_types`	`list[str]`	No	-	Filter edge types (CALL, IMPORT, INHERITS_FROM, etc.). A non-empty list overrides graph_view defaults.
`exclude_test_paths`	`bool`	No	`true`	Default true: exclude test, fixture, vendor, and example paths from traversal and centrality results. Set false to include them. Orphan analysis always applies its own stricter noise exclusions.
`exclude_generated_paths`	`bool`	No		Exclude generated declarations plus build, coverage, cache, source-map, and minified artifact paths from traversal results
`include_module_symbols`	`bool`	No		Default false: drop edges whose from_name or to_name is the synthetic __module__ symbol (module-level noise). Set true to include module-level edges in dependents/dependencies results.
`branch`	`str`	No	-	Branch override
`per_hop_limit`	`int`	No	-	Maximum relationships per hop (1-300)
`include_metrics`	`bool`	No		Opt-in graph metrics on result rows (compacted with refactor_risk). Metrics are also fetched internally when min_centrality>0 but not returned unless this is true.
`metrics_detail`	`Literal[summary, full]`	No	`summary`	When include_metrics=true: summary (default) returns decision signals + refactor_risk; full returns the larger curated metric set
`include_edge_metadata`	`bool`	No		Include raw edge metadata and weights (large). Compact impact payloads leave this off.
`symbol_types`	`list[str]`	No	-	Filter returned symbols by kind (function, class, method, etc.)
`exact_match`	`bool`	No		Require exact symbol name match
`find_similar_patterns`	`bool`	No		Find similar usage patterns
`min_centrality`	`float`	No	`0`	Minimum PageRank score. Metrics are fetched internally for filtering; graph_metrics are returned only when include_metrics=true.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	No	`dependency`	Graph view used for traversal relationship defaults, metrics, and centrality ranking; orphan analysis is calculated across all views
`verify_after_edit`	`bool`	No		P2-7 post-edit verify mode: re-query the indexed impact graph for recently edited symbols in one compact multi-root response. Requires targets and/or changed_paths (or target/query). Defaults to shallow incoming dependents; results reflect the indexed graph (may lag live edits). When true, takes precedence over PR/diff impact on the same changed_paths.
`targets`	`list[str]`	No	-	When verify_after_edit=true: symbol names to re-verify (callers/dependents). Merged with target/query if both are supplied.

Best For:

Blast-radius / impact analysis before editing a shared symbol
PR/diff impact via changed_paths or patch
Post-edit verification via verify_after_edit

Not Recommended For:

Simple text or symbol lookups — use text_pattern_search or find_symbol

Code Analysis Tools#

find_symbolStable

Jump to where a function, class, or variable is defined and used. Use when you know the name (e.g. "getCurrentUser") — faster and more precise than Grep, and it spans the whole indexed repo. Optionally returns references and importance metrics.

Parameters:

symbol_nameOptional

Type: str
Description: Symbol name to search for (optional — omit to browse by metrics)

repositoryOptional

Type: str
Description: Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.

scopeOptional

Type: Literal[definitions, references, both]
Default: both
Description: Search scope

limitOptional

Type: int
Default: 15
Description: Maximum results returned in this page

offsetOptional

Type: int
Description: Deprecated compatibility offset. Prefer cursor from pagination.next_cursor.

cursorOptional

Type: str
Description: Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged.

find_similarOptional

Type: bool
Default
Description: Include similar symbol names

include_metricsOptional

Type: bool
Default
Description: Include centrality metrics

metrics_detailOptional

Type: Literal[summary, full]
Default: summary
Description: When include_metrics=true: summary (default) returns decision signals + refactor_risk; full returns the larger curated metric set

path_filterOptional

Type: str
Description: Filter by file path prefix

branchOptional

Type: str
Description: Branch override

symbol_typeOptional

Type: Literal[function, class, variable, method, constant, module, interface, type]
Description: Filter by symbol type

high_impactOptional

Type: bool
Default
Description: Browse architecturally important symbols (omit symbol_name). Default mode is popularity (top PageRank decile minus utility mega-hubs). Set high_impact_mode=risk for articulation/bridge cut-vertices.

high_impact_modeOptional

Type: Literal[popularity, risk]
Default: popularity
Description: When high_impact=true: popularity = top PageRank decile minus utility mega-hubs/modules; risk = articulation points ranked by SMV bridge_count then k_core (structural refactor risk, not hub popularity)

in_cycleOptional

Type: bool
Default
Description: Filter to symbols in dependency cycles

exclude_test_pathsOptional

Type: bool
Default: true
Description: When browsing by graph metrics, exclude tests, fixtures, vendor code, and examples before ranking; named symbol lookup is unchanged

Parameter	Type	Required	Default	Description
`symbol_name`	`str`	No	-	Symbol name to search for (optional — omit to browse by metrics)
`repository`	`str`	No	-	Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.
`scope`	`Literal[definitions, references, both]`	No	`both`	Search scope
`limit`	`int`	No	`15`	Maximum results returned in this page
`offset`	`int`	No	-	Deprecated compatibility offset. Prefer cursor from pagination.next_cursor.
`cursor`	`str`	No	-	Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged.
`find_similar`	`bool`	No		Include similar symbol names
`include_metrics`	`bool`	No		Include centrality metrics
`metrics_detail`	`Literal[summary, full]`	No	`summary`	When include_metrics=true: summary (default) returns decision signals + refactor_risk; full returns the larger curated metric set
`path_filter`	`str`	No	-	Filter by file path prefix
`branch`	`str`	No	-	Branch override
`symbol_type`	`Literal[function, class, variable, method, constant, module, interface, type]`	No	-	Filter by symbol type
`high_impact`	`bool`	No		Browse architecturally important symbols (omit symbol_name). Default mode is popularity (top PageRank decile minus utility mega-hubs). Set high_impact_mode=risk for articulation/bridge cut-vertices.
`high_impact_mode`	`Literal[popularity, risk]`	No	`popularity`	When high_impact=true: popularity = top PageRank decile minus utility mega-hubs/modules; risk = articulation points ranked by SMV bridge_count then k_core (structural refactor risk, not hub popularity)
`in_cycle`	`bool`	No		Filter to symbols in dependency cycles
`exclude_test_paths`	`bool`	No	`true`	When browsing by graph metrics, exclude tests, fixtures, vendor code, and examples before ranking; named symbol lookup is unchanged

Best For:

Pinning a known symbol's definition, references, and graph metrics
Browsing by centrality, high_impact, or in_cycle when symbol_name is omitted

Not Recommended For:

Conceptual or unknown-area queries — use intelligent_search or semantic_search

analyze_dependenciesStable

Alias for blast-radius via dependency_search (dependents/incoming). Prefer dependency_search with analysis_type="dependents" or "impact" for new agents. Keeps the legacy multi-hop impact response shape (graph, connection_summary, optional metrics with refactor_risk). Use graph_view to scope relationship family: dependency (default), type, data_flow, control_flow.

Parameters:

repositoryOptional

Type: str
Description: Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.

targetRequired

Type: str
Description: Symbol name to analyze

depthOptional

Type: Literal[shallow, balanced, deep]
Default: balanced
Description: Analysis depth

limitOptional

Type: int
Default: 10
Description: Maximum results returned in this page

offsetOptional

Type: int
Description: Deprecated compatibility offset. Prefer cursor from pagination.next_cursor.

cursorOptional

Type: str
Description: Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged.

directionOptional

Type: Literal[incoming, outgoing, both]
Default: incoming
Description: Traversal direction

relationship_typesOptional

Type: list[str]
Description: Filter edge types (CALL, IMPORT, INHERITS_FROM, etc.). Always overrides the graph_view-derived default below when supplied.

graph_viewOptional

Type: Literal[dependency, type, data_flow, control_flow]
Default: dependency
Description: Graph view: determines both the default traversal edge types and which view's metrics are used when include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (default), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Only applied as the relationship_types default when relationship_types is not explicitly supplied. Matches dependency_search's existing graph_view parameter name for consistency across tools.

path_filterOptional

Type: str
Description: Restrict target symbol resolution by file path prefix; returned graph relationships may cross outside that path

language_filterOptional

Type: str
Description: Language filter

branchOptional

Type: str
Description: Branch override

per_hop_limitOptional

Type: int
Description: Maximum relationships per hop (1-300)

include_metricsOptional

Type: bool
Default
Description: Include graph metrics in results, each enriched with a derived refactor_risk block ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk is "low" when not an articulation point (in the selected view), "medium" when an articulation point bridging few edges, "high" when bridging many (heuristic threshold, not empirically validated). Omitted per-symbol when no metrics row exists for that symbol/view.

metrics_detailOptional

Type: Literal[summary, full]
Default: summary
Description: When include_metrics=true: summary (default) returns decision signals + refactor_risk; full returns the larger curated metric set

include_edge_metadataOptional

Type: bool
Default
Description: Include raw edge metadata and weights. Disabled by default because extractor metadata can be large; enrichment coverage is reported when enabled.

exclude_test_pathsOptional

Type: bool
Default: true
Description: Default true: exclude test, fixture, vendor, and example paths from returned graph edges. Set false to include them.

include_module_symbolsOptional

Type: bool
Default
Description: Default false: drop edges whose from_name or to_name is the synthetic __module__ symbol. Set true to include module-level edges.

Parameter	Type	Required	Default	Description
`repository`	`str`	No	-	Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.
`target`	`str`	Yes	-	Symbol name to analyze
`depth`	`Literal[shallow, balanced, deep]`	No	`balanced`	Analysis depth
`limit`	`int`	No	`10`	Maximum results returned in this page
`offset`	`int`	No	-	Deprecated compatibility offset. Prefer cursor from pagination.next_cursor.
`cursor`	`str`	No	-	Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged.
`direction`	`Literal[incoming, outgoing, both]`	No	`incoming`	Traversal direction
`relationship_types`	`list[str]`	No	-	Filter edge types (CALL, IMPORT, INHERITS_FROM, etc.). Always overrides the graph_view-derived default below when supplied.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	No	`dependency`	Graph view: determines both the default traversal edge types and which view's metrics are used when include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (default), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Only applied as the relationship_types default when relationship_types is not explicitly supplied. Matches dependency_search's existing graph_view parameter name for consistency across tools.
`path_filter`	`str`	No	-	Restrict target symbol resolution by file path prefix; returned graph relationships may cross outside that path
`language_filter`	`str`	No	-	Language filter
`branch`	`str`	No	-	Branch override
`per_hop_limit`	`int`	No	-	Maximum relationships per hop (1-300)
`include_metrics`	`bool`	No		Include graph metrics in results, each enriched with a derived refactor_risk block ({risk: "low"\|"medium"\|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk is "low" when not an articulation point (in the selected view), "medium" when an articulation point bridging few edges, "high" when bridging many (heuristic threshold, not empirically validated). Omitted per-symbol when no metrics row exists for that symbol/view.
`metrics_detail`	`Literal[summary, full]`	No	`summary`	When include_metrics=true: summary (default) returns decision signals + refactor_risk; full returns the larger curated metric set
`include_edge_metadata`	`bool`	No		Include raw edge metadata and weights. Disabled by default because extractor metadata can be large; enrichment coverage is reported when enabled.
`exclude_test_paths`	`bool`	No	`true`	Default true: exclude test, fixture, vendor, and example paths from returned graph edges. Set false to include them.
`include_module_symbols`	`bool`	No		Default false: drop edges whose from_name or to_name is the synthetic __module__ symbol. Set true to include module-level edges.

Best For:

Legacy callers already wired to its response shape (graph, connection_summary)

Not Recommended For:

New agent loops — prefer dependency_search, which shares the same traversal core

get_task_contextStable

Starting work in an unfamiliar area? Describe the task (e.g. "add SSO support", "fix the billing webhook") and get a bounded one-call bundle of relevant files, code, symbols, and dependencies. Seeded files contribute direct indexed content even when they define no symbols. For more results, continue with the specialized search tool for that layer.

Parameters:

task_descriptionRequired

Type: str
Description: Description of the task you need context for

repositoryOptional

Type: str
Description: Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.

limitOptional

Type: int
Default: 15
Description: Maximum results per layer

scopeOptional

Type: Literal[semantic, symbols, dependencies, all]
Default: all
Description: Which context layers to include

language_filterOptional

Type: str
Description: Language filter

path_filterOptional

Type: str
Description: Filter by file path prefix

branchOptional

Type: str
Description: Branch override

include_related_contextOptional

Type: bool
Default
Description: Include related context from adjacent symbols

seed_symbol_idsOptional

Type: list[str]
Description: Tier-1 explicit seeds: symbol IDs the agent already knows are central to the task (e.g. symbols in files it has open). Ranked ahead of keyword-derived seeds in the dependencies/related_context layers. Additive — omit for today's keyword-only behavior.

seed_file_pathsOptional

Type: list[str]
Description: Tier-1 explicit seeds: indexed file paths the agent has open or just edited. Returns bounded direct file evidence and resolves up to 5 symbols per file for graph context, including symbol-free docs and config. Additive — omit for keyword-only behavior.

Parameter	Type	Required	Default	Description
`task_description`	`str`	Yes	-	Description of the task you need context for
`repository`	`str`	No	-	Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.
`limit`	`int`	No	`15`	Maximum results per layer
`scope`	`Literal[semantic, symbols, dependencies, all]`	No	`all`	Which context layers to include
`language_filter`	`str`	No	-	Language filter
`path_filter`	`str`	No	-	Filter by file path prefix
`branch`	`str`	No	-	Branch override
`include_related_context`	`bool`	No		Include related context from adjacent symbols
`seed_symbol_ids`	`list[str]`	No	-	Tier-1 explicit seeds: symbol IDs the agent already knows are central to the task (e.g. symbols in files it has open). Ranked ahead of keyword-derived seeds in the dependencies/related_context layers. Additive — omit for today's keyword-only behavior.
`seed_file_paths`	`list[str]`	No	-	Tier-1 explicit seeds: indexed file paths the agent has open or just edited. Returns bounded direct file evidence and resolves up to 5 symbols per file for graph context, including symbol-free docs and config. Additive — omit for keyword-only behavior.

Best For:

Task-aware context blending seeded files with semantic, symbol, and dependency layers

Not Recommended For:

Single-tool lookups where a more specific tool already answers the question

get_fileStable

Read a file from the indexed repo by path. Prefer the local Read tool for files on disk — use this for cross-repo or remote lookups where the file isn't in your working tree. Supports an optional line range; continue a token-truncated response from metadata.next_line_start.

Parameters:

file_pathRequired

Type: str
Description: File path relative to repository root

repositoryOptional

Type: str
Description: Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.

line_startOptional

Type: int
Description: Start line (1-indexed)

line_endOptional

Type: int
Description: End line (1-indexed, inclusive; must be at or after line_start)

branchOptional

Type: str
Description: Branch override

max_tokensOptional

Type: int
Default: 5000
Description: Maximum tokens to return

include_metadataOptional

Type: bool
Default: true
Description: Include file metadata in response

Parameter	Type	Required	Default	Description
`file_path`	`str`	Yes	-	File path relative to repository root
`repository`	`str`	No	-	Repository as owner/repo[:branch]. Optional — omit to use the request-scoped client default (when supplied) or the sole accessible repository; pass explicitly only to target a different indexed repo. The response shows which repository was used.
`line_start`	`int`	No	-	Start line (1-indexed)
`line_end`	`int`	No	-	End line (1-indexed, inclusive; must be at or after line_start)
`branch`	`str`	No	-	Branch override
`max_tokens`	`int`	No	`5000`	Maximum tokens to return
`include_metadata`	`bool`	No	`true`	Include file metadata in response

Best For:

Remote or indexed file snapshots (line ranges, token limits)

Not Recommended For:

A path already on local disk — use the local Read tool

System & Utility Tools#

repository_contextStable

List the repositories you can search, or get identity info on one (namespace/branch, indexed_commit_sha / index freshness). Call with action:"list" once to learn the exact repo slug the search tools accept. (If your key has a single repo, the search tools default to it — you can skip this.) Namespace-wide file/blob/edge counts are opt-in via include_statistics=true.

Parameters:

actionRequired

Type: Literal[list, info]
Description: Action: list available repos or get repo info

repositoryOptional

Type: str
Description: Repository in owner/repo or owner/repo:branch format (required for info)

branchOptional

Type: str
Description: Branch override

patternOptional

Type: str
Description: Filter repository list by pattern

include_statisticsOptional

Type: bool
Default
Description: Opt-in: include namespace-wide indexed-data counts (file/blob/edge). Default false — repository identity does not require this slower aggregate.

limitOptional

Type: int
Default: 20
Description: Maximum results returned in this page

offsetOptional

Type: int
Description: Deprecated compatibility offset. Prefer cursor from pagination.next_cursor.

cursorOptional

Type: str
Description: Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged.

Parameter	Type	Required	Default	Description
`action`	`Literal[list, info]`	Yes	-	Action: list available repos or get repo info
`repository`	`str`	No	-	Repository in owner/repo or owner/repo:branch format (required for info)
`branch`	`str`	No	-	Branch override
`pattern`	`str`	No	-	Filter repository list by pattern
`include_statistics`	`bool`	No		Opt-in: include namespace-wide indexed-data counts (file/blob/edge). Default false — repository identity does not require this slower aggregate.
`limit`	`int`	No	`20`	Maximum results returned in this page
`offset`	`int`	No	-	Deprecated compatibility offset. Prefer cursor from pagination.next_cursor.
`cursor`	`str`	No	-	Opaque cursor from pagination.next_cursor. Pass it unchanged and keep the query and filters unchanged.

Best For:

Listing accessible repositories
Resolving repository identity, branch, and HEAD-vs-index freshness

Not Recommended For:

Namespace-wide statistics by default — pass include_statistics=true explicitly, since it can be slower than resolution

ask_maguyvaStable

Maguyva help and feedback. Primary: get tool guidance, or submit a bug report / feature request stored for Maguyva's maintainers. Never include secrets or sensitive personal data in feedback. The evaluate operation remains for back-compat only — prefer local compute or host tools for math/hash/string work.

Parameters:

operationRequired

Type: Literal[guidance, report_bug, request_feature, evaluate]
Description: Primary: guidance, report_bug, request_feature. Legacy/compat only: evaluate (deterministic expression engine; not part of the primary agent workflow).

queryOptional

Type: str
Description: Guidance topic (e.g. tool_selection, semantic_search). For legacy evaluate only: expression string.

descriptionOptional

Type: str
Description: Required for report_bug and request_feature. Free-form feedback for Maguyva's maintainers. Never include secrets or sensitive personal data.

related_toolOptional

Type: Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]
Description: Optional Maguyva tool most closely related to the feedback

Parameter	Type	Required	Default	Description
`operation`	`Literal[guidance, report_bug, request_feature, evaluate]`	Yes	-	Primary: guidance, report_bug, request_feature. Legacy/compat only: evaluate (deterministic expression engine; not part of the primary agent workflow).
`query`	`str`	No	-	Guidance topic (e.g. tool_selection, semantic_search). For legacy evaluate only: expression string.
`description`	`str`	No	-	Required for report_bug and request_feature. Free-form feedback for Maguyva's maintainers. Never include secrets or sensitive personal data.
`related_tool`	`Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]`	No	-	Optional Maguyva tool most closely related to the feedback

Best For:

Tool guidance (operation="guidance")
Durable bug reports and feature requests for Maguyva's maintainers

Not Recommended For:

Math/hash/string computation — the evaluate operation is legacy/back-compat only; prefer local host compute

Best Practices#

Use Explicit Overrides Deliberately: Omit the repository when your MCP client supplies a request default or the key can access exactly one repository; otherwise pass it explicitly.
Choose the Right Search Mode: Use intelligent_search with mode="auto" for most cases. Specify a mode when you know exactly what you need.
Leverage Language Filters: Use language_filter to narrow results and improve performance.
GraphRAG Boosting: GraphRAG importance boosting is off by default for semantic search (boost_by_importance=false) to keep ranking agent-safe. Pass boost_by_importance=true to enable centrality-aware re-ranking for architecture tours.
Repository Matching Is Case-Insensitive, Not Fuzzy: repository_context matches repository names case-insensitively — it does not correct typos. Check metadata.resolution_reason on the info action ("exact" vs "corrected") to see how a name resolved.
Combine Tools: Use multiple API methods together for comprehensive analysis.
Handle Large Results: Use limit and tool-specific paging controls (for example line_start/line_end in get_file).
Use ask_maguyva for Tool Guidance: The ask_maguyva evaluate operation (hash, base64, JSON, math) is legacy / back-compat only. Call ask_maguyva with operation="guidance" and query="tool_selection" instead for the local-tool-wins matrix and a full tool-by-tool cheat sheet.
Verify Impact Before and After Editing: Before editing a shared symbol, call dependency_search with analysis_type="impact" (or pass changed_paths for PR/diff impact) to see its blast radius. After editing, set verify_after_edit=true with targets and/or changed_paths for a compact re-check of the same symbols.

Performance Characteristics#

Operation	Performance notes
Semantic search	Sub-second, but includes a live embedding API call every time (not cached) — expect extra latency on top of the vector query
Text search	Sub-second for exact/regex; fuzzy content search paginates client-side, so deep offsets cost more — narrow with path_filter/language_filter
Structural search	AST-indexed — cost scales with result volume, not repository size
Dependency search	Cost scales with depth — prefer depth="shallow" unless you need multi-hop context; per_hop_limit bounds fan-out
File retrieval	Near-instant for a single file — page large files with line_start/line_end or max_tokens instead of one large pull
Repository context	Namespace resolution is cached per request only, not across calls — every tool invocation re-resolves
ask_maguyva (guidance / evaluate)	Near-instant — runs in-Worker with no database call

Error Handling#

All API methods return a structured envelope:

status: String — "success" or "error". Degraded-match and freshness signals live in nested fields such as metadata.resolution_reason on repository_context or metadata.index_freshness.status.
tool: Name of the tool that generated the response
data: Result payload when successful (structure varies by tool)
error: Structured error object when status is "error" — includes type, message, suggestions, and recovery_actions
metadata: Additional information about the operation (routing, caching, parameter adjustments)
pagination: Present on list responses — includes has_more and next_cursor

Always check the status field before processing results — it is only ever "success" or "error". For degraded-match or freshness signals, read the nested field instead: metadata.resolution_reason on repository_context, or metadata.index_freshness.status (known/partial/unknown/unavailable).

Getting Started#

Configure MCP Client: Point your MCP client to the Maguyva server endpoint
Confirm Repository Access: Use repository_context with list or info to inspect repositories available to the API key
Start Searching: Begin with intelligent_search and explore specialized tools as needed
Combine Tools: Use multiple tools together for comprehensive code analysis

For detailed integration instructions, see the installation guide.