From c5c4729dccfe2f24923dc05ac77ec1ed09b1f92b Mon Sep 17 00:00:00 2001 From: Chiranjeet Mishra Date: Thu, 10 Sep 2026 03:01:13 +0000 Subject: [PATCH] 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 |