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.

Tool types

http_api, database, webhook, rag_retriever, email, calendar, ecommerce, crm, file, browser, code_execution, mcp, agent (call another agent as a tool), function (a declared function the runtime resolves) and custom.

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.
• 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.

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.

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.