Tools

What a tool is

A tool is an action an agent can take, such as saving a lead or emailing your team. The agent decides when to use a tool, and the tool decides how the work is done. You choose which tools each agent may use, and whether each one needs your approval.

There are three kinds:

• Built-in tools, ready in every agent.
• Connected app actions, such as adding a row to a sheet. See Channels and connected apps.
• Your own tools, which you build from steps. See Your own tools.

Built-in tools

These are in the agent builder today, under Tools:

Reply to the customer and Send an email are marked Sensitive, because they act outside the app, so they start with an approval step. You can change the setting for any tool. See Tasks and approvals.

Whatever a tool's setting, an agent asks first on its own once a task has read something from outside, such as a web page, and before a message with an ID number or a stray link goes out. See When your AI asks first on its own.

Your own tools

A tool of your own does one job the same way every time. You decide what it needs (its inputs), what it does (its steps, in order) and what it hands back (its output). No code is involved, and none can be added: every step is a form you fill in.

For example, an Order status tool could take an order number, ask your shop's system about that order, and return one line such as "Order A1234 was shipped on 12 September."

Open Tools and select New tool. The builder has four tabs:

• Build: the tool's description, inputs, steps and output.
• Test: run the draft with example values and see what each step did. On a wide screen, this sits next to the builder.
• Run: the form link, API examples and the tool's recent runs.
• Versions: every published version, with a way to load one back into the draft.

Changes save as you type. Forms, the API and agents only use the tool once you publish it, and they always use the latest published version.

Inputs

A tool can have up to 15 inputs. Each has a label (what people see), a key (how steps refer to it), a type and an optional description:

Mark an input Hide in run logs for values such as a PAN or an account number. The tool still uses the value, but run logs and approval requests show it as hidden.

Steps

A tool can have up to 10 steps. They run one after another, and each step can use the inputs and what earlier steps found. Steps inside a Repeat count towards the 10.

Web requests follow a few rules:

• Only https:// addresses. Values you put in the address are encoded for you.
• Requests only go to public internet addresses. Addresses inside private networks, and redirects to them, are refused.
• Redirects are followed only for GET and HEAD requests. If a redirect leads to another site, your headers are not sent there.
• A request that takes longer than 15 seconds, or an answer larger than 1 MB, fails the step.
• An error answer (such as 404) fails the step, unless you turn on Carry on if the request fails. Later steps can then check {{steps.name.ok}} and {{steps.name.status}}.

AI prompts treat the values you insert as data: the AI is told not to follow instructions hidden in a customer's message or a web page. Each AI step uses Smart (the default, fastest and lowest cost), Smarter or Smartest, and counts towards your workspace's AI spending, like agents do.

Search knowledge answers from your own material, so a tool can quote your price list or your return policy instead of guessing:

• Write what to look for, usually the customer's question, and choose how many passages to bring back (1 to 10).
• By default it searches every file on your Knowledge page. Tick some files to search only those.
• Tick a knowledge table as well and the rows that match come back as passages too.
• Nothing leaves your workspace and the search itself costs nothing. Only the AI steps that read the passages cost anything.
• Use {{steps.name.text}} to drop what it found into an AI prompt or the tool's answer.

Repeat does the same work for each item of a list, such as every order number an earlier step returned:

• Choose the list, then add the steps to run for each item. Inside them, {{item}} is the item being worked on ({{item.name}} for a field of it).
• A list with more than 20 items stops the tool with a message, instead of going on and on. Narrow the list down in an earlier step first.
• If a step fails on one item, the run stops there and says which item it was on.
• A repeat can't hold another repeat or a condition.

Using values in steps

Insert a value with Insert value, or type it in double braces:

These are plain lookups, not code: there are no calculations or functions. A value that isn't there is left empty. Each step shows its reference name (the get_order part), and renaming it updates the steps after it. After a test run, Insert value also lists the fields the answers actually had.

What each step gives later steps:

In a JSON body or result, put each {{…}} inside quotes, as in {"qty": "{{inputs.qty}}"}. A quoted value that is only one {{…}} keeps its type, so a number stays a number.

Output

The output is what the tool returns: text or JSON, built from the inputs and steps. Leave it empty to return the last step's result.

Tools that change data

A tool changes data when it has a web request other than GET or HEAD, or a connected app action that adds, updates or deletes something. The builder marks it for you and says why. Connected app actions that change data only work after you turn on This tool changes data, so nobody adds one by accident.

Tools that change data:

• ask for approval before an agent uses them, unless you choose otherwise for that agent;
• can only be run from the form by Builders, Admins and Owners;
• need a tick before a test run, because a test run really makes the changes.

A tool with an app action that can delete data always asks first when an agent uses it.

Test, publish and versions

1. Fill in example values on the Test tab and select Run test. Each step shows what it sent, what came back, and how long it took. Secrets and hidden inputs are masked.
2. Fix anything the builder lists under things to fix. You can't test or publish until the list is empty.
3. Select Publish tool. Each publish keeps a version on the Versions tab.

The tool's key (its name for agents) can change until the first publish.

Running your own tools

Every run is recorded with its inputs, each step's result, the output, the time it took and its rupee cost. Open a tool's Run tab to see recent runs.

From an agent

1. Open the agent. On the Build tab, find Your tools under Tools.
2. Choose a published tool and select Add tool. An agent can use up to 10.
3. Choose how it runs, or keep the tool's default: Ask first for tools that change data, Runs freely for the rest.

The agent sees the tool under its key, with the description and inputs you wrote. When a tool waits for approval, the request in Tasks shows the exact inputs, and approving runs the version the agent asked for. Each run shows on the task as a step.

In the agent's test chat, tools that change data don't really run. Tools that only read data do.

As a form

On the tool's Run tab, copy the form link. Anyone in the workspace can open it, fill in the inputs and run the published tool. Viewers can run tools that only read data.

Through the API

Send the inputs with a project API key. See Tool run API.

Tool secrets

API keys and tokens that your tools send to other services belong in tool secrets, not in the tool itself.

• Workspace Owners and Admins manage them under Integrations, then Tool secrets, next to your API keys. Builders see their names so they can use them.
• A secret belongs to a project. Tools use it as {{secrets.NAME}}, and only in a web request's headers, query parameters or body, never in the address.
• The value is stored encrypted and is never shown again. To change it, enter a new value.
• Run logs, test results and API answers hide secret values, even if another service sends them back.
• You can limit a secret to certain sites, such as api.myshop.in. A tool can then only send it to those sites. We recommend it.
• A secret can't be deleted while a tool uses it.

Who can do what

A tool can't be deleted while an agent uses it, in its draft or its live version. The builder lists those agents.

Safety

• An agent can only use the tools and app actions switched on for it.
• The details an agent passes to a tool are checked against what the tool accepts before it runs.
• In the test chat, replies, emails and changes in connected apps are simulated, so nothing is really sent.
• Your own tools can't run code, and their templates can't either.
• Tools stop when AI work is paused on the platform or the daily spending limit is reached. A single run stops once it has spent ₹5 or run for 90 seconds. See Limits and costs.

Later

Planned. Running a tool over many rows at once, a visual flow canvas, code steps that run in a separate sandbox, and using your own AI provider keys.