# `Issho.Tools`
[🔗](https://github.com/hattoriai/issho/blob/v0.2.0/lib/issho/tools.ex#L1)

Tools for agents, for any way an agent reaches your app. Issho's room
tools are `room/0`; the components bring theirs
(`Kotoba.Issho.tools/0`, `Hakushi.Issho.tools/0`), and you can write
your own (`Issho.Tool`).

For your app's own model, through its API: give it the tools'
definitions, and run the ones it calls as its agent.

    tools = Issho.Tools.room() ++ Kotoba.Issho.tools()
    ctx = Issho.Tool.Context.new(MyApp.Issho, assistant, on_behalf_of: current_user)

    # The `tools` of a request to the model:
    Issho.Tools.schemas(tools)

    # Each tool use in its answer:
    Issho.Tools.call(tools, name, input, ctx)

For MCP clients, serve the same tools with `Issho.MCP`.

# `call`

```elixir
@spec call([module()], String.t(), map(), Issho.Tool.Context.t()) ::
  Issho.Tool.result()
```

Runs the tool of that name with the input a model gave, as the agent of
the context. Gives `{:ok, result}` or `{:error, text}`, for the model.

# `person_of`

```elixir
@spec person_of(GenServer.server(), String.t()) :: {:ok, map()} | {:error, String.t()}
```

A person of the room, by their name (any case) or their key: their
name, and each of their sessions' awareness states, for a component's
tool that acts on what someone selected ("connect what Ada selected").
Gives `{:ok, %{name: name, key: key, states: [state]}}`, or an error in
words.

# `place_of`

```elixir
@spec place_of(GenServer.server(), String.t(), String.t()) ::
  {:ok, term(), String.t()} | {:error, String.t()}
```

Where a person of the room is in a document: their place's `"at"`, in
the document's own terms ("rewrite what Ada selected"). Gives
`{:ok, at, name}`, or an error in words.

# `room`

```elixir
@spec room() :: [module()]
```

Issho's tools for rooms: join, look around, read, point, say what you do, change, leave.

# `run`

```elixir
@spec run(module(), map(), Issho.Tool.Context.t()) :: Issho.Tool.result()
```

Runs a tool with its input, as the agent of the context.

# `schemas`

```elixir
@spec schemas([module()]) :: [map()]
```

The tools' definitions, as a model's API takes them: `name`,
`description` and `input_schema` (a JSON Schema) for each.

---

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