Tools

Tools give agents the ability to act and to fetch live data. They are created under Tools and attached to agents (Tools tab), to apps, or to a specific toolbox node.

#Toolboxes: grouping tools

A toolbox on the Tools page is a named group of related tools, for example all the order tools of a shop, the way a knowledge base holds documents. A tool is in one toolbox or in none, and you can move it at any time: pick the toolbox on the tool's own page, use Add existing tools on the toolbox's page, or create the tool from the toolbox's page so it starts there. Deleting a toolbox keeps its tools; they are simply in no toolbox.

Toolboxes only make picking easier. In an agent's Add tools picker you can tick a whole toolbox, tick some tools inside one, or pick tools that are in no toolbox; the agent then gets each picked tool on its own, exactly as if you had added them one by one. Moving a tool to another toolbox later does not change any agent. (Not to be confused with the toolbox node of a workflow, which is where a run's tools are bound.)

#Tool types

Tools → New tool offers the types that run end to end:

• HTTP API: calls a REST endpoint from a request template.
• Webhook: posts an event to a URL.
• RAG retriever: searches a knowledge base as a tool.
• Browser: fetches, searches or extracts from web pages.
• Shopify store: one action on a linked Shopify store, such as searching products, looking up an order or adding to the shopper's cart (Shopify store assistant).
• Chat window event: fires an event in the visitor's own page, where your code answers it; the answer is the tool's result (see "Chat window events" below).

A tool created earlier with a type that is no longer offered keeps showing its own type. Types that would act on the AgentRow server itself (file, database, code execution, and calling another agent as a tool) are disabled for every organisation (Guardrails, approvals and safety).

#What a tool defines

• Name and description. The model reads the description to decide when to call the tool, so write it for the model: what the tool does, what it needs, what it returns, and when to use it (for example "use this first when you only know a place name").
• Input schema and output schema (JSON Schema). Arguments the model must provide and the shape of the result.
• Configuration for the type: for an HTTP API the method, URL, headers, query and body templates.
• Auth type: none, API key, bearer token, basic, OAuth2, custom header, a stored connection, or end user token (the signed-in end user's own token is forwarded as the credential, so the tool acts as that user).
• Safety level: safe read, sensitive read, write safe, write sensitive, destructive.
• Identity placeholders: {{auth.user_id}}-style placeholders in the URL, headers, query params or body take the signed-in end user's claims (for example ?organisation_id={{auth.organisation_id}}), so a tool can be scoped to the person asking. A tool whose placeholders the run cannot fill is withheld from the model and reported; the end user's access token itself can never be templated.
• Parameters: path placeholders such as {order_id} become inputs; each query parameter has a value or {placeholder} template, a description for the model and a required switch. The generated input schema tells the model which inputs it may leave out, and an optional input it leaves out is dropped from the request rather than sent as a literal placeholder. For a parameter filled from the signed-in user's claim ({{auth.organisation_id}}) the switch says whether the run must carry that claim: checked, the tool is withheld from the model without it; unchecked, the parameter is left out of the request. A path parameter can never be left out.
• Limits: timeout, retry policy, rate limits, requires approval, read-only flag.
• Widget events: whether end users in the widget see this tool's activity as hidden, a status line, or full detail.
• Widget icon and label: the icon (one of the set, or your own SVG) and the label the widget shows on this tool's activity line instead of the tool's name.

#Chat window events

A Chat window event tool lets the agent ask the page the widget is on to do something — open the booking calendar with a date filled in, read the product the visitor is looking at, add to a cart on a non-Shopify shop, prefill a form, start a checkout — and get the page's answer back as the tool's result. Nothing about the page reaches AgentRow except what your code returns.

The tool names the event (for example book_demo), its mode and its wait, and has an input schema like any tool (what the model fills in). On the page, your code registers a responder for the event:

AgentRow.onEvent("book_demo", async (input) => {
  const slot = await openCalendar({ date: input.date });   // your page's code
  return { booked: true, when: slot };                     // the tool's result
});

• Wait mode (1–60 seconds, default 20): the agent's call waits for the answer. No answer in time, a failing responder, or a page without the responder are named errors the agent carries on from — never a silent failure.
• Async mode (60 seconds to 24 hours, default 10 minutes): the call returns at once and the agent tells the user it will follow up. The page answers whenever it is done (its responder may return ctx.later() and answer later with AgentRow.respondToEvent(ctx.id, result)), or your server answers with the app secret (POST /api/app/server/events/{id}), for work that outlives the page. The answer starts a follow-up turn: at once when the conversation is idle, after the run in progress otherwise; no answer before the deadline tells the agent so. The outcome itself is never shown to the visitor — the agent's reply is what they read — and stays in the run's trace and the Inbox as an "Event" record.
• The widget tells AgentRow which events the page listens for with every message, so the tool binds only on pages that have the responder — not in Slack, server runs or pages without it; the trace shows it withheld with the reason.
• Answers come from the visitor's browser, so treat an event result exactly as a user message: data, never identity or permission. Only the conversation's own session can answer, requests expire, inputs and answers are capped at 16 KB, and the builder fixes the event names.
• In the dashboard's test chat there is no host page: a fired event shows a card and the builder answers it as the page would.

The Shopify store's cart tools work the same way under the hood but need no code from you: the storefront widget answers them itself (Shopify store assistant).

#Addresses a tool may call

HTTP API, Webhook and Browser tools call only public internet addresses, over http or https. A URL that points at localhost, a private network or another internal address is refused when you save the tool. Every request is checked again when it runs, including each redirect, because a public name can resolve to a private address. A refused call fails with a named OUTBOUND_… error: the model receives it as the tool result, and the tool call in the run's logs records it. Run test on the tool's page goes through the same checks. Guardrails, approvals and safety lists what is refused.

#How tool results reach the model

Large results are compacted: the model receives a preview plus a handle such as "#641". The full result is stored and the model can read any part of it with the built-in tool_history tool, paging by character range. The most recent tool-calling turn of a conversation is replayed to the model as compact pairs so it remembers what it already fetched, and it is told not to fetch the same thing again.

#Tool selection: all, vector or hybrid

A toolbox can bind every attached tool to each model call (all), or select the most relevant ones per message using embeddings of the tool descriptions (vector, or hybrid with keyword matching). With selection on, the toolbox binds up to max tools, plus any pinned tools that are always present.

A tool's description is embedded when the tool is saved, once per embedding provider of the organisation. The tool's page lists each provider under Embeddings as embedded or failed, with the reason. A provider that fails, for example one at an address AgentRow does not call, does not stop the others or the save; Re-embed tries again.

The built-in search_tools lets the model widen its own tool set: it can ask for a tool by exact name or describe the capability it needs, and the matching tools become callable on its next turn. The model is shown, as a JSON object, which tools are bound right now and which are not bound yet with the exact call that binds each. A tool that is not bound cannot be called directly; the call returns an error telling the model to search first.

#Authenticated tools for signed-in users

When an app's end user signs in with an identity token that carries a tool token, tools with the end user token auth type forward that token. Those tools bind only when the run has a signed-in user, so an anonymous visitor never triggers them.