fix(indexing): improvements to semantic_search tool description

[shssoichiro]

Issue

Fixes #10271 (hopefully for good this time)

Context

The semantic search tool continues to not be invoked reliably. We want to help agents understand how and when to use this tool appropriately.

Implementation

• Add a statement instructing the agent to "proactively" use the tool in the appropriate scenario. The word "proactively" has been shown to improve agent tool utilization.
• Refactor the location and wording of directory and path parameter limitations, as I've seen agents sometimes failing to understand these limitations.

Screenshots / Video

N/A

How to Test

• Do some task that involves finding code snippets without knowing the specific name. Don't explicitly tell the agent to use the tool.
• Codebase search should be used early in the agent's exploratory process to narrow down search scope for more exact file reads and greps.

Checklist

• Issue linked above, or exception explained
• Tests/verification described
• Screenshots/video included for visual changes, or marked N/A
• Changeset considered for user-facing changes
• I personally reviewed the diff and can explain the changes, including any AI-assisted work.

Get in Touch

ExpedientFalcon on Discord

[kilo-code-bot]

Code Review Summary

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	1

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
packages/opencode/src/kilocode/tool/semantic-search.txt	7	New prose references Grep/Read without backticks while the rest of the description code-formats tool names

Files Reviewed (1 file)

• packages/opencode/src/kilocode/tool/semantic-search.txt - 1 issue

Notes: the reworded "When to use" prose matches the wording agreed in the existing review discussion, and the earlier duplicate-bullet finding no longer applies. The PR description still says the change adds a "proactively" instruction, which the current text no longer contains — worth updating the description before merge.

Fix these issues in Kilo Cloud

Previous Review Summaries (2 snapshots, latest commit 1a55007)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 1a55007)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (1 file)

• packages/opencode/src/kilocode/tool/semantic-search.txt - previously flagged duplicate bullet removed; no remaining issues

Previous review (commit 5aeb043)

Status: 1 Issue Found | Recommendation: Merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	1

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
packages/opencode/src/kilocode/tool/semantic-search.txt	5	New intro line duplicates an existing "When to use" bullet, making the guidance redundant

Files Reviewed (1 file)

• packages/opencode/src/kilocode/tool/semantic-search.txt - 1 issue

Fix these issues in Kilo Cloud

---

_{Reviewed by claude-opus-5 · Input: 28 · Output: 5.2K · Cached: 755.4K}

_{Review guidance: REVIEW.md from base branch main}

[marius-kilocode]

Maybe we should make it clearer when semantic search is superior to indexed based search. "Use proactively before" will inevitably lead to more token consumption.

[shssoichiro]

I'm unsure what you mean. This is the indexing-based semantic search tool. Are you thinking about how it interacts with the warpgrep semantic search tool? That is a good question. I've been generally running on the assumption that a user won't have both enabled at the same time, because that seems like the most likely scenario, but also because my assumption is that right now, if a user does have both enabled, the LLM will pick one pseudo-randomly.

[marius-kilocode]

You are right that semantic_search is itself index-backed. I was conflating indexing with lexical search. The distinction I meant is semantic retrieval versus exact keyword/regex search.

I do not think we should instruct agents to use semantic search proactively before all targeted tools. It is superior when the agent can describe the desired behavior but does not yet know the repository’s identifiers or terminology. Grep is superior when there is already a concrete symbol, string, config key, error, or regex.

Can we try something like:

“Use early for open-ended exploration when you know the intent but not the exact identifiers or the semantics. Once likely files or symbols are found, follow up with Grep and Read. Prefer Grep directly when exact terms are already known.”

[shssoichiro]

Sounds good to me!

[kilo-code-bot]

SUGGESTION: Keep tool names in backticks for consistency

Every other tool reference in this description is code-formatted (Grep, Glob, Read, path), but the new prose mentions Grep and Read as plain words. Since this text goes straight into the model-facing tool description, consistent formatting makes it clearer these are literal tool names rather than prose.

Suggested change

	follow up with Grep and Read. Prefer Grep directly when exact terms are already known.
	follow up with `Grep` and `Read`. Prefer `Grep` directly when exact terms are already known.

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[marius-kilocode]

Thanks @shssoichiro