Creating Tools

Shell Tools (TOML — easiest)

No Elixir needed. Define a command template:

.annihilation/tools/docker_status.toml

[tool]
name = "docker_status"
description = "Check status of Docker containers"
command = "docker ps {{#if name}}--filter name={{name}}{{/if}} --format '{{.Names}}\t{{.Status}}'"

[parameters]
name = { type = "string", description = "Filter by container name" }

The system generates an Elixir module from this at runtime.

Elixir Plugin Tools (full control)

.annihilation/tools/db_query.ex

defmodule DbQuery do
  @behaviour Annihilation.Tool.Behaviour

  def name, do: "db_query"
  def description, do: "Run a read-only SQL query against the dev database"

  def parameters_schema do
    %{
      "query" => %{"type" => "string", "description" => "SQL query (SELECT only)", "required" => true}
    }
  end

  def validate(%{"query" => query}) do
    if String.match?(query, ~r/^\s*SELECT/i) do
      :ok
    else
      {:error, "Only SELECT queries are allowed"}
    end
  end

  def execute(%{"query" => query}, _call_id, _agent_pid) do
    # Your implementation here
    %Annihilation.ToolResult{
      tool_call_id: nil,
      content: "query results...",
      is_error: false
    }
  end
end

Tool Discovery

Tools are loaded from three locations (later overrides earlier):

1. Built-in — lib/annihilation/tools/
2. Global — ~/.annihilation/tools/*.ex and *.toml
3. Project-local — $PROJECT_ROOT/.annihilation/tools/*.ex and *.toml

Parameter Schema

Use a JSON Schema subset for parameters_schema/0:

• Supported types: string, integer, number, boolean, array, object
• required: true marks mandatory parameters
• enum: [...] restricts to specific values
• Extra/unknown parameters are ignored (lenient validation)