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.

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.

Your own endpoint

You can make an endpoint available in two ways:

Install it into your account. Any loop in the account can then use it by name. This is the usual way.
Declare it on one loop’s draft. The Tools page writes the entry for you to paste into that draft’s tools:.

1. Store its secret, if it needs one

On Tools, press New tool. Under Store a secret for a tool, give the secret a name, such as crm_key, and its value. The value is stored and never shown again. A tool sends it as Authorization: Bearer, unless the tool names another header. Storing under the same name replaces the value.

2. Declare the tool

Choose a loop on the Tools page; the form offers that loop’s permissions. Then fill in Declare a tool:

Field	What it is
Id	The name the model calls it by, such as `price_lookup`.
What it does	One line the model reads to decide whether to call the tool. Write it for the model.
Endpoint	The `https://` address plutonium.io calls.
Method	`GET` for a read with no body, or `POST` for a call that takes a body.
Authentication	No auth, or a secret you stored, chosen by name.
How it shows to a person	How the call appears in a conversation.
What it needs	The permissions it needs, chosen from the loop’s own. An install permission is never one: those belong to the platform’s own install cards.
Input schema, Output schema	JSON Schema objects for the arguments and the answer.
Its results	Leave this off unless you vouch that the model may act on the answer with no check.

When the form is complete, it shows the entry to paste and Review the install. Press Review the install, read what the tool reaches, and press Install tool. The page then opens the installed tool. Installing runs nothing: a tool is called only by a loop that you publish and that names it.

3. Use it in a loop

Name the installed tool in the loop’s record:

tools:
  - use: price_lookup

A draft uses the tool as it is now. Publishing pins it: the published version keeps the tool’s definition, its host and the name of its secret as they were, and a later re-install changes nothing for that version until you publish again. Publish refuses a name that is not installed, and a secret name that is not your account’s.

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.

LoopAssistant can also propose a change to a tool you already installed. Its card reads Update the installed tool …? and lists what changes from the installed version. 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.