smart_search
Search code by meaning: describe what you need in plain language, and it translates your query into code-search terms, returning matching C/C++ symbols and definitions from the indexed project.
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).
This tool names no build. It takes neither variant nor
image, and it answers for the build that get_active_build
reports as the active one. On a project that holds several builds,
use search_code or search_bodies to ask about one named build.
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.
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 (default 20). The pipeline holds it between 5 and 100: a smaller number becomes 5, because the re-rank steps need a set to choose from.
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.
When the LLM stalls, the tool gives the FTS5 results that it has.
The leading dict then holds ``_partial: True``, a ``warning`` with
the timeout, and a ``hint``. The result is incomplete: make the
query more specific, or increase the LLM timeout.
When the index is stale, a leading dict holds a ``warning`` and a
``hint`` to reindex.
No match gives ``[]``. One dict with ``error`` means the query
failed — check that key first.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results (default 20, max 100). | |
| query | Yes | Natural language description, 5-15 words. E.g. 'how does the modem connect?' or 'handle BLE pairing failure'. | |
| 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. | |
| 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 |