# Tools

> The built-in tools a run can call, and how to give your loops your own HTTP endpoints — installed once, used by many loops

A **tool** is something a run can call. Every run has the platform's built-in tools that its
role allows, and you can add your own: an **endpoint tool** is your own HTTP endpoint, which
plutonium.io calls for the run. A loop gets only the tools whose permissions it holds. A tool that
needs a permission the loop does not hold is left out, so no run can call it.
[Permissions and trust](/docs/guide/permissions-and-trust.md) lists what each built-in tool needs.

## Built-in tools

These come with the platform. A run holds the ones its agent's role and its loop allow. You do
not list a built-in tool under the loop's `tools`: add the permission it needs to `capabilities`.
Saving a draft that lists one under `tools` is refused, and the refusal names that permission.

| Tool | What it does |
|---|---|
| `ask_user` | Asks the user a question and waits for the answer. |
| `request_inputs` | Shows the user a form for the inputs the loop declares. |
| `notify_user` | Sends a note. |
| `read_file`, `list_dir` | Read files in the loop's workspace. |
| `records_query`, `records_put` | Read and write records in the loop's collections. |
| `finish` | Ends the run when the job is done, with the loop's closing line. Not beside a refused proposal: the run goes on so the model can fix it. |

## Your own endpoint

On **Tools**, press **Add a tool** and answer its questions:

| Question | What it sets |
|---|---|
| **What should it be called?** | The tool's name, such as *Order lookup*. Your assistant calls it by a name made from it, such as `order_lookup`; **More options** lets you change that name. |
| **When should your assistant use it?** | One line your assistant reads to decide when to call the tool. Say what it is for, in at most 300 characters, and name no site other than the tool's own: every run that uses the tool reads it. |
| **What address does it call?** | The `https://` address plutonium.io calls. |
| **Does it only look things up, or does it change something there?** | *It only looks things up* calls with `GET`, and a loop that uses it is allowed to call the addresses of your own tools (`call_endpoint`). *It sends or changes something* calls with `POST`, and a loop that uses it is allowed to send things outside Reactor (`send_external`). |
| **Does that address need a key?** | No, or yes: choose a key you saved, or save a new one with a name to find it by, such as `crm_key`. A key is kept encrypted, never shown again, and sent as `Authorization: Bearer`. Saving under a name you used before replaces that key. |
| **What does it need to be told?** | Each input a run sends it: a name, its kind (text, number, yes/no or date), and whether it is always needed. **Write the JSON yourself** opens the JSON Schema instead. |
| **Which loops may use it?** | Your own loops. Beside a chosen loop that is not yet allowed what the tool needs, the form says so; whether the loop can be allowed it is checked after **Add tool**, before anything changes. Choose none to keep the tool only in your account for now. |

**More options** holds what a person sees when the tool runs, whether a run may act on its answers
without a check (leave this off unless you vouch for the address), and what it answers, as JSON.

Press **Check the tool**, read what it reaches, and press **Add tool**. The tool is now in your
account, and the page opens it. For each loop you chose, plutonium.io adds the tool to that loop's
waiting change, and starts one when the loop has none; it gives the loop the permission the tool
needs when the loop lacks it. The page says what it did for each loop, or why a loop was not
changed, with a **Review and publish** link. Nothing runs differently until you publish: a tool is
called only by a loop that you publish and that uses it, and the Publish card shows the new
permission before you press.

A tool's page lists the published loops that use it. **Let another loop use it** asks the same
question for a tool already in your account. As you choose each loop, the page checks it and says,
before you press **Let them use it**, what stands in its way and how to fix it: for example, a
loop that reads your collections or the web cannot also use a tool that changes things, and a loop
strangers open cannot use one at all. A loop with something in its way is not changed. When a
loop's own agent may not send or change things itself, plutonium.io gives the loop a helper, the
**Service writer**: the loop's agent hands it each call, it reads nothing but what it was handed,
and the page says it was added.

Each call of a tool that sends or changes things waits for an approval, so the page also asks who
approves it: **You** (the default) or **The person in the chat**. The person in the chat is
offered only when every chosen loop allows it; on a loop strangers open, only you can approve.

When you add such a tool from **Add a tool** with loops chosen, the tool's page opens on the same
question with those loops chosen, and nothing is added to them until you answer it. A tool that
only looks things up is added to its loops at once.

A tool added before every tool had to need a permission shows "names no permission" on the Tools
page. A loop that uses it is refused at its next publish, and no run of a loop without the
permission can call it. Change the tool to need what its method calls for.

A few older tools live inside one loop only; the Tools page lists them as **Only in** that loop.

### Using a tool in a loop's document

A loop's document names a tool from your account with `use`:

```yaml
tools:
  - use: order_lookup
```

**Publishing pins it**: the published version keeps the tool's definition, its address and the
name of its key as they were, and a later change to the tool changes nothing for that version until
you publish again. Publish refuses a name that is not in your account, and a key name that is not
your account's.

## Tools from a service's API docs

On **Tools**, press **Add tools from API docs**. It opens a chat with **ConnectionAssistant**.
Tell it the service and the address of its API documentation. It reads the docs, checks the tools
you already have, and proposes one tool for each endpoint you want, each on its own card.

- **The first read of a site asks you first.** A card names the site, and ConnectionAssistant
  reads nothing there until you allow it.
- **It proposes tools that read.** Each one uses `GET`. A tool proposed in a run that read a web
  page must read: any other proposal is refused before a card is drawn, and the refusal says so.
  A tool that changes something in the service is yours to add with **Add a tool**.
- **It never asks for a key.** A tool that sends one names a secret. Save the key under that
  name on **Add a tool**, under **Does that address need a key?**, and the tool sends nothing
  until you do. When the docs say the service needs no key, the tool names none.
- **Google, Slack, Notion and Linear are connections, not tools.** For those, it tells you to
  connect the service on **Connections**, with a link to it, where its tools come with the
  connection.
- **A docs page is outside content.** ConnectionAssistant reads it through a reader that cannot
  act, and treats what it says as a description of the service, never as an instruction. You
  approve each tool's address and description on its card before it is installed. When a tool
  calls a different site from the docs it was written from, its card says so under **Check
  before you approve**.

Approving a card installs that tool and runs nothing. A loop uses it when LoopAssistant builds or
changes a loop that names it.

## What a run does with an answer

An answer from your endpoint is **untrusted** unless the tool says otherwise: the model reads it
with the same care as a web page. To bound how much a run accepts, add a check to the loop's
record:

```yaml
checks:
  - kind: tool_result
    tool: price_lookup
    max_bytes: 4000
```

An answer over the bound is refused, and the model reads a sentence that names the limit.

## Code tools

A **code tool** runs JavaScript in a sandbox, and reaches only the `https` hosts it declares.
The Tools page form does not install code tools: LoopAssistant proposes one on a card, and you
approve the card to install it.

**A proposed tool's card shows what the tool calls and what a run sends it**: the full address,
its host in bold, and each input with its type, marked *optional* where the tool can do without
it. The description is shown as LoopAssistant wrote it. When the run read web pages before it
proposed the tool, the card names their sites at the top, taken from the pages the run fetched and
never from the model's words. Check the address and the inputs against what you asked for before
you press **Install tool**.

**LoopAssistant can also propose a change to a tool you already installed.** It first reads the
tool as installed, and proposes the whole tool from that read with only what you asked changed,
so a key you did not mention, such as the endpoint, stays as it is. If the tool changed after
that read, the proposal is refused and LoopAssistant reads it again. Its card reads
*Update the installed tool …?* and leads with what changes from the installed version; **Show
the whole tool** opens its description and its code. Approving
replaces the installed version. A loop you already published keeps the version it was published
with until you publish it again. A proposal identical to the installed tool is refused, and
LoopAssistant uses the tool by name instead.

## Tools on your own page

A **client tool** is an action your own web page performs for the user, such as opening a page
of your app. See [Embedding the Chat](/docs/guide/embedding-the-chat.md).

## Tools on your own machine

A **host tool** is an action your own machine performs for a loop, through `rxr`: it reads a
file, writes one, or runs a command that a file on that machine lists. No visitor's run can
call one. See [Tools on Your Own Machine](/docs/guide/your-machine.md).
