Give a Tool to an Agent
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 Control Panel and select the agent you want to update.
- Click the Tools step in the agent's setup.
- 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 the agent.
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.
The shared 25-tool limit
Every agent has a budget of 25 tool slots. Custom tools and database connections both come out of the same budget.
| What you give the agent | Slots used |
|---|---|
| One custom tool | 1 |
| A read-only database connection | 2 |
| A write-only database connection | 5 |
| A full read-and-write database connection | 7 |
So an agent with a full database connection (7) and three custom tools (3) is using 10 of the 25 slots. If you try to turn on a tool that would push you over 25, the page will tell you which ones to turn off first.
If your agent is bumping into the limit, look for custom tools it never actually calls. Removing those usually frees up enough room for the ones that matter.
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. |