Custom Tools
Create tools with AI
What a custom tool is made of, and how the AI reads a service's docs, builds and tests the tools, and hands you a guide to review.
A custom tool is like teaching your agent a new skill from a manual — once it's set up, the agent can do that one job whenever it's useful: look up an order, send a message, create a contact. Your tools sit on the Integrations page, grouped under the credential each one uses. If an app offers a ready-made set, an MCP server saves you building them one by one.
Image: The Custom Tools page showing feature cards, stats, and the tool grid
What a custom tool is made of
| Ingredient | What it means for you |
|---|---|
| The address Nirvai calls | The exact place on the outside service where the action happens (an "endpoint" — like the "send message" desk at a post office). |
| A credential | A saved login for the service — Nirvai keeps it so it can act there on your behalf. Some services don't need one. |
| Parameters the agent fills in | The information the tool needs each time, like a customer ID or a search term. You decide which ones the agent fills in from the chat and which are always the same. |
| A name, description, and usage note | Plain-language labels so your agent knows what the tool is for and when to reach for it. |
The agent only ever sees the name, description, usage note, and the fields it fills in. The address, the credential and any fixed values stay behind the scenes.
Two ways to create a tool
This page covers the AI route, which suits most people: it's like asking a knowledgeable friend to read the manual and set up the gadget for you. You say what you want, the AI reads the service's documentation, sets up and tests every tool, and shows you a tidy summary before you press Create. Prefer full control, or the service is private? Create a tool manually.
Before you start
- A saved credential for the service you want to connect. If you don't have one yet, set it up in Credentials first.
- A clear idea of what you want the agent to be able to do — "list contacts, create a contact, update a contact" is much more useful than just "HubSpot stuff".
- A few minutes of patience while the AI reads the docs and tests each tool with a real call.
Step-by-step
- Open Custom Tools from the sidebar and click AI Tool Creation.
- You'll land on a page showing your saved credentials as cards — pick the one for the service you want to connect.
- Tell the AI, in plain language, what you want the agent to be able to do. The AI may show you a multi-choice question with the actions it knows about for that service — tick the ones you want.
- Wait while the AI works through the setup. It moves in stages and shows a progress timeline right in the chat.
- When the AI is done, an Open Setup Guide card appears. Click it to open the Toolkit Guide — a tidy review of every tool the AI built.
- Look over each tool card, expand the sections you want to inspect, then click the Create card at the bottom to save the whole batch to your workspace.
Image: The AI Tool Creator showing the chat view with progress timeline and toolkit result
You can chat with the AI in plain language at any point — ask it to explain what a tool does, why it picked a certain field, or to add another tool. It's a real conversation, not a fixed wizard.
What the AI is doing while you wait
The AI works in stages, in small batches, so it can keep going even on big toolkits. You see each stage in the chat as it happens.
| Stage | What's happening |
|---|---|
| Search | Looking up the service's documentation online. |
| Fetch | Reading the actual documentation pages to find each address that does one thing. |
| Configure | Setting up each tool — the address, the kind of request, and which fields the agent should fill in. |
| Test | Making a real call for each tool using your saved credential. |
| Validate | Marking which tools passed the test, and adjusting the ones that didn't. |
If a test needs a real value from your account (like an existing order ID), the AI will pause and ask you for one — in the chat — before continuing.
Reading the Toolkit Guide
Each tool the AI built shows up as a card. Most cards have these pieces:
| Piece of the card | What it tells you |
|---|---|
| Request-type badge | The kind of request — GET, POST, PUT, PATCH, or DELETE — so you can tell at a glance whether the tool reads, creates, updates, or deletes. |
| Name and description | What the tool does, in the words your agent will read when deciding whether to use it. |
| Warnings | Coloured notes the AI left behind. Three levels: info (just so you know), warning (a real limit your agent needs to work around), and critical (review before creating). The agent sees these at runtime too. |
| The address Nirvai calls | The exact place the tool goes — useful if you want to double-check it against the service's docs. |
| What the AI will fill in | An expandable list of every field — its name, type, where it goes (path, query, header, body), and whether the agent fills it in or it's always the same. |
| Sample answers | A preview of what the tool actually returned during testing — images show inline, short documents render in place, larger files show as links. |
| Test result | Whether the test passed or failed, with an expandable section to see the full answer the service sent back. |
When you're happy with everything, click Create and the whole batch is saved to your workspace.
Tips and good-to-know
You can come back and add more tools later. Sessions are saved automatically — open Custom Tools, find the in-progress session, and pick up where you left off. Your chat, configurations, and test results are all preserved.
You can create tools for several services in one sitting. After finishing one batch, click Keep working with AI on the completion screen, point the AI at a different credential, and start a fresh toolkit. Each service becomes its own group.
Read the warnings on each tool card before clicking Create. A "critical" warning usually means the tool only works in a sandbox, requires extra app review, or has a non-obvious gotcha your agent should know about.
Troubleshooting
| Problem | What to check |
|---|---|
| The AI says it can't find docs for the service | The service may not have a public, indexed documentation site. Try the manual route — see Create a tool manually. |
| A tool keeps failing its test | Open the test result on that card and read the answer the service sent — it usually says exactly what's wrong (a missing field, an expired credential, a permission you don't have). Then ask the AI in the chat to adjust and retry. |
| The AI asks for an ID and I don't have one | Paste any real example from your account (an existing order, contact, or record). The AI just needs something real so the test call has a chance of succeeding. |
| I changed my mind about a tool | In the Toolkit Guide, you can ignore tools you don't want — only the ones you keep are saved when you click Create. You can also ask the AI in the chat to remove or change one. |
| I started over and lost work | Use the Restart button only when you really want a clean slate — it clears the whole session. To keep progress, just close the page; the session is saved. |
What's next
- Create a tool manually — wire up one tool by hand, with full control over every field.
- Give a tool to an agent — assign your new tools to the agents that should have them.