# `Mojentic.LLM.Tools.Tool`
[🔗](https://github.com/svetzal/mojentic-ex/blob/v1.5.0/lib/mojentic/llm/tools/tool.ex#L1)

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

# `descriptor`

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

# `descriptor`

```elixir
@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`

```elixir
@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

# `description`

Returns the tool's description from its descriptor.

## Examples

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

# `descriptor`

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?`

Checks if a tool matches the given name.

## Examples

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

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

# `name`

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`

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"}

---

*Consult [api-reference.md](api-reference.md) for complete listing*