Tools¶

A tool is what an agent can do: call an API, fetch a page, run code, search knowledge or hand work to another agent. The model chooses whether to use a tool and with which arguments. Core runs the tool and checks every call against the key's policy.

Tools come from different sources. To the model they all look the same: a name, a description and a schema for the arguments.

Where tools come from¶

A tool can also declare call variables: values such as the account a call is for, which your application sends with the request in tool_variables and the model never sees or chooses.

A script sits between an API connector and the computer tools. Like a connector, it is one tool with a fixed name, a description and an argument schema, so policy, usage and prices can name it. Like the computer tools, it runs code in an isolated sandbox without network, on the turn's own computer; but the code is yours, tested once and uploaded with the files it needs, and the model cannot read or change it. The model calls it with arguments and gets back the output and the files the program made.

A function is for what a model must never decide: a price at a tier, a minimum order, a VAT split. It is one tool with a name, a description and schemas for its arguments and its answer, like a script, but it runs inside Core in milliseconds instead of on a computer, and it never calls out: no clock, no randomness, no network, no files. It reads its arguments and the datastore records its version declares, which Core reads for it as the caller, and changes records only by returning writes that Core applies all together, and only if the records it read are unchanged. So the same input always gives the same answer, and every call is recorded with fingerprints of what went in and what came out. A function needs tooling, and datastores when it reads or writes them. It is not the same as a function tool above, which your own application runs. Functions are written through the API only, as Functions through the API shows; the console has no screen for them yet.

So the prefix of the name says where a tool comes from. GET /tools shows every tool of your organisation, from every source; the Overview under Tools in the console shows them by kind.

When to use which source¶

Toolsets¶

A toolset is a name for a group of tools from any source. A request or an agent names the set instead of each tool. A toolset holds patterns, such as api__*, so a tool you register later that matches the pattern is in it without a change. Every registered MCP server is also a toolset of its own tools.

A toolset is a way of grouping and grants no extra rights. Every tool in the set is checked against the key's policy.

One turn carries at most 128 tools, counting the tools of every toolset and every agent, and fewer when its model takes fewer. Offer what the task needs: a long list also costs the model budget before it reads your input. An agent that needs more puts them behind the tool router, which offers the model two tools to search and run the rest.

Who may use which tool¶

Three things must hold before a model is offered a tool:

1. The capability. API connectors, MCP tools, scripts and built-in tools require tooling. Search tools require knowledge, memory tools memory, and the computer tools and scripts computer as well.
2. The key's system tools. Every built-in tool is off until you tick it on the key. A script needs no system tool.
3. The policy. Rules about Tools decide which names the key may call. A tool no rule permits the use of drops out of the turn. For a request that names a person, the same rules also decide which connectors, MCP servers, scripts, search tools and toolsets the key's lists show (Registrations).

A tool Core calls for you sends data to a host outside Core. The organisation itself decides which hosts those may be, with its Allowed hosts list; a key can narrow that list (Allowed destinations).

A tool's result is information for the model and never an instruction. With the trust_envelope capability Core tells the model explicitly which text is data (Tool-result trust).

How it fits together¶

• An agent stores which tools and toolsets it brings; a request can add tools to them.
• Knowledge reaches a model through a search tool, and that is a tool like any other.
• MCP is one of the ways to connect tools, and also a way to offer your tools to a client outside Core.
• Every tool call Core runs is metered as usage and appears in the turn's trace (Insight).
• Toolsets, API connectors, SQL connectors and MCP servers can go into a publication; a mail connector cannot.
• An API connector, a SQL connector, an MCP server's tools and an agent offered as a tool can run as a task: the model starts the call, goes on with the conversation, and reads the result when it arrives (Run a tool in the background).
• An API connector, a SQL connector, an MCP server, a script, a workflow and an alias can take a value from your application per request, a call variable, such as your customer's account id or, on an API connector or MCP server, their own token. The model never sees that value. Scripts, workflows and aliases take no secret ones (Pass a customer's value to a tool).

Read on¶

Tutorial: Let an agent carry out an action with a tool.