# `Jibu.Tools`
[🔗](https://github.com/oliverandrich/jibu/blob/v0.2.1/lib/jibu/tools.ex#L1)

Runs a tool-use conversation until the model stops asking for tools.

Jibu executes every tool in `body.tools` that carries a `:run` function.
Jibu removes `:run` before sending. Every other field passes through.
Tools without `:run`, such as server tools, go out unchanged.

    weather = %{
      name: "weather",
      description: "Current weather for a city",
      input_schema: %{type: "object", properties: %{city: %{type: "string"}}, required: ["city"]},
      run: fn %{"city" => city} -> {:ok, "sunny in " <> city} end
    }

    {:ok, response, messages} =
      Jibu.Tools.run(client, %{
        model: "claude-opus-5-5",
        max_tokens: 1024,
        tools: [weather],
        messages: [%{role: "user", content: "Weather in Berlin?"}]
      })

`:run` receives the tool input as a map with string keys.
It returns `{:ok, content}` or `{:error, content}`.
`content` is a string or a list of content blocks.

An error tuple, a raised exception or an unknown tool name becomes a `tool_result` with
`is_error: true`. The model sees the error and can react.
All results of one turn go back in a single user message.

A `pause_turn` response goes back unchanged, so the model can continue.
The returned `messages` hold the whole conversation, ending with the final assistant turn.

See the [Tools guide](tools.md) for more.

# `run`

```elixir
@spec run(Req.Request.t(), map() | String.t() | [map()], keyword()) ::
  {:ok, Jibu.Response.t(), [map()]} | {:error, Jibu.Error.t()}
```

Runs the loop.

The second argument is a request body or a prompt. A prompt takes the shortcuts of
`Jibu.ask/3` except `:on_text`. Use `:on_event` to stream.
`tools:` goes into the body like any other keyword.

Returns `{:ok, response, messages}` for the first response whose `stop_reason` is neither
`"tool_use"` nor `"pause_turn"`. Check that `stop_reason` for `"refusal"` or `"max_tokens"`
before using the answer.

## Options

  * `:max_iterations` - maximum number of requests, default `10`.
  * `:max_concurrency` - maximum number of tools of one turn that run at once, default `1`.
  * `:tool_timeout` - milliseconds a tool may run, default `:infinity`.
    A tool that exceeds it is killed and returns an error result.
  * `:on_event` - a function that receives every stream event of every turn.
    Each turn then goes through `Jibu.stream/3`.

With `:max_concurrency` above `1` or a finite `:tool_timeout`, each tool runs in its own task.

---

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