Tools

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 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:

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:

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.