Custom Tools
Give a Tool to an Agent
Assign a custom tool to an agent so it can use the tool during conversations.
Once a skill is in your toolbox, you still have to hand it to the team member who needs it. A custom tool you've created sits on the shelf until you assign it to an agent — only then can that agent actually use it when chatting with someone.
Image: The Tools step in the Agent Control Panel showing custom tool cards that can be turned on for the agent
Before you start
- A custom tool that you've already tested and saved (see Test a Custom Tool).
- An agent you want to give the tool to. If you don't have one yet, create one from the Agents page.
- An idea of which other tools and databases that agent already uses — there's a shared limit (see below).
Step-by-step
- Open the agent you want to update in the builder (Edit in the Agents center).
- Choose Tools in the left menu.
- Switch to the My Tools tab. Every custom tool you've created appears here.
- Click a tool card to turn it on for this agent. Click again to turn it off.
- (Optional) Open the tool from the card to review its description and usage notes — that's what the agent reads to decide when to call it.
- Save your changes (each section saves on its own).
Your agent can now use this tool in conversations. When someone asks for something the tool can do, the agent picks the tool, fills in the inputs from what the person said, calls the service, and uses the response in its answer.
How many tools can an agent have?
There's no limit. Each custom tool adds one tool, and all your connected databases share a single set of database tools (at most 6, depending on their permission). Still, keep the list focused: with fewer tools to choose from, the agent picks the right one more reliably — remove tools it never calls.
How the agent decides when to use a tool
Every custom tool carries two pieces of guidance the agent reads at the moment it's deciding what to do:
| What the agent reads | Where it comes from |
|---|---|
| The tool's description | The "what does this do" sentence you wrote when you created the tool. The agent uses this to decide whether the tool fits the user's request. |
| The usage notes | Notes about how and when to call the tool — including any caveats you added. The agent uses these to decide how to call it, what to be careful about, and when to skip it. |
A clear, specific description ("Looks up the status of a customer order by order number, including shipping and delivery dates") makes the agent pick the right tool. A vague one ("Gets order info") makes it guess.
Caveats show up here too
Any warnings you added when you built the tool — things like "only use this for VIP customers" or "don't call this more than once per conversation" — appear inside the usage notes under a Caveats block. The agent reads those before every call.
So if you ever want the agent to be more careful, or skip a tool in certain situations, add a caveat on the tool itself rather than trying to handle it in the agent's instructions.
What happens at runtime
When a user sends a message that matches a tool's purpose:
The user never sees the call happening — they just get an answer in plain language based on what the tool returned.
Checking which agents already use a tool
On the Custom Tools page, each tool card shows how many agents currently use it. Click the tool to see the full list.
This is helpful before editing or deleting a tool: you can see exactly which agents would be affected.
Image: A tool card showing the "Used by 3 agents" indicator
Troubleshooting
| Problem | Fix |
|---|---|
| The tool doesn't appear in the agent's My Tools tab | Open the Custom Tools page and confirm the tool is saved (not stuck in draft). |
| Turning on a tool is blocked with a "limit reached" message | The agent has used all 25 slots. Turn off tools or databases it doesn't need. |
| The agent isn't calling the tool when I expect it to | Rewrite the tool's description to be more specific about what it does and when to use it. Save, then start a new conversation to test. |
| The agent calls the tool at the wrong time | Add a caveat on the tool itself (e.g. "only use when the user asks about open orders"). It will appear in the usage notes the agent reads on every call. |
| I deleted a tool and an agent broke | Re-create or restore the tool, or rewrite the agent's instructions to no longer rely on it. |