Tools & functions

In one line. A tool (the platform also calls it a function) is a callable an agent can invoke mid-conversation — built-in toolkits the platform wires up for you, and custom API tools you register yourself. You’ll be able to. Register a custom API tool from a JSON input schema, give it default parameter values, and wire it onto an agent’s Capabilities tab. Where this lives. Studio ▸ Agent Builder ▸ Tools (/studio/.../agent_builder/tools), plus the agent editor’s Capabilities tab.

Why agents need tools

An LLM on its own can only talk. The moment your agent needs to do something it can’t reason its way to from the prompt alone — look up a row in a table, fetch a live exchange rate, search your knowledge corpus, call your order system — it needs a tool: a callable the agent can invoke mid-conversation. The agent’s model decides, turn by turn, whether to answer directly or to call a tool first, read the result, and then answer. You don’t program that decision — you give the agent good tools with clear descriptions, and the model picks.

This page assumes Core concepts and Your first agent. To use the SQL search tool you’ll want a Datasheet; for the knowledge retriever, a Knowledge collection.

There are two families:

Built-in toolkits — callables the platform wires up for you from configuration you already did. The big two: SQL search over a Datasheet (the agent writes read-only SQL against your structured table) and the knowledge retriever over a Knowledge collection (the agent embeds the question and pulls back cited chunks). You don’t register these on the Tools page — they switch on automatically when you attach a Datasheet or a Knowledge collection on the agent’s Knowledge tab.
Custom API tools — callables you register on the Tools page: an HTTP endpoint plus a description and a JSON input schema. This is how you teach an agent to call anything your business already exposes over an API.

This page is about the second family — the Tools page — because that’s the surface you operate.

Under the hood. Every tool — built-in or custom — becomes a validating function the model can call: the input schema is turned into a checked function signature, so a malformed call is rejected before your API is ever hit. Built-in toolkits map to SQL / OpenSearch retriever toolkits; custom tools map to an API-call function. You never see this — but it’s why the input schema matters so much.

The Tools page

Studio ▸ Agent Builder ▸ Tools is a two-pane shell: a list of your tools on the left, the selected tool’s detail on the right. Creating or editing a tool opens a dialog over the top.

┌───────────────────────────┬─────────────────────────────────────────────────┐
│  Tools           [⇅ sort] │   exchange-rate-lookup                    [ ⋮ ] │
│  ┌──────────────────────┐ │   Tool Name    exchange-rate-lookup             │
│  │ exchange-rate-lookup │◀│   Tool Description                              │
│  │ order-status         │ │     "Look up today's FX rate between two ISO    │
│  │ vendor-risk-score    │ │      currency codes. Use when the user asks     │
│  └──────────────────────┘ │      to convert two currencies."                │
│  [ + Tool ]               │   Snippet (generated function definition)       │
│  (empty ⇒ "No tools…")    │   ⋮ menu:  Edit   Delete                        │
└───────────────────────────┴─────────────────────────────────────────────────┘

The list is server-paged, so a Load more affordance appears when you have many tools. An empty project shows a “No tools” empty state with an inline create CTA.

Control	What it does	Notes
Sort toggle	Flips the list between newest-first and A–Z	Cosmetic only.
+ Tool (footer)	Opens the Add Tool dialog	Needs the Add Tool permission.
Tool Name (detail)	The tool’s identifier	Shown to the agent.
Tool Description (detail)	The natural-language description the model reads	The single most important field — see below.
Snippet (detail)	The generated function definition	Read-only; for your reference.
⋮ ▸ Edit	Reopens the dialog in form view	Permission-gated.
⋮ ▸ Delete	Removes the tool	Destructive; confirm. Won’t auto-detach from agents already using it.

The Add / Edit Tool dialog

+ Tool (or ⋮ ▸ Edit) opens a wide dialog with two views. A brand-new tool starts in the import view (pick a prebuilt one to start from); editing an existing tool jumps straight to the form view.

Import view — start from a prebuilt tool

When you create a tool with nothing selected, the dialog shows a gallery of prebuilt tool libraries you can clone as a starting point:

Search field — filter the cards by name.
Filter by type — narrow the grid to a tool type: API Endpoint, JavaScript, Template, Prompt, Python, Agent, Agent Tool, or UI Card.
Visibility filter — show built-in vs your custom libraries.
Clear Filters — reset both filters.

Each card shows an icon (by type), the library’s name and description, a type chip, and a Built-In / Custom chip; hovering reads “Click to import”. Click a card to import it — the dialog flips to the form view pre-filled from that library. No match shows “No libraries found”.

For a plain HTTP lookup, filter to API Endpoint and pick the closest prebuilt card; you’ll usually only need to change the URL, the description, and the input schema.

Note. Some prebuilt library types in the import grid (Agent / Agent Tool / UI Card) belong to adjacent builders and may not all be relevant to a simple API tool — for a plain HTTP lookup, stay in API Endpoint.

Form view — define the tool

Field	What it is	Why it matters
Tool Name	A short, stable identifier (e.g. `exchange-rate-lookup`)	Becomes the function name the model calls. Keep it lowercase-and-hyphens, descriptive.
Tool Description	One or two plain-English sentences: what it does and when to use it	The LLM reads this to decide whether to call the tool. A vague description = a tool the agent never calls (or calls wrongly). Say what it returns and the trigger condition.
Code editor	The tool’s definition — the API URL, HTTP method, the JSON input schema (parameters and their types), and (where the prebuilt template provides them) auth / headers	The executable contract. The input schema is what becomes the validated function signature.
Default parameter values	Pin a fixed value for any input parameter, so the model doesn’t have to supply it each call	The field-by-field part most builders miss — see below.

The input schema (the parameters)

The schema is a JSON object describing each input the tool accepts — name, type, and whether it’s required. Conceptually:

{
  "from_currency": { "type": "string",  "description": "ISO code, e.g. USD" },
  "to_currency":   { "type": "string",  "description": "ISO code, e.g. EUR" },
  "amount":        { "type": "number",  "description": "Amount to convert" }
}

At runtime the platform turns this into a validated function call: when the model decides to call your tool, it must supply values matching these names and types. A call missing a required field, or sending a string where a number is expected, is rejected before your API is hit — so a confused model can’t send garbage to your endpoint. Describe each parameter well: those per-parameter descriptions guide the model just like the tool description guides whether to call at all.

Default parameter values

Below the name and description, this section lets you pin values the model should not have to think about. Each row is:

Parameter — a dropdown restricted to the parameters in your input schema (you can only default a parameter that actually exists). A type chip shows that parameter’s type.
Value — a typed input matching the parameter’s type: string → text box, integer / number → numeric box, boolean → toggle, sensitive → a masked box with a show/hide visibility toggle (use this for API keys and tokens). An Insert variable menu lets you splice a {{variable}} placeholder (e.g. a project-scope value) into the value instead of a literal.
Remove (×) — drop the default. Add default adds another row.

Use defaults for the parts of the call that are constant for this tool — an API key, a fixed region, a version=2 flag — so the model only fills in the genuinely variable inputs.

Watch out. Put credentials in a sensitive default, never in the plain description or the URL. Sensitive values are masked in the UI and treated as secrets.

Save writes the tool. Save is disabled until the required fields (Name, Description) are present, and the input schema must parse. Once saved, the tool appears in the list and is available to attach to any agent.

Attaching a tool to an agent

A registered tool does nothing until an agent is told it may use it. You do that in the agent editor, on the Capabilities tab:

Open Studio ▸ Agent Builder ▸ Agents, select your agent, and Edit it.
Go to the Capabilities tab.
Under Tools, click + Add tool. A picker lists the tools registered on the Tools page.
Select your tool — it appears as a card under Tools (with a remove control). Add as many as the job needs.
Save Agent.

That’s the whole wiring: the tool is registered once (Tools page) and attached per agent (Capabilities tab). The same tool can power many agents.

If a tool should require human sign-off before it runs (anything that writes to your systems), configure an approval for it on the agent’s Governance tab — the per-tool approval rows live there. See Guard rails.

Where the built-in toolkits come from

You won’t find these on the Tools page — they switch on from the agent’s Knowledge tab:

Built-in toolkit	Turns on when…	What the agent can then do
SQL search	you attach a Datasheet on the Knowledge tab	Write read-only SQL against that structured table to answer data questions.
Knowledge retriever	you attach a Knowledge collection on the Knowledge tab	Embed the question, retrieve matching chunks, answer with citations.

So: structured questions → attach a Datasheet (SQL toolkit); corpus questions → attach a Knowledge collection (retriever); anything else your business exposes over HTTP → a custom API tool from this page.

Try it yourself

Studio ▸ Agent Builder ▸ Tools → + Tool.
In the import grid, filter by type API Endpoint and import a GET-style card (or the closest match). The dialog flips to form view.
Tool Name: exchange-rate-lookup.
Tool Description: “Look up today’s FX rate between two ISO currency codes. Use this whenever the user asks to convert or compare amounts in two different currencies.” Notice it says what and when.
In the code editor, point the API URL at your rate endpoint, set the method to GET, and make the input schema declare from_currency (string) and to_currency (string), both required.
In Default parameter values, add a row, pick (say) an api_key parameter, set its type to sensitive, and paste the key — it’ll be masked.
Save. The tool appears in the list with a Snippet on the right.
Open an agent → Edit → Capabilities → + Add tool → pick exchange-rate-lookup → Save Agent.
In the agent’s playground, ask “What’s 100 USD in EUR today?” and watch the transcript — you should see a tool call to your endpoint, its result, then a grounded answer.

If the agent answers without calling the tool, your description is too weak — sharpen the “use this when…” sentence and try again. That feedback loop is the whole craft of tools.

Where to go next

Skills & skill packs — reusable, bundled capabilities, a step up from a single tool.
Drive & Datasheet — build the Datasheet that the built-in SQL search toolkit queries.
Your first agent — the Capabilities tab in full context.
Guard rails — per-tool approvals and safety filters.