Normandy.Tools.BaseTool protocol (normandy v0.6.0)

View Source

Protocol for implementing executable tools that agents can use.

Tools represent external functions or capabilities that agents can invoke during their execution. Each tool must provide metadata (name, description, schema) and an execution implementation.

Summary

Types

t()

All the types that implement this protocol.

Functions

input_schema(config)

Returns the JSON schema describing the tool's input parameters.

run(config)

Executes the tool with the given configuration/parameters.

tool_description(config)

Returns a human-readable description of what this tool does.

tool_name(config)

Returns the unique name identifier for this tool.

Types

t()

@type t() :: term()

All the types that implement this protocol.

Functions

input_schema(config)

@spec input_schema(struct()) :: map()

Returns the JSON schema describing the tool's input parameters.

The schema should follow the JSON Schema specification and describe all required and optional parameters for the tool.

Examples

iex> tool = %CalculatorTool{}
iex> Normandy.Tools.BaseTool.input_schema(tool)
%{
  type: "object",
  properties: %{
    operation: %{type: "string", enum: ["add", "subtract", "multiply", "divide"]},
    a: %{type: "number", description: "First operand"},
    b: %{type: "number", description: "Second operand"}
  },
  required: ["operation", "a", "b"]
}

run(config)

@spec run(struct()) :: {:ok, term()} | {:error, String.t()}

Executes the tool with the given configuration/parameters.

Returns either {:ok, result} on success or {:error, reason} on failure. The result should be serializable to JSON.

Examples

iex> tool = %CalculatorTool{operation: :add, a: 5, b: 3}
iex> Normandy.Tools.BaseTool.run(tool)
{:ok, 8}

iex> tool = %CalculatorTool{operation: :divide, a: 10, b: 0}
iex> Normandy.Tools.BaseTool.run(tool)
{:error, "Division by zero"}

tool_description(config)

@spec tool_description(struct()) :: String.t()

Returns a human-readable description of what this tool does.

This description is used to help the LLM understand when and how to use the tool.

Examples

iex> tool = %CalculatorTool{}
iex> Normandy.Tools.BaseTool.tool_description(tool)
"Performs basic arithmetic operations on numbers"

tool_name(config)

@spec tool_name(struct()) :: String.t()

Returns the unique name identifier for this tool.

Examples

iex> tool = %MyTool{}
iex> Normandy.Tools.BaseTool.tool_name(tool)
"my_tool"