Attaching Tools to your Agent and Writing Instructions
Part of: Using Tools with Your Agent (Overview) | Last reviewed: 25 Sep 2026
This guide shows you how to give an installed tool to a specific agent, and how to write the prompt instructions that tell the agent when and how to use it. Installing a tool only adds it to your workspace. No agent can use it until you attach it.
What you'll be able to do
- Attach an installed tool, or a built-in System tool, to an agent
- Write a prompt block that tells the agent when to use the tool
- Handle success and failure so the agent never improvises on a live call
Before you begin
- An installed tool: see Installing a Vendor Tool or Building a Custom HTTP Tool. Transfer and call-control tools don't need installing (see Part 1).
- An existing agent that you have permission to edit.
Part 1: Attach the tool
Step 1: Open your agent
Open the Dashboard (the top icon in the left navigation rail). Under Your Workforce, click the agent you want to edit.
Step 2: Open the Tools section
In the agent editor, the prompt is on the left and the Configuration panel is on the right. In the Configuration panel, expand Tools.
Click + Attach tool. Search for the tool you installed, or browse the System and Custom lists, then select it.
✔ Tool not there yet? Click Create a new tool at the bottom of the dialog to jump straight to the Custom HTTP Tool builder.
Step 4: Save the agent
Click Save.
Part 2: Tell the agent when to use the tool
Attaching a tool makes it available. It doesn't make the agent use it well. That comes from the instructions in the agent's prompt (the large editor on the left of the agent editor).
For each tool, add a prompt block that covers these four things:
| Cover this | What to write |
|---|---|
| 1. When to use it | The situation that triggers the tool, and when not to use it. |
| 2. What to collect first | Each value the agent needs, its format, and whether to confirm it with the caller. |
| 3. What to say afterward | How to report a successful result to the caller. |
| 4. What to do when it fails | The exact words to say, and what not to reveal or retry. |
Example prompt block
Copy this into your agent's prompt and adapt the tool name, inputs and messages.
# UPDATE TICKET
Use this when a caller asks to add information to a ticket they already have.
Do not use it to create a new ticket.
## Step 1 - Collect inputs
Ask for these one at a time. Don't proceed until you have both.
- ticketId - the ticket identifier (format: 2 letters + 4 digits, e.g. "FA1234").
If the input doesn't match that format, say so and ask again.
- comment - the note to add to the ticket.
Before calling the tool, read both values back to the caller and get confirmation.
## Step 2 - Call the tool
Call update_ticket with:
{
"ticketId": "{{ticketId}}",
"comment": "{{comment}}"
}
## Step 3 - Report the result
On success: confirm the update and read back the status message and any details
returned by the tool.
On failure: say exactly - "Sorry, we are unavailable at the moment, please
retry in a few minutes." Do not mention error codes, the tool name, or internal
details, and do not retry automatically.update_ticket) must match the tool's name as it appears in the agent's Tools section.Two rules that prevent most problems
Verify it worked
- The tool is listed in the agent's Tools section.
- The tool runs successfully from its own test panel.
- The prompt has a block for the tool that covers all four points in Part 2.
Next step
Continue with Testing and Deploying Tool Changes to check the tool behaves correctly before it reaches real callers.