From c5c4729dccfe2f24923dc05ac77ec1ed09b1f92b Mon Sep 17 00:00:00 2001 From: Chiranjeet Mishra Date: Thu, 10 Sep 2026 03:01:13 +0000 Subject: [PATCH 1/2] docs: maxTokens is a model property, not a tool property The custom tools troubleshooting page told readers to set maxTokens on a tool, in three code blocks and in the debugging table. The API has no such field, so pasting the page's own example back returns 400: POST https://api.vapi.ai/assistant {"message":["model.each value in tools.function.property maxTokens should not exist"],"error":"Bad Request","statusCode":400} Reproduced 2026-09-10. A report of this arrives with an assistant.model prefix when the payload is nested under an assistant key; a direct POST roots at model. Same validator. Per https://api.vapi.ai/api-json, OpenAIFunction accepts only name, strict, description and parameters, and JsonSchema, used for each property, accepts only type, items, properties, description, pattern, format, required, enum and title. maxTokens is defined on the model schemas alone, with a range of 50 to 10000 and a default of 250, so the token truncation section now points at model.maxTokens and states the real default. The page previously said the default was 100, which is not a value the API has anywhere. Co-Authored-By: Claude Opus 5 (1M context) --- fern/tools/custom-tools-troubleshooting.mdx | 30 +++++++++------------ 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/fern/tools/custom-tools-troubleshooting.mdx b/fern/tools/custom-tools-troubleshooting.mdx index b46eb6ad2..54b679f1d 100644 --- a/fern/tools/custom-tools-troubleshooting.mdx +++ b/fern/tools/custom-tools-troubleshooting.mdx @@ -31,7 +31,8 @@ Start with the most common issue for your symptoms: format problems - **Symptoms:** Tool parameters or responses truncated Increase token limits + **Symptoms:** Tool parameters or responses truncated Increase the model + token limit @@ -83,8 +84,7 @@ Add `strict: true` to catch validation errors early: "parameters": { // ... your parameters }, - "strict": true, - "maxTokens": 500 + "strict": true } ``` @@ -225,20 +225,17 @@ Tool returns data but the assistant doesn't use it in conversation. Tool parameters or responses are getting cut off. -### Increase token limits +### Increase the model token limit -The default token limit is only 100. Increase it for complex tools: +Tool call arguments are generated by the model, so they draw on the same +per-turn token budget as speech. Raise `maxTokens` on the assistant's `model`, +not on the tool. It accepts a value from `50` to `10000` and defaults to `250`. -```json title="Tool configuration" {7} -{ - "name": "complex_tool", - "description": "Tool that needs more tokens", - "parameters": { - // ... your parameters - }, - "maxTokens": 500 // Increase from default 100 -} -``` + + `maxTokens` is a model property, not a tool property. Setting it inside + `tools[].function` is rejected with `400 Bad Request` and the message + `assistant.model.each value in tools.function.property maxTokens should not exist`. + Look for "Token truncation warnings" in your call logs to identify when this @@ -366,7 +363,6 @@ Tool behavior doesn't match your expectations. "required": ["param1"] }, "strict": true, - "maxTokens": 500, "async": false } ``` @@ -389,5 +385,5 @@ Look for these key error messages in your call logs: | "Tool call ID mismatches" | toolCallId doesn't match | Ensure exact ID match | | "HTTP errors" | Webhook not returning 200 | Return HTTP 200 always | | "Schema validation errors" | Missing required parameters | Check required array | -| "Token truncation warnings" | Need more tokens | Increase maxTokens | +| "Token truncation warnings" | Need more tokens | Increase `model.maxTokens` | | "Response parsing errors" | Malformed JSON/line breaks | Fix JSON format | From 27b043f743f4885bdedabcd26b98fe81aa31734d Mon Sep 17 00:00:00 2001 From: Chiranjeet Mishra Date: Thu, 10 Sep 2026 03:11:45 +0000 Subject: [PATCH 2/2] docs: make the complete tool configuration template a valid payload The "Complete tool configuration" template on the custom tools troubleshooting page is not a payload the API accepts. Pasted as a tool it returns 400 twice over, reproduced against POST https://api.vapi.ai/assistant on 2026-09-10: as written model.each value in tools.type must be one of the following values: dtmf, endCall, ... function, mcp, apiRequest, ... with type added, function wrapper still missing model.each value in tools.property name should not exist name, description, parameters and strict belong inside function; type, async and server sit on the tool. The template had them all flat, so it was missing both the discriminator and the wrapper. The corrected template validates: posted with a deliberate unrelated error to force rejection, the tool itself produces no validation failure. server is optional and is included because a custom tool without one has nowhere to send its tool-calls webhook, which is the subject of this page. Co-Authored-By: Claude Opus 5 (1M context) --- fern/tools/custom-tools-troubleshooting.mdx | 33 +++++++++++++-------- 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/fern/tools/custom-tools-troubleshooting.mdx b/fern/tools/custom-tools-troubleshooting.mdx index 54b679f1d..3d1b9784d 100644 --- a/fern/tools/custom-tools-troubleshooting.mdx +++ b/fern/tools/custom-tools-troubleshooting.mdx @@ -350,23 +350,32 @@ Tool behavior doesn't match your expectations. ```json title="Complete tool configuration" { - "name": "tool_name", - "description": "Clear description of what the tool does", - "parameters": { - "type": "object", - "properties": { - "param1": { - "type": "string", - "description": "Parameter description" - } + "type": "function", + "async": false, + "function": { + "name": "tool_name", + "description": "Clear description of what the tool does", + "parameters": { + "type": "object", + "properties": { + "param1": { + "type": "string", + "description": "Parameter description" + } + }, + "required": ["param1"] }, - "required": ["param1"] + "strict": true }, - "strict": true, - "async": false + "server": { + "url": "https://your-server.com/webhook" + } } ``` +`name`, `description`, `parameters` and `strict` belong inside `function`. +`type`, `async` and `server` sit on the tool itself. + ### Critical response rules **Always return HTTP 200** - Even for errors