# `Planck.Agent.Tool`
[🔗](https://github.com/alexdesousa/planck/blob/v0.1.0/lib/planck/agent/tool.ex#L1)

An executable tool for use in agent turns.

Extends `Planck.AI.Tool` with an `execute_fn` — the function called when the
LLM requests a tool invocation. The AI tool schema (name, description, parameters)
is extracted when building `Planck.AI.Context`; `execute_fn` stays agent-side.

# `execute_fn`

```elixir
@type execute_fn() :: (agent_id :: String.t(), id :: String.t(), args :: map() ->
                   {:ok, String.t()} | {:error, String.t()})
```

The function invoked when the LLM requests this tool.

Receives the calling `agent_id`, the tool call `id` (an opaque string from
the provider, used to correlate results), and `args` (the JSON-decoded
arguments map). Must return `{:ok, result}` or `{:error, reason}` where both
values are strings — they are placed directly into the model's context as
tool result text. Exceptions and exit signals are caught by the agent and
converted to error strings automatically.

# `t`

```elixir
@type t() :: %Planck.Agent.Tool{
  description: String.t(),
  execute_fn: execute_fn(),
  name: String.t(),
  parameters: map()
}
```

A fully-specified tool: schema fields understood by the LLM plus the
`execute_fn` that runs when the model calls it.

- `:name` — identifier the model uses to call the tool; must be unique within
  an agent's tool set
- `:description` — natural-language description sent to the model; quality
  here directly affects how reliably the model uses the tool
- `:parameters` — JSON Schema object describing the accepted arguments
- `:execute_fn` — the function called with the agent id, tool call id, and decoded args

# `new`

```elixir
@spec new(keyword()) :: t()
```

Build a `Planck.Agent.Tool` from keyword options.

## Examples

    iex> Tool.new(
    ...>   name: "read_file",
    ...>   description: "Read a file",
    ...>   parameters: %{"type" => "object", "properties" => %{"path" => %{"type" => "string"}}, "required" => ["path"]},
    ...>   execute_fn: fn _agent_id, _id, %{"path" => path} -> File.read(path) end
    ...> )
    %Planck.Agent.Tool{name: "read_file", ...}

# `to_ai_tool`

```elixir
@spec to_ai_tool(t()) :: Planck.AI.Tool.t()
```

Convert to a `Planck.AI.Tool` for use in `Planck.AI.Context` (drops `execute_fn`).

---

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