A tool an agent uses in Issho's rooms, however it reaches your app: an MCP client (Issho.MCP), your app's own model through an API (Issho.Tools), or whatever comes next. A tool says what it does and what it takes, as a JSON Schema; it runs as the agent of an Issho.Tool.Context, under your policy, as anyone in a room does.

Issho's room tools are Issho.Tools.room/0; a component brings its own (Kotoba.Issho.tools/0, Hakushi.Issho.tools/0).

defmodule MyApp.Tools.Rename do
  use Issho.Tool,
    name: "rename_board",
    description: "Renames a board.",
    annotations: [idempotent: true]

  arg :board, :string, required: true
  arg :title, :string, required: true, max_length: 120

  @impl true
  def call(%{board: board, title: title}, ctx) do
    with {:ok, agent, _doc, _snapshot} <- Issho.Tool.Context.open(ctx, board) do
      ops = [%{"op" => "set", "path" => ["title"], "value" => title}]

      case Issho.Participant.transact(agent, board, ops) do
        {:ok, _receipt} -> {:ok, "Renamed."}
        {:error, reason} -> Issho.Tool.Context.error(reason)
      end
    end
  end
end

arg name, type, opts declares an argument; the types are :string, :integer, :number, :boolean, :any, {:array, type}, {:enum, values} and {:object, [{name, type, opts}]}, and the options required, description, min, max, min_length and max_length. call/2 gets the declared arguments with atom keys, the ones given.

call/2 gives {:ok, result} (text, or a map or list as JSON) or {:error, text}: what went wrong, in words the model reads.