semantic_search
Find code symbols by concept using natural language queries and semantic embeddings, even when exact names are unknown.
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 |