# Agent-Side Search Patterns

## Purpose

Documents recommended patterns for agent-side query expansion, plus how agent guidance interacts with the engine's optional server-side reranking. These patterns are communicated via MCP tool descriptions.

## Requirements

### Requirement: Query expansion guidance in tool description

The `kb_search` MCP tool description SHALL include guidance on query expansion as a recommended pattern for complex queries.

#### Scenario: Tool description includes expansion pattern
- **WHEN** an agent reads the `kb_search` tool description
- **THEN** the description SHALL include guidance such as: "For complex queries, consider expanding into 2-3 variant phrasings and calling this tool multiple times, then deduplicating results by chunk_id"

---

### Requirement: Reranking guidance in tool description

The `kb_search` MCP tool description SHALL describe the engine's server-side reranking behaviour and retain agent-side reranking as a fallback pattern.

#### Scenario: Tool description covers server-side reranking
- **WHEN** an agent reads the `kb_search` tool description
- **THEN** the description SHALL state that results are reranked server-side by default when the engine has a reranker enabled, that `rerank=False` skips it for lower latency, and that `kb_status` reports whether reranking is active

#### Scenario: Tool description retains agent-side fallback
- **WHEN** an agent reads the `kb_search` tool description
- **THEN** the description SHALL include guidance that, when the engine's reranker is disabled, the agent can rerank the returned results using its own judgement of relevance to the original question

---

### Requirement: No external LLM dependency

The engine SHALL NOT require or use any external LLM API for search operations. Query expansion SHALL remain an agent-side concern. Reranking MAY be performed engine-side using a local, opt-in cross-encoder model; it SHALL never depend on an external API.

#### Scenario: Engine has no external LLM dependency
- **WHEN** the engine is deployed without any `ANTHROPIC_API_KEY` or similar LLM API configuration
- **THEN** all search operations SHALL function fully, with no degraded results or missing features

#### Scenario: Reranking is optional and degrades gracefully
- **WHEN** the engine is deployed with `KB_RERANK_ENABLED` unset or false, or the reranker model fails to load
- **THEN** all search operations SHALL function fully using hybrid retrieval alone, with responses reporting `"reranked": false`