Check whether Ollama is running and the configured embedding/chat model is installed.

Read-only: yes. No side effects. Call before smart_search, semantic_search, or explain_symbol (when on-demand fallback is expected — pre-computed analysis returns instantly without Ollama).

Returns: dict: {ollama_enabled (bool), status (str — "ok"|"disabled"|"error"|"model_missing"), ollama_running (bool), ollama_url (str), configured_model (str), num_ctx (int), installed_models (list[str]), configured_embed_model (str), embedding_installed (bool), message (str, on error/disabled), available_code_models (list[str], when model missing), debug_log (str, optional — only when debug logging is enabled)}

Return metadata about the most recently indexed build configuration.

Read-only: yes. Call at session start to check if the index exists, how many symbols it contains, and whether it is stale (needs re-index).

stale is True when any of: (1) compile_commands.json changed since the last index, (2) source files were modified after indexing, or (3) the index schema is older than the current code expects (schema_version < current_schema). Cases (1) and (2) are handled transparently by auto-reindex on query; case (3) requires a full fw-context index — remind the user.

When modified_files_count > 0, a background fw-context index subprocess is spawned automatically (non-blocking, at most one at a time). Queries continue to be served from the existing index while the new one is being built. reindex_progress contains the last log line from the reindex subprocess when bg_reindex_running is True.

Returns: dict: {config_hash, project_id, project_root, build_system, compile_commands, indexed_at (ISO timestamp), symbol_count, file_count, reference_count, modified_files_count (int), analyzed_symbols (int), unanalyzed_symbols (int — definition symbols still needing LLM analysis), analysis_model (str or None), bg_reindex_running (bool), reindex_progress (str or None — last log line when reindex is running), schema_version (int — DB schema version), current_schema (int — code expects), stale (bool — any staleness condition)}

List all indexed firmware projects with their statistics.

Read-only. No side effects. Use at session start to discover available projects; use get_active_build for details on the currently active project.

Returns: list of dicts, each with: project_id, name, root_path, build_system, symbol_count, file_count, indexed_at, schema_version, current_schema, stale (bool), db (path to SQLite database file).

Re-parse a single source file with libclang and update its symbols in the index.

Not read-only — uses the exact compiler flags from compile_commands.json. The file must be listed in compile_commands.json (headers are re-indexed via the translation unit that includes them). Use after editing a file to keep the index current without a full rebuild.

Also regenerates LLM analysis and method override relationships for affected symbols when those features are enabled in config.

Args: file_path: Path to source file to re-parse. Must be in compile_commands.json. project_root: Project root directory. Auto-detected if omitted.

Returns: dict: {file, translation_units, symbols_updated, elapsed_s, analysis_updated (if LLM enabled), or error}.

Re-parse a single source file with libclang and update its symbols in the index.

Shared implementation used by reindex_file (public tool, full analysis) and _auto_reindex_stale (background fast path, no LLM). Prefer reindex_file for interactive use; call this directly only when you need to control with_analysis explicitly.

Requires an existing index (fw-context index must have been run first). The file must appear in compile_commands.json — header-only files are re-indexed via the .cpp translation unit that includes them.

Args: file_path: Absolute or project-relative path to the source file to re-parse. Must have a matching entry in compile_commands.json. project_root: Project root directory. Auto-detected from cwd if omitted. with_analysis: When True (default), also regenerates LLM symbol analysis, file-level summaries, and method override relationships — slower but produces a fully up-to-date index. Set to False for a fast symbol-only update (used by background auto-reindex).

Returns: On success — dict with keys: file (str): Resolved absolute path to the re-indexed file. translation_units (int): Number of TUs that include this file. symbols_updated (int): Number of symbols written/updated. elapsed_s (float): Parse + store time in seconds. analysis_updated (int, optional): Symbol count with fresh LLM analysis (only present when LLM analysis is enabled and with_analysis=True). analysis_warning (str, optional): Reason LLM analysis was skipped. overrides_warning (str, optional): Reason override analysis was skipped. warning (str, optional): Header re-indexed via a single TU — other TUs including this header may still have stale symbols; run fw-context index for full accuracy. On error — dict with key: error (str): Human-readable reason (no index found, file not found, file not in compile_commands.json, no build config indexed).

Delete the entire symbol index for a project.

Not read-only — permanently deletes the SQLite database and WAL files. Call with confirm=False first (dry-run) to see what would be deleted. Re-index with fw-context index afterwards.

Handles corrupt databases gracefully — you can delete a corrupt index without needing to open it first.

Args: project_root: Project root directory. Auto-detected if omitted. confirm: Must be True to execute. Call without first as dry-run.

Returns: dict: {project_root, db, project_id, action: "dry_run"|"deleted", message, symbol_count, indexed_at (dry-run)}.

Look up a symbol by name — exact or prefix matching.

Returns all declarations and definitions matching the name across the entire indexed codebase. Prefer this over search_code when you know the exact symbol name or a prefix of it (uart_ finds all UART symbols). Use search_code for keyword/concept search when you don't know the name.

Read-only: yes. May auto-reindex stale files (non-blocking).

Args: name: Symbol name (exact match) or prefix (set exact=False). E.g. 'uart_init' finds the exact function; 'uart_' finds all symbols starting with 'uart_'. project_root: Project directory. Auto-detected if omitted. exact: True = exact name match, False = prefix LIKE match (default). limit: Maximum results (default 50).

Returns: list[dict]: Symbols with name, qualified_name, kind, file, line, signature, docstring, is_definition, is_template, is_virtual, is_pure_virtual fields. Enum constants include enum_value with the integer value. May also include template_usr, parent_usr, summary, inputs, outputs when available. When no results found, may include _did_you_mean with suggested symbol names. Empty list if not found.

Full-text search over indexed C/C++ symbols (functions, classes, methods, enums, etc.).

Read-only. No side effects. Use when looking for symbols by topic or keyword rather than exact name. Prefer lookup_symbol when you already know the symbol name.

FTS5 syntax:

• init* matches init, init_uart, initialize (trailing wildcard)

• "spi init" matches the exact phrase "spi init"

• Do NOT use underscore in queries — modem_init is split into modem AND init. Use modem init instead.

Progressive relaxation: when the initial FTS5 search returns nothing, the tool automatically broadens the search in up to five steps:

1. FTS5 with kind filter — the original query with the user-provided kind constraint.

2. FTS5 without kind filter — drops the kind constraint (users often guess the wrong kind for a symbol).

3. name_tokens substring match — searches the pre-computed CamelCase/ snake_case token column (e.g. BuildType is indexed as "build type"). Requires at least N‑1 of N query terms to match.

4. Single-term docstring LIKE — when only one query term was given and the token-based steps found nothing, does a raw LIKE over the docstring column to catch terms the FTS5 tokeniser may have missed.

5. Individual term FTS5 — searches each query word separately and merges the results.

Results from fallback steps carry _fallback indicating which method succeeded ("fts5", "name_tokens_like", "docstring_like", "individual_terms").

Kind filter values: function, method, constructor, destructor, class, struct, enum, enum_constant, typedef, variable, field, namespace.

Each result may include summary, inputs, outputs when LLM analysis has been generated (fw-context index --analyze). These provide structured descriptions: what the symbol does, what parameters/data it receives, and what it returns/produces.

Args: query: Search term(s) with FTS5 syntax. Keep queries short — 1–3 words. project_root: Project root directory. Auto-detected from CWD if omitted. kind: Optional filter to return only symbols of this kind. limit: Maximum number of results (default 20, max 100).

Returns: list of dicts, each with: name, qualified_name, kind, file, line, is_definition, signature, docstring, is_template, is_virtual, is_pure_virtual. Enum constants include enum_value with the integer value. May also include template_usr, parent_usr, summary, inputs, outputs when available. Fallback results include _fallback with the method name.

Read-only. Semantic search using pre-computed symbol embeddings.

Finds symbols conceptually related to a natural-language query, even when the query words don't appear literally in the code. Uses cosine similarity over 1024-dimensional embeddings generated during fw-context index.

When to prefer over search_code: When you're describing a concept rather than searching for a known keyword. Examples:

• "parcel locker state" finds door-state and shipment methods even though "parcel" and "locker" don't appear in their names.

• "cell modem" finds _socket_t and ModemMsg* classes.

• "delivery box" finds set_shipment and get_zrtdata.

• "power consumption" finds get_load_power and INA260 class.

When to prefer search_code instead: When you know the exact keyword or symbol name ("fram_write", "cbor encode"). FTS5 is faster and more precise for lexical matches.

Threshold guidance (mxbai-embed-large model):

• 0.50 — exploratory: more results, lower precision

• 0.55 — balanced (default, ~1000 results)

• 0.60 — precise: ~175 avg, high precision

• 0.65 — strict: few results, may miss relevant symbols

Source-aware ranking: Project code (src/) boosted 1.2×, library code (lib/) 1.1×, vendored SDK (mbed-os/) 0.85×.

Requires Ollama with an embedding model (mxbai-embed-large). Falls back to search_code with a warning if Ollama is unavailable.

Args: query: Natural language description of what you're looking for. Be specific — 5–15 words works best. project_root: Project root. Auto-detected if omitted. threshold: Minimum cosine similarity (0.0-1.0). Default 0.60. limit: Maximum number of results (default 20, max 100).

Returns: list of dicts, each with: name, qualified_name, kind, file, line, is_definition, signature, docstring, plus _similarity (cosine similarity score) and _method ("embedding" or "search_code_fallback").

Natural-language search: Ollama generates FTS5 keywords, then searches the index.

Read-only. No side effects. Slow (10-30 s) — delegates to the full SMART_SEARCH pipeline (8 phases: translate → rough_search → llm_query → fts5_search → refine → embedding → deduplicate → format).

Multi-phase approach:

1. Translate non-English queries

2. Rough search to gather sample symbols for naming conventions

3. Ollama sees those samples + query and generates FTS5 terms

4. FTS5 search with generated terms

5. Refine: Ollama checks results and course-corrects query terms

6. Semantic embedding search (cosine similarity re-rank)

7. Deduplicate, score, and format results

When to prefer over search_code: When you don't know the exact keywords and want to describe what you're looking for ("how does the modem connect?", "handle BLE pairing failure").

Fallback: When Ollama is unavailable, falls back to direct FTS5 search with word-split terms from the query.

Args: query: Natural language description of what you're looking for. Be specific — 5–15 words works best. project_root: Project root directory. Auto-detected from CWD if omitted. limit: Maximum number of results (default 20, max 100).

Returns: list of dicts with metadata entries (_generated_queries, _rough_queries, _translated_from) followed by symbol results with name, qualified_name, kind, file, line, is_definition, signature, docstring.

Read-only. Find all transitive callers — who calls name, directly or indirectly.

Use for impact analysis: "if I change this function, how far does the ripple go?" Returns callers at depth 1 (direct), depth 2 (callers of callers), up to max_depth (default 5). Results are deduplicated — each caller appears once at its shortest distance to the target.

For a flat, single-level caller list use find_callers (faster). Requires the reference index (fw-context index — refs on by default). BFS from the target outward; performance scales with call-graph fan-out.

Read-only. Find call paths between two functions via BFS in the call graph.

Use to answer "how does A reach B?" — e.g. tracing how a high-level event handler eventually calls a low-level driver. Returns up to 5 shortest paths, each with depth (edge count) and chain (e.g. "main → app_run → modem_init").

For one-sided exploration use find_all_callers_recursive (who reaches this?) or find_callees_recursive (what does this reach?). Requires both symbols to be in the index and refs enabled (fw-context index — refs on by default).

Read-only. Find all transitive callees — what name calls, directly or indirectly.

Use for dependency analysis: "what does this function depend on to do its job?" Returns callees at depth 1 (direct), depth 2 (callees of callees), up to max_depth (default 5). Results are deduplicated by shortest distance.

For direct callees only, get_symbol_context gives a faster flat list along with the function body and callers. Requires the reference index (fw-context index — refs on by default).

Read-only. Find call sites of a function/method — who calls name (direct + indirect via function pointers).

Use when you need a quick, flat list of immediate callers. For the full transitive call tree (who calls this indirectly through other functions), use find_all_callers_recursive. For all references including reads and member accesses, use find_references. For a path between two specific symbols, use find_call_path.

Requires the reference index (fw-context index — refs are on by default). Only direct call sites are returned; callers more than one hop away are not included.

Indirect edges (ref_kind: "indirect") are detected when a function pointer references a function through:

• Call arguments: callback(&Class::method, this), EventQueue::call_every(ms, obj, &handler)

• Assignments: driver.onData = &handleData, global_cb = &handler

• Variable initializers: static void (*fp)(int) = &handler

• Struct/array init lists: {.on_data = &handler}, {&fn_a, &fn_b}

Args: name: Symbol name to find callers of. Uses the same three-tier resolution as find_references (exact name, exact qualified, suffix LIKE). project_root: Project root directory. Auto-detected if omitted. limit: Maximum results (default 50).

Returns: list of dicts, each with: file, line, ref_kind ("call" or "indirect"), caller (enclosing function name), caller_kind ("function", "method", …).

Read-only. Find functions/methods that are defined but never called.

Returns two categories of results, each with a status field:

• "dead" — no references at all (neither calls nor function pointer assignments). Likely unused.

• "possibly_dead" — the function is assigned to a function pointer (Phase 1 ref_kind="indirect") but no call site through that pointer was resolved (Phase 3). This means the function MIGHT be called through unindexed code or a type-erased API. LLM should treat this as uncertain, not as confirmed dead code. Verify each hit with find_indirect_targets before deleting.

Expect additional false positives from constructors called via factories, ISRs, virtual method overrides, and weak-aliased symbols. Always verify before deleting.

By default, SDK/vendor paths are auto-excluded based on the build system (mbed-os/ for Mbed OS, .pio/ for PlatformIO, zephyr/ + build/

• modules/ for Zephyr), and project config exclude_paths are applied. Use project_only=False to see all results including vendor code. Requires the reference index.

Read-only. Find the most-called functions ranked by caller count.

Use for high-level impact assessment: changing a hotspot affects many call sites. The result tells you which functions carry the most "architectural weight" — good targets for refactoring, optimization, or extra testing.

By default, SDK/vendor paths are auto-excluded. Use project_only=False to see all results including vendor code.

Requires the reference index (fw-context index — refs on by default). For the callers of a specific hotspot, follow up with find_callers or find_all_callers_recursive.

Find indirect call sites where a function pointer field or variable is invoked.

Returns locations where a function pointer is called through a field access (driver.onData(buf, len)) or variable dereference (stored_callback(42)).

Read-only. No side effects. Use this to answer "where is this function pointer invoked?" as opposed to find_callers which answers "who calls this function?" and find_references which answers "where is this symbol read or assigned?"

For the reverse query — which functions are assigned to a given field or parameter — use find_indirect_targets.

Requires the reference index (fw-context index — refs on by default).

Args: name: Name of the function pointer field or variable. E.g. "onData" finds every call through a field named onData. Uses three-tier resolution: exact name, exact qualified, suffix LIKE. project_root: Project root directory. Auto-detected if omitted. limit: Maximum results (default 50, max 200).

Returns: list of dicts, each with: file, line, expr_text (the callee expression, e.g. "driver.onData"), target_usr, target_name, fn_ptr_type (the function pointer type signature), caller (enclosing function name), caller_kind.

Read-only. Find functions assigned to a function pointer field or variable.

Links assignment sites (driver.onData = &handler) to call sites (driver.onData(buf, len)) via the field's USR.

Returns each function that could be invoked through the named function pointer, showing both the assignment location and the call site(s). When a function is assigned but no call site is found, call_file and call_line are null — the assignment exists but the invocation may be in unindexed code.

For the reverse query — where is this field or parameter called — use find_indirect_call_sites.

Read-only. No side effects. Requires the reference index (fw-context index — refs on by default).

Args: name: Name of the function pointer field, variable, or parameter. E.g. "onData" finds every function assigned to a field named onData. Uses three-tier resolution. project_root: Project root directory. Auto-detected if omitted. limit: Maximum results (default 50, max 200).

Returns: list of dicts, each with: rhs_name (assigned function), rhs_qname, fn_ptr_type, method (assignment/call_arg/var_init/ init_list), assign_file, assign_line, assign_caller, call_file, call_line, call_expr_text.

Find all references to a symbol — calls, reads, and member accesses.

Read-only. No side effects. Returns every reference in the indexed codebase, including call sites, variable reads, struct member accesses, and indirect function-pointer references. Requires the reference index (fw-context index — refs on by default).

For direct callers only use find_callers. For transitive callers use find_all_callers_recursive. For call paths between two symbols use find_call_path.

Args: name: Symbol name to find all references of. project_root: Project root directory. Auto-detected if omitted. limit: Maximum results (default 50, max 200).

Returns: list of dicts, each with: file, line, ref_kind, caller, caller_kind. ref_kind is one of: "call", "ref", "member", "indirect" (function-pointer reference in arguments, assignments, initializers, or init lists), "template_ref".

Read-only. Find wrapper classes that call methods of a driver class.

Returns wrapper methods grouped by wrapper class, showing which driver methods each wrapper calls. Useful for understanding the adapter/wrapper architecture (e.g. UART wraps UART_DRIVER).

Read-only. Trace how data of a given type flows to a target function.

Finds functions whose signature mentions type_name, then looks for call paths from those functions to to_symbol. Returns a data flow map — useful for understanding how a data structure travels through the system to its destination.

Works best for synchronous driver stacks (e.g. sensor read → I2C write). Cannot follow async flows (message queues, interrupts, RS485 callbacks). For exact call-graph queries use the find_* family; verify specific paths with find_call_path.

Explain what a C/C++ symbol does in plain English.

Read-only. No side effects — uses pre-computed LLM analysis when available (instant, generated during fw-context index --analyze), falls back to calling Ollama on-demand. Returns the symbol's purpose, inputs, outputs, and side effects.

For raw source code use get_source. For symbol metadata without explanation use lookup_symbol. For body + callers + callees use get_symbol_context.

Args: name: Symbol name to explain. E.g. uart_init, ModemMsg::send. project_root: Project root directory. Auto-detected if omitted. context_lines: Lines of source context around the symbol definition (default 40, max 200). Only used when no pre-computed analysis exists.

Returns: dict: {name, kind, file, line, signature, explanation, llm_analysis (if pre-computed)}, plus source/explain_prompt on fallback.

Return the file-level LLM analysis summary for a source file.

Read-only: yes. No side effects. Returns the pre-computed 2-3 sentence summary describing what the file is responsible for. Generated during fw-context index when [llm] analyze_symbols is enabled.

Returns file, summary, model, analyzed_at on success, or an error message if no analysis exists yet.

Return all symbols in a file grouped by kind — fast structural overview.

Like a table of contents before reading a chapter. Pass a path relative to the project root (src/main.cpp) or just the filename (main.cpp). Returns symbols keyed by kind (function, method, class, struct, enum, ...). Each kind has count (total) and items (first N, default 30). Set max_per_kind=0 for unlimited, signatures=true for full sigs.

Enum constants (enum_constant) are grouped into subgroups by parent enum. Each subgroup has name, count, and constants (list of {name, qualified_name, line, enum_value}). The subgroup count reflects the real total even when max_per_kind limits the constants list.

Read-only: yes. No side effects. Use before reading a large file to orient yourself — see what functions, classes, and enums it defines.

Args: file_path: Path relative to project root, or just the filename. project_root: Project directory. Auto-detected if omitted. signatures: Include full function signatures. Default: False. max_per_kind: Max items per kind group (default 30, 0 = unlimited).

Returns: dict: {file, total_symbols, symbols: {kind: {count, items[], subgroups?[]}}, file_summary (str, optional — file-level LLM analysis summary when available)}

Read-only. Preferred way to read a function/method/enum body — uses libclang for exact extents instead of guessing from line numbers. No LLM, fast.

For enums, includes a constants array listing all member constants with their names and integer values.

For rich context (who calls this, what does it call) use get_symbol_context instead. For the full file, use a normal file read.

Returns: dict: {name, qualified_name, kind, file, line, signature, is_definition, is_template, is_virtual, is_pure_virtual, source (str — the function/enum body, truncated at 8000 chars), warning (str, optional — when source file cannot be read)}. May also include template_usr, parent_usr, enum_value, constants (list for enums) when applicable.

Read-only. Rich one-shot context for a symbol: body, signature, all direct callers and callees. Answers "what does this do and how does it fit in the system?" in a single response.

For body-only use get_source (faster). For transitive call-graph exploration use find_all_callers_recursive or find_callees_recursive.

By default, SDK/vendor callers and callees are filtered out for clarity. Use project_only=False to see all callers/callees.

Returns dict with: name, qualified_name, kind, file, line, signature, is_definition, callers (list), callees (list), source (body text), indirect_call_sites (list, for field/variable symbols — where the function pointer is actually invoked). For field and variable symbols that have function pointer type, also includes resolution: {assignments_found, call_sites_found, resolved, note} indicating whether assignments and call sites are linked (Phase 3). resolved=False with a note when parts are missing — LLM can detect uncertainty. For enums also returns constants and enum_value. When LLM analysis has been generated (fw-context index --analyze), includes llm_analysis: {summary, inputs, outputs, model, analyzed_at} with a structured description of the symbol's purpose, parameters, and return values/side effects.

Read-only. Return all methods, fields, and nested types of a class/struct.

Members are grouped by kind (method, constructor, destructor, field, enum, typedef, class, struct). Each member includes its signature, virtual flags, and source line. Works for C structs too — they just won't have methods.

Returns: dict: {name, qualified_name, kind, file, line, members: {kind: [...]}, member_count}

Read-only. Return the C++ inheritance chain for a class or struct.

Shows direct base classes (what this inherits from) and direct derived classes (what inherits from this), along with access level and virtual flag for each edge.

When transitive=True, walks the full hierarchy up to all ancestors and down to all descendants (bounded by max_depth). Uses BFS with cycle detection to handle diamond inheritance.

Returns: dict: { name, qualified_name, kind, file, line, bases: [{name, usr, access, is_virtual, file}], derived: [{name, usr, access, is_virtual, file}], all_bases: [...] (when transitive=True, ancestors sorted by depth), all_derived: [...] (when transitive=True, descendants sorted by depth) }

Read-only. Return virtual method override information.

Shows what base-class method this method overrides, and what derived-class methods override this one. Built from the overrides table which is populated during fw-context index via post-processing of the inheritance graph and virtual method signatures.

For class-level inheritance, use get_inheritance_chain. For symbol details, use get_symbol_context.

Returns: dict: { name, qualified_name, kind, file, line, signature, overrides: [{usr, name, qualified_name, kind, file, line}], overridden_by: [{usr, name, qualified_name, kind, file, line}] }

Read-only. Find all template instantiations for a given class or function template.

Returns concrete instantiations of the template — each with its full type signature (e.g. Callback<void(int)>). The template declaration itself is also returned as the first result when found.

Uses the template_usr column populated during indexing via libclang's cursor.specialized_template.

Returns: list[dict] with one element wrapping the template declaration: {name, qualified_name, kind, file, line, is_definition, signature, instances (list of dicts, each with name, qualified_name, kind, file, line, signature, is_definition), instance_count (int)}