Behaviour for tools that agents can call.

Required Callbacks

Every tool must implement name/0, description/0, input_schema/0, and execute/2.

Optional Callbacks

Tools may optionally implement:

• allowed_callers/0 — declares which callers may invoke this tool (:human, :code_execution). Defaults to [:human].
• result_type/0 — declares whether the tool returns :text or :structured data. Defaults to :text.

Structured Results

Tools can return a 3-tuple {:ok, text, data} where text is the human-readable result and data is a map of structured data for programmatic consumption (e.g., by a code execution sandbox).

Path Security

Set :allowed_paths in the agent context to restrict file access:

Alloy.run("Read the config",
  context: %{allowed_paths: ["/home/user/project"]},
  tools: [Alloy.Tool.Core.Read]
)

When configured, resolve_path/2 returns {:error, reason} for paths outside the allowed directories.

Example

defmodule MyApp.Tools.Weather do
  @behaviour Alloy.Tool

  @impl true
  def name, do: "get_weather"

  @impl true
  def description, do: "Get current weather for a location"

  @impl true
  def input_schema do
    %{
      type: "object",
      properties: %{location: %{type: "string", description: "City name"}},
      required: ["location"]
    }
  end

  @impl true
  def execute(%{"location" => loc}, _context) do
    {:ok, "72°F, sunny in #{loc}", %{temp: 72, condition: "sunny", location: loc}}
  end

  @impl true
  def allowed_callers, do: [:human, :code_execution]

  @impl true
  def result_type, do: :structured
end