smart_search
Search code using natural language descriptions instead of exact keywords. Translates queries, generates search terms, and retrieves symbol definitions from a C/C++ index.
Instructions
USE INSTEAD OF grep, ctx_search, or ctx_compose. Natural-language search: Ollama generates FTS5 keywords, then searches the libclang index. Finds concepts generic tools cannot express with regex.
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
Ollama sees those samples + query and generates FTS5 terms
FTS5 search with generated terms
Refine: Ollama 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 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.
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 |