Test and troubleshoot tools
Try a tool with sample values, read the result, and fix invalid parameters, timeouts and failing APIs.
What you will achieve
You will confirm a tool works before an agent relies on it.
Step-by-step: test a tool
- Open the tool from Tools.
- Save changes first. The test page says "Save first, the test uses the saved version."
- In Test, enter a value for each parameter (required ones are marked with
*). - Press Run test. The result says Succeeded or Failed, shows how long it took in milliseconds, and shows what your endpoint returned (after applying Read this from the response) or the error.
If the result takes over 300 ms the page warns: "Over 300 ms, so the caller hears silence while it runs." Then consider Run in the background or a faster endpoint.
Read the logs
On the agent's Logs tab, the tools view lists how often each attached tool ran. The Settings page's API Usage tab shows tool and action usage across the workspace with recent activity.
What the agent is told when a tool fails
| What happened | The message |
|---|---|
| A required parameter was missing | "Missing required parameter(s): order_id" |
| A value had the wrong type or was not an allowed choice | "Parameter 'x' must be a integer." or "…must be one of: …" |
| The URL is private or internal | A message that it is not an allowed address |
| The service took too long | "The service did not answer within 5s." |
| The service returned 4xx | "The service rejected the request (404)." Not retried. |
| The service returned 5xx | "The service returned 502." Retried for GET, PUT and DELETE only. |
| The service redirected | "The service redirected the request, which is not followed." |
Troubleshooting
- 404 or 401 in the test. Check the URL, path parameters and authentication.
- Always times out. Raise Timeout (up to 30 s) only if the caller can wait, or use Run in the background.
- Test works but the agent never calls it. Improve the description and the system prompt.
- A POST ran once but you expected a retry. POST and PATCH are never retried, by design.
Related guides
Something here does not match what you see in the dashboard? Let us know.