Tool failures
Fix tools that are never called, return errors, time out, send the wrong values, or run twice.
What you will achieve
You will find out whether a tool fails in your service or in how the agent uses it.
Start with the test
On the tool's page, Save changes, then Run test with sample values. If the test fails, the agent will fail the same way, so fix that first. See Test and troubleshoot tools.
Symptoms
| Symptom | Likely cause | Fix |
|---|---|---|
| The agent never uses the tool | Not attached, or the description is vague | Switch it on under the agent's Tools tab; rewrite the tool's description to say exactly when to use it |
| "Missing required parameter(s): …" | The agent did not collect a required value | Describe the parameter clearly; tell the agent in Instructions to ask for it first |
| "Parameter 'x' must be a integer." | Wrong type | Fix the parameter's type, or its description |
| "The service rejected the request (401 or 403)." | Bad or missing authentication | Check the credential under Authentication |
| "The service rejected the request (404)." | Wrong URL or path value | Check the URL and path parameters |
| "The service did not answer within 5s." | Slow service | Raise Timeout (up to 30 s) or use Run in the background |
| "The service returned 5xx" | Your service is failing | Fix it; GET, PUT and DELETE are retried, POST and PATCH never |
| "Not an allowed address" | Private or internal URL | Use a public https address |
| The agent speaks a raw JSON blob | Read this from the response is empty | Pick the field the agent should read |
| An action happened twice | The caller asked twice, or the agent retried | Make the endpoint safe to repeat; POST is never retried automatically |
| Works in test, not in a call | The agent supplied different values | Read the tool results in the call's transcript in History |
Connected-app tools
Tools made from integrations (Calendly, Google Calendar and so on) fail for a different set of reasons, such as an expired connection. See Integration errors.
Testing
Make a call that should trigger the tool, then open it in History and look at the tool result under the transcript.
Expected result
The tool result in History shows the service's answer, and the agent speaks it.
Related guides
Something here does not match what you see in the dashboard? Let us know.