# `Codex.Tools.WebSearchTool`
[🔗](https://github.com/nshkrdotcom/codex_sdk/blob/v0.18.1/lib/codex/tools/web_search_tool.ex#L1)

Hosted tool for performing web searches.

## Overview

WebSearchTool provides web search functionality with support for multiple
search providers. It can be used standalone or registered in the tool registry.

## Configuration

Requires a search provider to be configured. Supported providers:

  * `:tavily` - Tavily Search API (requires `TAVILY_API_KEY`)
  * `:serper` - Serper API (requires `SERPER_API_KEY`)
  * `:mock` - Mock provider for testing (no API key needed)
  * Custom callback via `:searcher` option

## Options

Options can be passed during registration or via context metadata:

  * `:provider` - Search provider (default: `:tavily`)
  * `:api_key` - API key (or from environment variable)
  * `:max_results` - Maximum results to return (default: 10)
  * `:searcher` - Custom search callback function (overrides provider)

## Usage

### With Mock Provider (Testing)

    {:ok, _} = Codex.Tools.register(Codex.Tools.WebSearchTool,
      provider: :mock
    )

    {:ok, result} = Codex.Tools.invoke("web_search", %{"query" => "elixir"}, %{})
    # => %{"count" => 2, "results" => [...]}

### With Tavily Provider

    {:ok, _} = Codex.Tools.register(Codex.Tools.WebSearchTool,
      provider: :tavily,
      api_key: Codex.Env.get("TAVILY_API_KEY")
    )

    {:ok, result} = Codex.Tools.invoke("web_search",
      %{"query" => "Elixir programming", "max_results" => 5},
      %{}
    )

### With Custom Searcher

    searcher = fn args, _ctx, _meta ->
      {:ok, %{"count" => 1, "results" => [%{"title" => args["query"]}]}}
    end

    {:ok, _} = Codex.Tools.register(Codex.Tools.WebSearchTool,
      searcher: searcher
    )

## Environment Variables

  * `TAVILY_API_KEY` - API key for Tavily search provider
  * `SERPER_API_KEY` - API key for Serper search provider

---

*Consult [api-reference.md](api-reference.md) for complete listing*