# Search Mode Configuration

The Web Search tool supports two execution modes, controlled by the **Search Mode** setting (`web_search_active_mode`).

| Setting | Values | Default |
| --- | --- | --- |
| `web_search_active_mode` | `v1`, `v2` | `v2` |

The platform-level default can be overridden via the `WEB_SEARCH_MODE` environment variable.

## V1 -- Basic Search Mode

In V1 mode, the orchestrator LLM sends a simple search query (plus an optional date filter) to the tool. The tool can optionally refine the query before executing.

### Language Model

| Setting | Type | Default |
| --- | --- | --- |
| `language_model` | Language model identifier | `gpt-4o` |

The language model is used for query refinement (Basic/Advanced modes) and other LLM-driven steps in the pipeline.

### Query Refinement

Controls how the user's question is optimized before being sent to the search engine.

| Setting | Type | Default | Description |
| --- | --- | --- | --- |
| `refine_query_mode.mode` | `Basic` / `Advanced (Beta)` / `Deactivated` | `Basic` | Refinement strategy. |
| `refine_query_mode.system_prompt` | string (textarea) | Built-in prompt | Instructions for the LLM on how to optimize search queries. |

**Refinement modes explained:**

- **Deactivated** -- The query is passed through to the search engine exactly as the orchestrator LLM provided it. No LLM call is made.
- **Basic** -- The query is sent to the language model with the refinement prompt. The LLM returns a single optimized query (max ~6 keywords, with optional advanced syntax like quotes, `site:`, `-word`).
- **Advanced (Beta)** -- The query is sent to the language model, which returns multiple targeted queries. Each query focuses on a different facet of the original question. The number of queries is capped by `max_queries`.

### Maximum Search Queries

| Setting | Type | Default | Description |
| --- | --- | --- | --- |
| `max_queries` | integer | `5` | Maximum number of queries generated in Advanced refinement mode. Only applies when refinement mode is set to Advanced. |

### Tool Parameter Descriptions

These control the descriptions shown to the orchestrator LLM for the tool's input parameters.

| Setting | Type | Default |
| --- | --- | --- |
| `tool_parameters_description.query_description` | string (textarea) | `"The search query to issue to the web."` |
| `tool_parameters_description.date_restrict_description` | string (textarea) | Format description for date restriction (`d1`, `w1`, `m3`, `y1`, etc.) |

### Tool Description and System Prompt

| Setting | Type | Description |
| --- | --- | --- |
| `tool_description` | string (textarea) | Short description that helps the orchestrator LLM decide when to use web search. |
| `tool_description_for_system_prompt` | string (textarea) | Detailed instructions for the orchestrator LLM on how and when to use web search, including query splitting guidance and examples. |

## V2 -- AI-Planned Research Mode

In V2 mode, the orchestrator LLM creates a structured research plan (`WebSearchPlan`) containing an objective, analysis, a list of steps, and expected outcomes. Steps execute in parallel.

### Plan Structure

The orchestrator LLM generates a plan with the following structure:

| Field | Description |
| --- | --- |
| `objective` | What the research aims to accomplish. |
| `query_analysis` | Analysis of what information is needed and why. |
| `steps[]` | List of research steps, each with a `step_type`, `objective`, and `query_or_url`. |
| `expected_outcome` | What the research is expected to find. |

Each step is one of:
- `search` -- Run a search engine query.
- `read_url` -- Directly read a specific URL using the crawler.

### Maximum Research Steps

| Setting | Type | Default | Description |
| --- | --- | --- | --- |
| `max_steps` | integer | `5` | Maximum number of steps the AI can include in a single research plan. Plans exceeding this limit are truncated. |

### Tool Description and System Prompt

| Setting | Type | Description |
| --- | --- | --- |
| `tool_description` | string (textarea) | Short description that helps the orchestrator LLM decide when to use web search. |
| `tool_description_for_system_prompt` | string (textarea) | Detailed instructions for the orchestrator LLM on how to plan and execute web research, including plan structure examples and query optimization techniques. |

## Shared Settings

These settings apply regardless of the active search mode.

### Source Content Budget

| Setting | Type | Default | Description |
| --- | --- | --- | --- |
| `percentage_of_input_tokens_for_sources` | float (0.0 -- 1.0) | `0.4` | Percentage of the AI model's input capacity reserved for web search results. Higher values include more search content but leave less room for conversation history. |
| `limit_token_sources` | integer | `60,000` | Hard upper bound on the number of tokens from web sources included in the final prompt. |

### Debug Mode

| Setting | Type | Default | Description |
| --- | --- | --- | --- |
| `debug` | boolean | `false` | When enabled, logs additional technical details (step timings, intermediate data) for troubleshooting.