Test a Custom Tool
Testing a custom tool is like ringing a doorbell before mailing the invitation — you want to know somebody's home before you commit. One quick test confirms that the connection works, your sign-in details are accepted, and the service answers the way you expect.
Image: A successful test showing the status code and response data
Before you start
- A custom tool that's been filled in (either built manually, started from a template, or built with the AI Tool Creator).
- A saved credential (sign-in details) selected on the tool.
- A few sample values you can use as inputs — real values from your account work best (a real contact ID, a real channel name, etc.).
What a test actually does
A test makes one real call to the service using the web address, the request method, and the parameter values you provide. It's the same call your agent would make later — nothing is faked.
| Where you test | How it shows up |
|---|---|
| AI Tool Creator | The AI tests automatically while it builds the tool and shows you the result. |
| Manual creation | The second page of the wizard has a Test button. |
| Templates | Same as manual — fill in your values on the test page, then run it. |
| An already-saved tool | Open it from the Custom Tools page and run a test from the same page. |
Step-by-step
- Open the test page for your tool.
- Fill in a sample value for every parameter. These stand in for what the agent would normally pick at runtime — pick values you know exist in your account.
- Click Test.
- Wait a moment for the service to respond. The result appears underneath.
- Read the result (see "Reading the result" below).
- If it failed, fix the cause and run the test again. Keep going until the test passes.
- Once the test passes, save the tool.
For your first test, pick a parameter combination that only reads data (like a "get one record by ID" call). It's safer than a test that creates or deletes something, and it still proves the connection works.
A test that creates, changes, or deletes data does so for real in the connected service. Use sample or sandbox values when you can.
Reading the result
The result shows up as either pass or fail, along with a preview of what the service sent back.
Pass
A pass means: the service was reached, your credential was accepted, your parameters were valid, and a real response came back. The response preview shows the actual data — scroll through it to make sure the fields you expected are there.
Fail
A fail means one of three things is off. Check them in this order:
- The parameter types. Numbers sent as text (or the other way around) are the most common cause of a fail. Open the parameter list and confirm each one is set to the right type (text, number, yes-or-no).
- The web address. Look for typos, missing slashes, or a path piece like
/contacts/{contact_id}that wasn't filled in. - The credential. If the response talks about authorization, your sign-in details might be expired or the wrong account. Re-authorize the credential in Credentials.
After fixing the cause, run the test again.
Image: A failed test showing an error message
Attach a sample output (optional)
Once a test passes, you can attach a sample of the response to the tool so reviewers (and you, later) can see at a glance what kind of answer the tool returns. The supported sample formats are:
| Format | Use for |
|---|---|
| image | A screenshot or an image the service returns |
| A document the service returns | |
| markdown | A formatted text response |
| json | A structured response — fields and values |
| file | Anything else the service might return |
The sample is shown alongside the tool when you (or a teammate) open it for review later. It doesn't change how the tool runs — it's just a preview.
Troubleshooting
| Problem | Fix |
|---|---|
| The test button is grayed out | A required parameter is empty, or no credential is selected. Fill in every required field and pick a credential. |
| The test passed but the data looks wrong | Check that you picked the right credential (sometimes there are two accounts), and that the parameters point to the record you expected. |
| The test fails only for one parameter combination | That specific record might not exist in your account. Try another sample value that you know exists. |
| The service answers "too many requests" or asks me to wait | You've hit how many requests the service allows in a short window. Wait a minute and try again. |
| Everything looks right but the test keeps failing | Re-open the credential in Credentials and re-authorize it — it may have expired. |
What's next
Once your tool tests cleanly, hand it to an agent.