# `Issho.Tools`
[🔗](https://github.com/hattoriai/issho/blob/v0.4.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, click, say what you do, your task and its steps, change, change shared state, comment, wait for what happens, read what was said to you while away, write a long answer as it comes, 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, within the
time budget of a tool call: the gestures it makes together take no
longer (`Issho.Motion`).

# `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*