# Relevance AI: How to Build a Custom Tool for an Agent

*How-to — 2026-10-23 — by Mahmoud Zalt*

How to build a custom tool in Relevance AI: inputs, steps, outputs, testing as you go, and handing the finished tool to an agent.

**Short answer.** **A tool in Relevance AI is built from three parts: inputs it receives, steps it runs, and outputs it returns.** You start from Tools in the left sidebar, choose whether to invent it from a description or start from scratch, then chain steps such as LLM prompts, API calls, integrations, and code. You can run each step on its own while you build, which is what keeps the whole thing debuggable.

**About this guide.** This guide is based on publicly available information and Relevance AI's own documentation, checked on 17 August 2026. Sistava is not affiliated with Relevance AI. Interfaces and pricing change often, so confirm the current steps in their documentation before you rely on them.

An agent without tools can only talk. Tools are the part that lets it fetch a page, call an API, write to a spreadsheet, or send a message, and building good ones is most of the real work on the platform. The good news is that the anatomy is simple and never changes.

Think of a tool as a small, reliable function with a name. It takes something in, does a fixed sequence of things, and hands something back. The agent supplies the judgement about when to call it, so the tool itself should be boring and predictable.

## What is a tool, and when do you need to build one?

A tool is a single capability an agent can call, and Relevance AI's own framing is that tools are the actions agents use to get things done, spanning API calls, LLM prompts, and custom code. The agent decides when to reach for one. The tool decides what happens next.

You do not need to build one for everything. There is a pre built set covering common actions, and building from scratch only earns its keep when your sequence is specific to your business, when several steps have to happen in a fixed order, or when you want the same routine reused by more than one agent without being rewritten each time.

## Should you use Invent or start from scratch?

Both routes start the same way. Their documentation describes selecting Tools in the left sidebar and clicking New Tool, at which point you choose between generating the tool from a description or building it yourself.

- **Invent**: you describe what the tool should do and the platform assembles a first version. Best when you know the outcome but have not worked out which steps get you there.
- **Start from scratch**: you define the inputs, add the steps, and set the outputs yourself. Best when the sequence is specific and you want to know exactly why every step is there.

A sensible middle route on your first build is to invent a draft, then open it and rebuild it by hand until you understand every step. You get a working structure quickly and you still learn where each setting lives, which matters enormously the first time a step returns something unexpected.

## How do you actually build the tool?

You work through four things in order: a name and description, the inputs, the steps, and the outputs. Their documentation also has you write a short note explaining how an agent should use the tool, which is easy to skip and worth doing, because that note is what the agent reads when deciding whether this is the right tool for the job.

### Build a tool from scratch

1. **Open Tools and start a new one** — Tools sits in the left sidebar. Choose New Tool, then the from scratch route, and give it a name and description that describe the action rather than the project.
2. **Write the note on how an agent should use it** — Their builder has a field for explaining to an agent how the tool should be used. Treat it as instructions for a colleague who has never seen it before.
3. **Add your inputs** — Inputs are the data the tool needs to receive. Each one gets a type, a title, and a description, and independent tutorials note you can set a default value and rename the variable to something meaningful rather than leaving it generic.
4. **Add your steps** — Steps are what the tool does with that data. Their documentation lists LLM prompts, API calls, integrations, and code execution among the options, and steps run in the order you place them.
5. **Wire the steps together with variables** — Later steps reference earlier ones through variable syntax, so the output of a search or a scrape can be dropped into the prompt that follows it. This is the part worth slowing down for, because a mistyped reference produces an empty result rather than an error.
6. **Run steps individually as you go** — Their documentation is explicit that you can run individual steps to test while you build. Do this after every single step rather than at the end, because it turns debugging from a search into a glance.
7. **Define your outputs** — Outputs are what the tool returns when it finishes. Return the smallest useful thing. An agent handed a huge blob of text will spend tokens rereading it on every turn.
8. **Save, then run the whole thing once** — Run the finished tool end to end with realistic input before any agent gets near it. A tool that works step by step can still fail as a sequence.

The single habit that separates a fast build from a frustrating one is running each step the moment you add it. It takes seconds and it means any failure belongs to the step you just wrote. Skip it and you will be bisecting a six step chain trying to work out where the empty string came from.

## Which steps can you put in a tool?

More than most people expect, and the catalogue is the reason building from scratch is worth learning. Their documentation index groups the steps into a few recognisable families.

- **Knowledge steps**: searching a knowledge table, retrieving rows without retrieval augmented generation, and inserting, updating, or deleting rows so the tool can write back what it learned.
- **Integration steps**: named actions for services including Google Sheets, Google Docs, Google Calendar, Gmail, Slack, Trello, Confluence, and LinkedIn.
- **Web and data steps**: Google Search, extracting website content, Firecrawl for turning sites into model ready data, and browser automation through Airtop.
- **Code and API steps**: a Python step for custom logic with helper functions, and a generic API step for calling any service that is not already integrated.
- **Conversion and control steps**: converting spreadsheets to JSON, PDFs to text, files to text, and audio or video to text, plus a delay step for pacing. Their customisation documentation also covers looping and branching.

That generic API step is the escape hatch worth remembering. If a service you use is not in the integration list, you are not blocked, you are just writing the request yourself. It is the difference between a platform you outgrow and one you do not.

It is also, honestly, a lot of surface area to learn before the first useful result. That is the trade any builder platform makes, and Relevance AI makes it deliberately, in exchange for genuine control over what happens and in what order.

That trade is the one we took the other side of at Sistava. Instead of assembling a tool and then handing it to an agent, you hire an AI Employee for a role and describe the outcome in plain English. The tools are already attached to the role, so there is no build step sitting between you and the first result.

## How do you test a tool before an agent touches it?

The tool builder gives you three tabs, and each answers a different question. Build is where you construct the tool. Use runs it as a shareable form so you can feed it real input yourself. Logs shows past executions, which is where you go after something has already gone wrong.

**The Use tab is your regression test.** Every time you change a step, run the tool from the Use tab with the same three inputs you used before. If the output changes shape, you have just broken something downstream, and you will find out now rather than in an agent conversation with a customer.

## How do you give the tool to an agent?

A finished tool can be handed to an agent or shared on its own as a form. On the agent side you add it from the Tools section of the agent builder, and then the settings that matter are the ones controlling how much freedom the agent has with it.

- **Input mode**: Let agent decide, Set manually, or Tool output taken from a previous step. Setting inputs manually is the safest starting point for anything irreversible.
- **Approval mode**: Auto Run, Approval Required, or Let Agent Decide. Anything that writes to a real system should sit on Approval Required until you trust it.
- **Failure policy**: whether to retry an errored tool, how many retries are allowed, and whether the task then terminates or escalates to a human. Their documentation notes that more retries can mean more usage.

One detail that saves an afternoon later: their documentation notes the builder tells you when more than one agent is using a tool, and suggests cloning it if you want an independent variation. Edit a shared tool carelessly and you change the behaviour of every agent holding it, which is exactly the kind of surprise that is hard to trace back.

## What does running a tool cost?

Relevance AI counts an Action when an agent runs a tool, and their pricing documentation is clear that this holds whether the tool sends one email or runs a long chain of steps. Vendor Credits sit alongside Actions and cover the underlying model and tool usage.

The practical consequence is a design principle. One tool that does a coherent job costs one Action, while the same work split across four tools the agent calls in sequence costs four. Plan tiers are named Free, Pro, Team, and Enterprise, and their current pricing page holds the numbers, which move.

## Which mistakes cost the most time?

- **Building the tool before defining the output**: decide what the tool returns first, then work backwards. Otherwise you finish the steps and discover the shape is wrong for the agent.
- **Vague tool names**: the model picks tools partly by name and description, so a name that describes the action gets chosen correctly far more often than a name that describes the project.
- **Testing only at the end**: running individual steps as you add them is supported for a reason. Six untested steps is a bisect, not a bug fix.
- **One tool that does five jobs**: if you cannot name it in four words, split it. Smaller tools are easier for the agent to choose between and much easier to reuse.
- **Returning everything**: a whole scraped page as an output makes every following turn slower and more expensive. Return the extracted answer, not the raw material.

None of that is a criticism of the platform. Building tools is genuinely satisfying when the job is specific, and the step catalogue is deep enough that you rarely hit a wall. If the assembly is not the part you want to spend your week on, that is the gap Sistava fills, and the honest answer is that it depends entirely on whether you enjoy building.

## FAQ

### What is the difference between a tool and an agent in Relevance AI?

A tool is one capability, such as calling an API, running a prompt chain, or writing a row to a table. An agent is the thing that decides which tool to use and when, based on its prompt and the task in front of it. You build tools so the agent has hands, and you write the prompt so it has judgement.

### Do I need to write code to build a tool?

No. Inputs, steps, and outputs are all configured through the interface, and the step catalogue covers integrations, web content, search, and conversions without code. There is a Python step and a generic API step if you want them, but they are optional rather than required.

### Can I test a tool before giving it to an agent?

Yes, and you should. Individual steps can be run on their own while you build, and the Use tab runs the finished tool as a form so you can feed it real input. The Logs tab shows past executions when you need to work out what happened on a previous run.

### Can two agents share the same tool?

Yes. Their documentation notes the builder will tell you when multiple agents are using a tool, and suggests cloning it if you want a variation that does not affect the others. Edit a shared tool and every agent holding it changes behaviour at once.

### How many steps should a tool have?

As few as will do the job. A tool you can describe in one short sentence is easier for an agent to choose correctly, easier to test, and easier to reuse. If your sequence has an obvious seam in the middle, that is usually two tools rather than one.

### Does every tool run cost money?

Relevance AI counts an Action each time an agent runs a tool, regardless of how simple or complex that tool is, and Vendor Credits cover the underlying model and tool usage on top. Consolidating several small tools into one coherent tool therefore reduces the Action count for the same work.

## Sources

- [Relevance AI documentation, Create a tool](https://relevanceai.com/docs/tool/create-a-tool)
- [Relevance AI documentation, Tools for agents](https://relevanceai.com/docs/build/agents/build-your-agent/tools.md)
- [Relevance AI documentation index of all pages](https://relevanceai.com/docs/llms.txt)
- [Relevance AI documentation, Pricing](https://relevanceai.com/docs/get-started/pricing.md)
- [Analytics Vidhya, Build a customised AI agent without code using Relevance AI](https://www.analyticsvidhya.com/blog/2024/11/build-an-agent-using-relevance-ai/)
- [Kingy AI, Relevance AI, your gateway to custom AI agents](https://kingy.ai/ai/relevance-ai-your-gateway-to-custom-ai-agents/)

**Tags:** relevance-ai, custom-tools, no-code-automation, ai-agent-tools, workflow-builder