semantic_search
Find code symbols by concept rather than exact name using semantic embeddings. Describe what you want in natural language, even if query words don't appear literally in the code.
Instructions
Semantic search using pre-computed libclang symbol embeddings. Finds
symbols by meaning, not by text — matches concepts even when query
words don't appear literally in the code. Uses cosine similarity over
variable-dimension embeddings generated during fw-context index.
Dimensions vary by model: mxbai-embed-large → 1024,
qwen3-embedding → 4096.
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_tandModemMsg*classes."delivery box"findsset_shipmentandget_zrtdata."power consumption"findsget_load_powerand 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 precision0.55— balanced (~1000 results)0.60— precise: ~175 avg, high precision (default)0.65— strict: few results, may miss relevant symbols
Source-aware ranking: Project code boosted 1.2×, library code 1.1×, vendored SDK code 0.85×.
Requires an LLM with an embedding model.
Falls back to search_code with a warning if the LLM is unavailable.
Read-only. No side effects.
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").
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results (default 20, max 100). | |
| query | Yes | Natural language description, 5-15 words. E.g. 'parcel locker state machine' or 'how does the modem connect?'. | |
| threshold | No | Minimum cosine similarity (0.0-1.0). Default 0.60. Use 0.55 for exploratory, 0.50 for broad search. | |
| project_root | No | Project root. Auto-detected if omitted. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |