docs(ctx_search): tool description lacks query-phrasing guidance for hybrid retrieval (keyword stacks starve the 0.7 semantic leg)
Problem
CTX_SEARCH_DESCRIPTION (packages/plugin/src/tools/ctx-search/constants.ts, L3–L20) tells the agent what to search and how to pick sources, but says nothing about how to phrase the query. The only stylistic signal is the implicit example list ("did we solve this before?", "what did we decide about X?", …) — all question-form, but never stated as a convention.
Left unguided, agents (reasonably) fall back to search-engine habits and issue keyword-stack queries: tagger collision fix scoring regression.
Why it matters
ctx_search is hybrid retrieval, not a keyword engine:
- Implicit searches blend
SEMANTIC_WEIGHT = 0.7 × semantic score + FTS_WEIGHT = 0.3 × FTS score, plus per-source boosts (search.ts).
- Explicit tool calls add a literal-probe pass merged via RRF.
Because the semantic leg carries 0.7 of the weight, query form materially affects ranking. Measured in a real project DB (same intent, same target memory):
| Query form |
True hit rank |
Score |
Keyword stack (tagger collision fix scoring …) |
3rd |
0.55 |
Natural question with embedded literal terms ("did we fix the tagger collision where …?") |
2nd |
0.60 |
The question-form query also produced a more correct ordering overall. Keyword stacks feed the 0.3 FTS leg while starving the 0.7 semantic leg — the description's own examples hint at the right form, but an agent that pattern-matches on "search tool" never sees the hint as a rule.
Proposal
Add a short "How to query" section to CTX_SEARCH_DESCRIPTION:
- State the mechanism in one line: hybrid semantic (0.7) + FTS (0.3) retrieval, so phrasing matters.
- Prescribe the form: question-form with embedded literal terms — a natural-language question that still contains the exact identifiers/symbols the answer would contain (these feed the FTS leg and the explicit-call literal probe).
- Discourage bare keyword stacks.
Suggested wording sketch (happy to iterate):
Phrase the query as a natural-language question containing the literal terms you expect in the answer (e.g. "did we fix the tagger collision in scoring?"), not as a bare keyword stack. Retrieval is hybrid semantic + FTS, so question form helps the semantic leg while embedded literals still hit the FTS leg.
PR forthcoming — I'll open a PR with this description change shortly.
Environment
@cortexkit/pi-magic-context 0.41.4
docs(ctx_search): tool description lacks query-phrasing guidance for hybrid retrieval (keyword stacks starve the 0.7 semantic leg)
Problem
CTX_SEARCH_DESCRIPTION(packages/plugin/src/tools/ctx-search/constants.ts, L3–L20) tells the agent what to search and how to picksources, but says nothing about how to phrase the query. The only stylistic signal is the implicit example list ("did we solve this before?","what did we decide about X?", …) — all question-form, but never stated as a convention.Left unguided, agents (reasonably) fall back to search-engine habits and issue keyword-stack queries:
tagger collision fix scoring regression.Why it matters
ctx_search is hybrid retrieval, not a keyword engine:
SEMANTIC_WEIGHT = 0.7× semantic score +FTS_WEIGHT = 0.3× FTS score, plus per-source boosts (search.ts).Because the semantic leg carries 0.7 of the weight, query form materially affects ranking. Measured in a real project DB (same intent, same target memory):
tagger collision fix scoring …)"did we fix the tagger collision where …?")The question-form query also produced a more correct ordering overall. Keyword stacks feed the 0.3 FTS leg while starving the 0.7 semantic leg — the description's own examples hint at the right form, but an agent that pattern-matches on "search tool" never sees the hint as a rule.
Proposal
Add a short "How to query" section to
CTX_SEARCH_DESCRIPTION:Suggested wording sketch (happy to iterate):
PR forthcoming — I'll open a PR with this description change shortly.
Environment
@cortexkit/pi-magic-context0.41.4