> For the complete documentation index, see [llms.txt](https://docs.zaia.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zaia.app/tools/available-tools/web-search-tool.md).

# Web Search Tool

The **Agentic Web Search Tool** allows your Agent to search the public web when it needs information that is not available in its existing context or knowledge sources. This is useful for retrieving up-to-date external information, validating facts, or gathering references from specific websites.

***

### 🔎 Overview

This tool gives your Agent an agentic way to search the web.

The Agent sends a textual description of what it needs to find. The search runs using OpenAI web search.

The tool returns:

* A consolidated text with the most relevant findings
* A list of source URLs found during the search

***

### ⚙️ Configuration Fields

1. **Name** — A clear name that identifies the purpose of the tool.\
   Example: `Product Documentation Search`
2. **Description** — Tells the Agent when and why it should use the tool.\
   Keep it specific so the Agent can choose the tool at the right time.
3. **Allowed Domains** — Optionally restricts search results to specific websites.\
   Use this when you want answers from trusted or official sources only.\
   Enter domains without `https://`.\
   Example: `openai.com`, not `https://openai.com/`.\
   A root domain also covers its subdomains.\
   Example: `openai.com` also covers subdomains.\
   OpenAI supports up to `100` allowed domains for `web_search`.
4. **Effort** — Defines the reasoning effort used during the search.\
   Available options: `low`, `medium`, `high`
5. **Execution** — Defines whether the tool is optional or mandatory.\
   Available options:
   * `eligible` — The Agent decides when to use the tool
   * `compulsory` — The tool must be executed
6. **Prompt** — Optional extra instruction that guides how the search should be conducted.\
   Use it for short guidance that improves search quality.
7. **LLM Provider** — Optional provider override for this tool.\
   Only **OpenAI providers** are supported.

***

### 🧠 How it works

1. The Agent decides to use the tool based on its configuration.
2. The Agent sends a textual description of the search it needs.
3. The tool performs the search using OpenAI web search.
4. If **Allowed Domains** is configured, results are limited to those domains.
5. **Effort** controls how much reasoning the search applies.
6. **Execution** controls whether use of the tool is optional or mandatory.

This makes the tool useful for external lookups that require fresh information or verifiable references.

{% hint style="info" %}
Domain filtering follows OpenAI `web_search` behavior in the Responses API. OpenAI supports up to `100` entries in `allowed_domains` or `blocked_domains`, but this tool currently exposes **Allowed Domains** only. These filters are not supported by the legacy `web_search_preview` tool or by Chat Completions search models. See [OpenAI Web Search domain filtering](https://platform.openai.com/docs/guides/tools-web-search).
{% endhint %}

***

### 📘 Example Setup

* **Name**: `Product Documentation Search`
* **Description**: `Use this tool when you need to find reliable information on official product documentation websites.`
* **Allowed Domains**: `docs.example.com`, `help.example.com`
* **Effort**: `medium`
* **Execution**: `eligible`
* **Prompt**: `Prefer official documentation and summarize the most relevant findings.`
* **LLM Provider**: `default OpenAI provider`

This setup helps the Agent search trusted documentation sources and return concise, grounded answers.

***

### 💡 Best Practices

* Keep the **Description** specific so the Agent knows when to use the tool.
* Use **Allowed Domains** when you want to restrict searches to trusted sources.
* List domains in plain form, without protocol prefixes.
* Choose higher **Effort** only when the task needs deeper reasoning.
* Use **compulsory** execution only when every relevant interaction must include a web lookup.
* Use the **Prompt** field for concise guidance, not long procedural instructions.