smart_search
Find C/C++ symbols by describing what you need in natural language when exact keywords are unknown; searches a libclang index by meaning using LLM-generated FTS5 terms.
Instructions
Natural-language search: an LLM generates FTS5 keywords, then searches the libclang index. Finds concepts by meaning rather than exact text match. Prefer this 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").
Read-only: yes. Slow (10-30 s) — delegates to the full
SMART_SEARCH pipeline (translate → rough_search → llm_query →
fts5_search → refine → embedding → adaptive_fusion → deduplicate →
expand_context → format).
Multi-phase approach:
Translate non-English queries
Rough search to gather sample symbols for naming conventions
LLM sees those samples + query and generates FTS5 terms
FTS5 search with generated terms
Refine: LLM checks results and course-corrects query terms
Semantic embedding search (cosine similarity re-rank)
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 LLM is unavailable, falls back to direct FTS5 search
with word-split terms from the query. When the LLM call or the
embedding step fails, a metadata dict gives the reason in warning
or detail.
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. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. limit: Maximum number of results on one page (default 20, max 100). The search itself always ranks up to 100 symbols. offset: Skip this many results of the previous search of the same query. 0, the default, is a NEW search. A page with an offset comes out of the stored answer of the last search; when the last search was of another query (or another project, or a build that a reindex changed), the tool searches again first. An index run that keeps the build keeps the stored answer. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application or the bootloader. Give it when the build has an image name.
Returns:
list of dicts with metadata entries (_generated_queries, _rough_queries,
_translated_from + _translated_to), then the page notice
{total, offset, shown, more, hint}, followed by symbol results with
name, qualified_name, kind, file, line, is_definition, signature,
docstring. total counts the symbols of the answer (at most
100). A page after the last symbol gives one info dict that
names the total. A symbol also holds summary, inputs and
outputs when fw-context index --analyze wrote them. A model
wrote that text, and the code did not: never quote it as a fact.
When the pipeline passes the LLM timeout (``[llm] timeout`` of the
project), a leading dict holds ``_partial: True``, a ``warning``
with the timeout, and a ``hint``. The symbols that follow are the
ones that the steps before the timeout found, without the later
re-rank steps; there can be none. This answer has no page notice
and is not stored, thus a next page searches again. Make the query
more specific, or increase the LLM timeout.
When the index of the build of the query is not current (for
example, compile_commands.json changed after the last index run),
a leading dict holds ``warning`` and ``index_state``. The answer
then comes from the last index run.
No match gives the metadata entries and a dict with ``info``. One
dict with ``error`` means the query failed — check that key first.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image | No | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. | |
| limit | No | Maximum results on one page (default 20). Held between 1 and 100. | |
| query | Yes | Natural language description, 5-15 words. E.g. 'how does the modem connect?' or 'handle BLE pairing failure'. | |
| offset | No | Skip this many results of the previous search of this query. 0 (the default) is a new search. | |
| project | No | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. | |
| variant | No | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build for you. One query answers for ONE build. | |
| project_root | No | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |