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.

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.

---

📘 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.