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:textor:structureddata. Defaults to:text.strict?/0— requests provider strict-mode schema enforcement. Defaults tofalse.input_examples/0— example inputs for providers that support advanced tool-use metadata. Defaults to[].defer_loading?/0— requests provider-side deferred loading where supported. Defaults tofalse.native_types/0— a provider's built-in type for this tool, such as Anthropic'smemory_20250818. Defaults to%{}.
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 follows symlinks and returns
{:error, reason} for paths whose real location is outside the allowed
directories. The built-in read, write and edit tools use it; it does
not restrict the bash tool.
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
Summary
Callbacks
Declares which callers may invoke this tool.
Whether this tool is safe to run concurrently with other tools.
State-mutating tools (file write, bash) should return false.
Defaults to true when not implemented.
Whether providers that support deferred tool loading should defer this tool.
Human-readable description of what the tool does.
Execute the tool with the given input.
Example tool inputs for provider tool-use guidance.
JSON Schema defining the tool's input parameters.
Maximum characters in the tool result before truncation.
The executor truncates results exceeding this, keeping head + tail.
Defaults to :unlimited when not implemented.
Unique tool name (used in API calls).
A provider's own schema for this tool, keyed by provider family.
Declares the tool's result type.
Whether providers should use strict schema enforcement for this tool.
Functions
Build an inline tool — a tool defined as data instead of a module.
Resolve a file path against the working directory from context.
Callbacks
@callback allowed_callers() :: [:human | :code_execution]
Declares which callers may invoke this tool.
:human— the tool can be called by the model during normal conversation:code_execution— the tool can be called from a code execution sandbox
Defaults to [:human] when not implemented. Providers that support
allowed_callers (e.g., Anthropic) include this in the tool definition
sent to the API.
@callback concurrent?() :: boolean()
Whether this tool is safe to run concurrently with other tools.
State-mutating tools (file write, bash) should return false.
Defaults to true when not implemented.
@callback defer_loading?() :: boolean()
Whether providers that support deferred tool loading should defer this tool.
@callback description() :: String.t()
Human-readable description of what the tool does.
@callback execute(input :: map(), context :: map()) :: {:ok, String.t()} | {:ok, String.t(), map()} | {:error, String.t()}
Execute the tool with the given input.
Context is a map that may contain:
:working_directory- base path for file operations:config- agent config struct:allowed_paths- list of allowed directory prefixes for file access- any custom keys added by middleware
Returns {:ok, string} or {:error, string} for text-only results.
Optionally returns {:ok, string, map} to include structured data
alongside the text (for programmatic consumption by code execution).
@callback input_examples() :: [map()]
Example tool inputs for provider tool-use guidance.
@callback input_schema() :: map()
JSON Schema defining the tool's input parameters.
@callback max_result_chars() :: pos_integer() | :unlimited
Maximum characters in the tool result before truncation.
The executor truncates results exceeding this, keeping head + tail.
Defaults to :unlimited when not implemented.
@callback name() :: String.t()
Unique tool name (used in API calls).
A provider's own schema for this tool, keyed by provider family.
A provider that finds its key sends the tool as that built-in type
instead of as a function with input_schema; every other provider uses
input_schema. Alloy.Provider.Anthropic reads :anthropic, so
%{anthropic: "memory_20250818"} makes Claude use its trained memory
tool while other models see the JSON schema. The tool still runs on the
client like any other. Defaults to %{}.
@callback result_type() :: :text | :structured
Declares the tool's result type.
:text— tool returns{:ok, String.t()}(the default):structured— tool returns{:ok, String.t(), map()}
Used by the executor and downstream consumers to know whether structured data is available in the tool result metadata.
@callback strict?() :: boolean()
Whether providers should use strict schema enforcement for this tool.
Strict tools must declare additionalProperties: false on their top-level
input schema. Alloy validates this instead of mutating the schema silently.
Functions
@spec inline(keyword() | map()) :: Alloy.Tool.Inline.t()
Build an inline tool — a tool defined as data instead of a module.
Accepts the same information as the behaviour callbacks, as options.
The returned Alloy.Tool.Inline struct can be passed in tools:
alongside tool modules. Use this for tools discovered at runtime
(e.g., an MCP server's tool list) or one-off tools that don't warrant
a module:
lookup =
Alloy.Tool.inline(
name: "lookup_user",
description: "Look up a user by email",
input_schema: %{
type: "object",
properties: %{email: %{type: "string"}},
required: ["email"]
},
execute: fn %{"email" => email}, _context ->
case MyApp.Accounts.get_by_email(email) do
nil -> {:error, "No user with email " <> email}
user -> {:ok, "User: " <> user.name}
end
end
)See Alloy.Tool.Inline for all options. Raises ArgumentError on
invalid definitions.
Resolve a file path against the working directory from context.
Absolute paths are expanded. Relative paths are joined with the
:working_directory from context, or expanded from cwd if not set.
When :allowed_paths is set in context, every symlink in the path is
followed and the resulting real path must equal one of the allowed
directories (themselves resolved the same way) or sit beneath it.
/proj allows /proj/lib/app.ex but not /proj-secrets/key.txt.
Components that do not exist yet (a file about to be written) are
accepted as they are. The real path is returned, so the tool opens the
file that was checked. Returns {:error, reason} for a path outside
the allowed directories or one that cannot be resolved (a symlink
loop).
The check happens before the tool opens the file. It is a guard for an agent's file tools, not a sandbox: a process that can create symlinks under an allowed directory between the check and the open (for example the agent's own bash tool) can still race it.