From 6a8b66ac4a9980ef8085886942a3de162f48bcc3 Mon Sep 17 00:00:00 2001 From: Steve Smtih Date: Mon, 28 Sep 2026 05:08:39 -0700 Subject: [PATCH 1/2] docs(tools): document the error field for Function tool responses Customers asking Ask AI and filing support tickets about custom/Function tools repeatedly ask how to report a tool failure back to Vapi -- the Server Response Format section only showed the success `result` shape. The `error` field already exists and is used elsewhere (troubleshooting guide, API-vs-Function comparison), but was never documented on the primary Function tools guide where builders land first. Adds the `error` field, its trigger semantics (presence of the field, not its content, selects Request Failed), a failure example, and the always-return-HTTP-200 rule, cross-linked to the troubleshooting guide. Does not touch the Request Format section edited in #1244 four days ago. --- fern/tools/custom-tools.mdx | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/fern/tools/custom-tools.mdx b/fern/tools/custom-tools.mdx index 145f88893..6122e165c 100644 --- a/fern/tools/custom-tools.mdx +++ b/fern/tools/custom-tools.mdx @@ -273,7 +273,12 @@ When your Vapi assistant calls a tool (via the server URL you configured), your **Breaking down the components:** - **toolCallId (X):** This is a unique identifier included in the initial request from Vapi. It allows the assistant to match the response with the corresponding tool call, ensuring accurate processing and context preservation. -- **result (Y):** This field holds the actual output or result of your tool's execution. The format and content of "result" will vary depending on the specific function of your tool. It could be a string, a number, an object, an array, or any other data structure that is relevant to the tool's purpose. +- **result (Y):** This field holds the actual output or result of your tool's execution on success. It must be a flat string -- not an object, array, or multi-line value. If your tool's output isn't already a string, serialize it (for example with `JSON.stringify`) before returning it. +- **error:** Use this field instead of `result` when the tool call fails. Vapi decides whether to speak the `Request Failed` message by checking for the *presence* of an `error` field on the result -- it does not inspect `result`'s content for failure text. `error` must also be a flat string, and a response can use `result` or `error` per `toolCallId`, but not both. + + +Always respond with HTTP 200, even when reporting a tool failure through `error`. Any other status code is ignored completely, and the assistant reports "no result returned" instead of speaking your error message. See [Troubleshoot tools](/tools/custom-tools-troubleshooting) for more response-format failure modes. + **Example:** @@ -290,10 +295,26 @@ Let's revisit the weather tool example from before. If the tool successfully ret } ``` +If the location can't be found, report the failure through `error` instead of `result` -- Vapi still expects HTTP 200: + +```json +{ + "results": [ + { + "toolCallId": "call_VaJOd8ZeZgWCEHDYomyCPfwN", + "error": "No weather data found for that location." + } + ] +} +``` + +For multiple tool calls in one request, return one result per `toolCallId`, in the same order the calls were triggered -- some can use `result` and others `error` in the same response. + **Some Key Points:** - Pay attention to the required parameters and response format of your functions. - Ensure your server is accessible and can handle the incoming requests from Vapi. - Make sure to add "Tools Calls" in both the Server and Client messages and remove the function calling from it. +- Always return HTTP 200, and use the `error` field -- not a non-2xx status code -- to signal that a specific tool call failed. By following these guidelines and adapting the sample payload, you can easily configure a variety of tools to expand your Vapi assistant's capabilities and provide a richer, more interactive user experience. From 322bac05efcd8dae2278d597430639ad51e6dc76 Mon Sep 17 00:00:00 2001 From: Steve Date: Mon, 28 Sep 2026 13:52:53 -0700 Subject: [PATCH 2/2] docs: clarify function tool result ordering --- fern/tools/custom-tools-troubleshooting.mdx | 8 +++++--- fern/tools/custom-tools.mdx | 2 +- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/fern/tools/custom-tools-troubleshooting.mdx b/fern/tools/custom-tools-troubleshooting.mdx index 367139eef..c3eae999b 100644 --- a/fern/tools/custom-tools-troubleshooting.mdx +++ b/fern/tools/custom-tools-troubleshooting.mdx @@ -219,8 +219,9 @@ Tool returns data but the assistant doesn't use it in conversation. - For multiple tools, return results in the same order as calls were - triggered, with matching `toolCallId` values. + For multiple tool calls, return a result for every call in the `results` + array. Match each result to its call with `toolCallId`. Results can appear + in any order. @@ -252,7 +253,8 @@ Some tools in parallel calls fail or return wrong results. ### Handle multiple tool responses -Return all results in the same order as the calls were triggered: +Return a result for every tool call in the `results` array. Match each result +to its call with `toolCallId`. Results can appear in any order. ```json title="Multiple tool response" { diff --git a/fern/tools/custom-tools.mdx b/fern/tools/custom-tools.mdx index 6122e165c..6e42a667a 100644 --- a/fern/tools/custom-tools.mdx +++ b/fern/tools/custom-tools.mdx @@ -308,7 +308,7 @@ If the location can't be found, report the failure through `error` instead of `r } ``` -For multiple tool calls in one request, return one result per `toolCallId`, in the same order the calls were triggered -- some can use `result` and others `error` in the same response. +For multiple tool calls in one request, return a result for every call in the `results` array and match each result to its call with `toolCallId`. Results can appear in any order. Use `result` for success and `error` for failure. **Some Key Points:**