smart_search
Find C and C++ symbols by describing what you need in natural language. Uses AI to translate queries into search terms and refine results.
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. No side effects. Slow (10-30 s) — delegates to the full
SMART_SEARCH pipeline (translate → rough_search → llm_query →
fts5_search → refine → embedding → rrf_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.
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.
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_root | No | Project root. Auto-detected if omitted. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |