A tool is a small function that lives in a document. For example, a forecast tool takes {city: "Lisbon"}, asks a weather service on the internet, and returns {temperature: 21}. A page, a trigger, an agent or any other client can call it.
The tool's metadata declares type: hm://hyper.media/tool. The document holds three things: what goes in, what comes out, and the code. A tool lives directly under an app or an agent, called its host. The host lists the tool with a card embed. The app environment that runs the host runs the function. The server refuses a tool written anywhere else.
Calls are not private. The server records every call with its input and its output. Anyone who can reach the server can read those records. Never pass secrets or private data as a tool's input or output. The section "Calls are not private" below has the details.
What a tool is made of
Attribute | Value |
|---|---|
|
|
| the tool's name |
| what it does |
| a published HM struct for its input, by |
| optionally, a published HM struct for what it returns |
|
|
The code contract is one async function:
export default async function (input: Input, ctx: {app: string; publicConfig: object; privateConfig: object}): Promise<Output> {
// ...
}ctx.app is the hm:// id of the host.
ctx.publicConfig is the host's publicConfig metadata.
ctx.privateConfig is the private config that the host's server holds.
How a tool runs
A tool runs in a sandbox on its host's server. It has internet access. It has no signing key, no access to the server's Seed node and no language model. So it neither reads nor publishes documents. The caller passes in the records the tool needs, and the caller does something with the result.
Each call does the same things in order:
The server checks that the host runs on it and lists the tool.
It checks the input against inputSchema. If the input does not match, the answer names the fields the tool does take.
It checks the host's private config against privateConfigSchema. If a field is missing, the call fails and says which.
It runs the tool's latest code in the sandbox.
It checks the returned value against outputSchema.
It records the call.
The caller signs every call. The record holds who called, the tool's version, the input, the output or the error, and how long the call took. The server records a failed call too.
An app's tools run once a writer of its space has run the app. An agent's tools run whenever the agent is mounted on its server.
Calls are not private
The server does not check who asks for a tool's call records:
The signed API gives a tool's calls to any signed account that knows the tool's hm:// id, and one call to any signed account that knows the call id.
The server also gives a running app's recent calls over plain HTTP, with no signature at all.
Each record includes the full input and the full output.
So follow these rules:
Never pass a secret, such as a password or an API key, as tool input.
Never return private data as tool output.
Put the secrets a tool needs in the host's private config. The tool reads them from ctx.privateConfig, and they do not appear in the call record unless the code returns them.
Making the app's document private does not hide its call records.
Who calls a tool
A trigger of the same host. The server records the call as made by the trigger's author.
Any client, through the signed API of the server that runs the host.
The other things called "tool"
The word has three uses in these docs. They are different things.
Name | What it is | Where it lives |
|---|---|---|
Tool (this page; the agent pages say tool resource) | a Seed document with schemas and code that anyone can read and call | under an app or an agent, on the network |
Callable tool | something an agent reaches through its | in the agent's Space, at |
the content-addressed DAG-CBOR record that describes one callable tool in | the app environment's database, per agent |
So in the agent pages, "tool document" is a record inside one agent's server state. It is not a document typed hm://hyper.media/tool. An agent cannot write code into ~/tools/. When an agent makes a tool, it publishes a tool in the sense of this page, under an app or under the agent's own document. Agent tools is the reference for the verbs and the callable tools.
See also
Building an app for writing and publishing a tool.
The signed API for apps for the actions that call a tool and read its calls.
Agent tools and tool document for the agent runtime's own tools.
The app environment, which runs the sandbox.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime