The contract every tool implements.

A tool is a struct whose module implements this behaviour. The struct holds the tool's configuration (an endpoint, a store, an index name), set by the application when it registers the tool (Normandy.Tools.Toolset.register/3). The model's input never goes into it: the dispatcher validates the input against input_schema/1 (Normandy.Tools.Input.validate/2) and passes it to run/2 as context.input.

Callbacks

• name/1: the name the model calls the tool by, 1 to 64 letters, digits, _ or -.
• description/1: what the tool does, for the model.
• input_schema/1: the JSON Schema object of the input.
• run/2: runs the tool. context.input is the validated input. Returns {:ok, result} or {:error, reason}; either reaches the model as the tool result.
• check_context!/2 (optional): checks the agent's tool_context when the agent is built or the tool is registered.
• native_definition/1 (optional): the provider-defined tool type the tool implements, which an adapter that supports it sends instead of the description and input schema.

use Normandy.Tool

defmodule MyApp.Search do
  defmodule Input do
    use Normandy.Schema

    io_schema "Search input" do
      field(:query, :string, required: true, description: "What to look for")
      field(:limit, :integer, default: 5, minimum: 1, maximum: 20)
    end
  end

  use Normandy.Tool, name: "search", description: "Searches the catalogue", input: Input

  defstruct [:index]

  @impl Normandy.Tool
  def run(%__MODULE__{index: index}, %Normandy.Tools.Context{input: %Input{} = input}),
    do: MyApp.Catalogue.search(index, input.query, input.limit)
end

use Normandy.Tool declares the behaviour, and each option generates one callback: :name → name/1, :description → description/1, :input (a module that uses Normandy.Schema, defined before the use) → input_schema/1. With :input, context.input is a struct of that schema. Leave an option out and write its callback when the value depends on the struct, or to hand-write the JSON Schema map; without :input, context.input is a string-keyed map checked against that map. Do not pass an option and also define its callback.

name/1, description/1, input_schema/1 and run/2 on this module call the tool's own callbacks.