Mojentic.LLM.Tools.Tool behaviour (Mojentic v1.2.0)

Behaviour for LLM tool implementations.

Tools allow LLMs to perform actions or retrieve information by calling functions that you define.

Examples

Implementing a custom tool:

defmodule WeatherTool do
  @behaviour Mojentic.LLM.Tools.Tool

  @impl true
  def run(arguments) do
    location = Map.get(arguments, "location", "unknown")
    {:ok, %{location: location, temperature: 22, condition: "sunny"}}
  end

  @impl true
  def descriptor do
    %{
      type: "function",
      function: %{
        name: "get_weather",
        description: "Get current weather for a location",
        parameters: %{
          type: "object",
          properties: %{
            location: %{
              type: "string",
              description: "The city or location"
            }
          },
          required: ["location"]
        }
      }
    }
  end
end

Summary

Types

descriptor()

Callbacks

descriptor()

Returns the tool descriptor for the LLM.

run(tool, arguments)

Executes the tool with the given arguments.

Functions

description(tool)

Returns the tool's description from its descriptor.

descriptor(tool)

Returns the descriptor for a tool.

matches?(tool, tool_name)

Checks if a tool matches the given name.

name(tool)

Returns the tool's name from its descriptor.

run(tool, arguments)

Runs a tool with the given arguments.

Types

descriptor()

@type descriptor() :: %{
  type: String.t(),
  function: %{name: String.t(), description: String.t(), parameters: map()}
}

Callbacks

descriptor()

@callback descriptor() :: descriptor()

Returns the tool descriptor for the LLM.

The descriptor includes the tool's name, description, and parameter schema in JSON Schema format.

run(tool, arguments)

@callback run(tool :: struct(), arguments :: map()) :: {:ok, term()} | {:error, term()}

Executes the tool with the given arguments.

Parameters

tool: The tool struct instance
arguments: Map of argument name to value

Returns

{:ok, result} on success
{:error, reason} on failure

Functions

description(tool)

Returns the tool's description from its descriptor.

Examples

iex> Tool.description(WeatherTool)
"Get current weather for a location"

descriptor(tool)

Returns the descriptor for a tool.

Handles both module-based tools (with descriptor/0) and struct-based tools (with descriptor/1).

Examples

iex> Tool.descriptor(WeatherTool)
%{type: "function", function: %{name: "get_weather", ...}}

iex> tool = ToolWrapper.new(...)
iex> Tool.descriptor(tool)
%{type: "function", function: %{name: "custom_name", ...}}

matches?(tool, tool_name)

Checks if a tool matches the given name.

Examples

iex> Tool.matches?(WeatherTool, "get_weather")
true

iex> Tool.matches?(WeatherTool, "other_tool")
false

name(tool)

Returns the tool's name from its descriptor.

Supports both module-based tools and struct-based tools with instance descriptors.

Examples

iex> Tool.name(WeatherTool)
"get_weather"

iex> tool_instance = ToolWrapper.new(agent: agent, name: "custom", description: "desc")
iex> Tool.name(tool_instance)
"custom"

run(tool, arguments)

Runs a tool with the given arguments.

Supports both module-based tools and struct-based tools.

Examples

iex> Tool.run(WeatherTool, %{"location" => "SF"})
{:ok, %{location: "SF", temperature: 22, condition: "sunny"}}

iex> tool = ToolWrapper.new(...)
iex> Tool.run(tool, %{"input" => "test"})
{:ok, "response"}