AI.Tools behaviour (fnord v0.9.22)

This module defines the behaviour for tool calls. Defining a new tool requires implementing the spec/0 and call/2 functions.

The spec/0 function should return a map that describes the tool's capabilities and arguments, using a map to represent the OpenAPI spec.

The call/2 function generates the tool call response. It accepts the requesting AI.Completion's struct and a map derived from the parsed JSON provided by the agent, containing the tool call arguments. Note that, because the arguments are parsed from JSON, the keys will all be strings. Whether those are converted to symbols is between the tool implementation and the code it calls. What happens behind closed APIs is none of MY business.

Skeleton Implementation

defmodule AI.Tools.MyNewTool do
  @behaviour AI.Tools

  @impl AI.Tools
  def async?(), do: true

  @impl AI.Tools
  def ui_note_on_request(_args) do
    {"Doing something", "This tool is doing something."}
  end

  @impl AI.Tools
  def ui_note_on_result(_args, _result) do
    {"Did something", "This tool did something."}
  end

  @impl AI.Tools
  def read_args(args) do
    {:ok, args}
  end

  @impl AI.Tools
  def spec() do
    %{
      type: "function",
      function: %{
        name: "something_tool",
        description: "This tool does something.",
        parameters: %{
          additionalProperties: false,
          type: "object",
          required: ["thing"],
          properties: %{
            thing: %{
              type: "string",
              description: "The thing to do."
            }
          }
        }
      }
    }
  end

  @impl AI.Tools
  def call(args) do
    {:ok, "IMPLEMENT ME"}
  end
end

Summary

Types

args_error()

entry()

entry_not_found()

frob_error()

invalid_arg_error()

json_parse_error()

missing_arg_error()

parsed_args()

project()

project_name()

project_not_found()

raw_tool_result()

something_not_found()

tool_error()

tool_name()

tool_result()

tool_spec()

toolbox()

unknown_tool_error()

unparsed_args()

Callbacks

async?()

Returns true if the tool is asynchronous, false otherwise. If false, when the LLM performs a multi-tool call, this tool will be called synchronously, after all other (asynchronous) tools have been called.

call(args)

Calls the tool with the provided arguments and returns the response as an :ok tuple.

is_available?()

Returns true if the tool is available for use, false otherwise. This is used to determine whether the tool can be used in the current context, such as whether the tool is available in the current project or if it requires specific conditions to be met (e.g., a project being set, availability of an external tool like ripgrep, etc.).

read_args(args)

Reads the arguments and returns a map of the arguments if they are valid. This is used to validate args before the tool is called. The result is what is passed to call/2, ui_note_on_request/1, and ui_note_on_result/2.

spec()

Returns the OpenAPI spec for the tool as an elixir map.

tool_call_failure_message(args, reason)

Returns a message to be displayed when a tool call fails. May return :default, :ignore, a binary message, or a {label, detail} tuple.

ui_note_on_request(args)

Return either a short string or a string tuple of label + detail to be displayed when the tool is called.

ui_note_on_result(args, result)

Return either a short string or a string tuple of label + detail to be displayed when the tool call is successful.

Functions

all_tools()

Returns a toolbox that includes all tools (basic, read/write, coding, task, and web tools).

basic_tools()

Returns a toolbox that includes all generally available tools and frobs.

build_toolbox(modules)

Given a list of modules, returns a map from tool_name => module, using each module's spec().function.name value as the key.

get_arg(opts, key)

Retrieves an argument from the parsed arguments map. Empty strings or nil values will return an error indicating a missing argument.

get_entry(file)

get_entry(project, file)

get_file_contents(file)

get_project()

has_indexed_project()

is_async?(tool_name, tools \\ nil)

maybe_with_ui(toolbox)

Conditionally adds UI tools to the toolbox if the current environment supports it (i.e., if we're running in a TTY and not in quiet mode).

on_tool_error(tool, args, reason, tools \\ nil)

on_tool_request(tool, args, tools \\ nil)

on_tool_result(tool, args, result, tools \\ nil)

perform_tool_call(tool, args, tools \\ nil)

required_arg_error(key)

skill_tool_tags()

Returns the allowed tool tags for skills. Skills.Runtime uses this to avoid duplicating the list.

stable_skill_tool_tag_order()

Returns the deterministic skill tool tags order, excluding "basic", used when applying tags.

tool_module(tool_name, tools \\ nil)

tool_spec(tool, tools \\ nil)

tool_spec!(tool, tools \\ nil)

toolbox_to_specs(toolbox)

Generate a list of tool specs from a toolbox map.

tools()

with_args(tool, args, fun, tools \\ nil)

with_coding_tools(toolbox \\ %{})

Adds the coding tools to the toolbox. Coding tools mutate the codebase, but do so in an organized, planned way, rather than directly managing files.

with_frobs(toolbox \\ %{})

Adds user-defined frobs to the toolbox. Frobs are local tooling (linters, formatters, test runners, kubectl wrappers, etc.) so they should only be given to agents that test, validate, or investigate - not to agents that only produce structured output (e.g. the Patcher).

with_mcps(toolbox \\ %{})

Adds MCP (Model Context Protocol) tools to the toolbox. MCP tools are externally hosted tool servers enabled at the project or global level. Starts the MCP service lazily on first call.

with_review_tools(toolbox \\ %{})

Adds the review tools to the toolbox. Review tools are read-only agents that perform multi-specialist code review.

with_rw_tools(toolbox \\ %{})

Adds the read/write tools to the toolbox. This includes tools that can directly perform file edits, shell commands, and other read/write operations.

with_skills(toolbox \\ %{})

Adds the skills tools to the toolbox. Skills are specialized tools that should only be included when explicitly requested.

with_task_tools(toolbox \\ %{})

Adds the task management tools to the toolbox. This includes tools that can create and manage task lists.

with_ui(toolbox \\ %{})

Adds interactive UI tools to the toolbox.

with_web_tools(toolbox \\ %{})

Adds the web tools to the toolbox. This includes tools that can access the web, such as web search.