# `Pixir.Provider.HostedTools`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/provider/hosted_tools.ex#L1)

Request shaping for Provider-hosted OpenAI tools.

These are not Pixir local `Tool`s. Pixir does not execute them, does not record them
as `tool_call` / `tool_result`, and does not ask `Pixir.Tools.Executor` to run them.
They are Provider-side capabilities declared in the Responses request body. Pixir's
job is to shape the request deliberately and later persist bounded Provider evidence.

# `error_reason`

```elixir
@type error_reason() :: %{kind: :invalid_args, message: String.t(), details: map()}
```

# `from_request`

```elixir
@spec from_request(map()) :: {:ok, [map()]} | {:error, error_reason()}
```

Extract Provider-hosted tool specs from a Provider request.

Supported request fields:

  * `:web_search` / `"web_search"` - Pixir-owned config for the hosted web search
    tool;
  * `:hosted_tools` / `"hosted_tools"` - raw hosted tool specs for tests or future
    Provider-hosted tools.

# `include_fields`

```elixir
@spec include_fields(map(), [map()]) :: {:ok, [String.t()]} | {:error, error_reason()}
```

Responses `include` fields needed by the declared hosted tools.

Web search source evidence is included by default whenever web search is enabled.
Callers may set `web_search.include_sources: false` to suppress it for a targeted
probe.

# `web_search`

```elixir
@spec web_search(map() | keyword() | boolean() | nil) ::
  {:ok, map() | nil} | {:error, error_reason()}
```

Build an OpenAI hosted `web_search` tool spec.

Pixir defaults `search_context_size` to `"low"` for beta ergonomics and cost
discipline. Supported OpenAI search policy fields are preserved; unsupported fields
return structured `:invalid_args` instead of silently changing policy.
`include_sources` is intentionally not part of the tool object; it drives the
Responses `include` list via `include_fields/2`.

# `web_search_config_fields`

```elixir
@spec web_search_config_fields() :: [String.t()]
```

The full `web_search` config vocabulary (config-only flags plus tool fields).

Single source of truth for every parser of this shape: `Pixir.Config` validates
config.json against this same list so the two can never drift.

# `web_search_requested?`

```elixir
@spec web_search_requested?([map()]) :: {:ok, boolean()} | {:error, error_reason()}
```

True when the hosted tool list contains OpenAI web search.

---

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