From 57af2984edbb7218ab62f3cd4394e1ee04f80cf4 Mon Sep 17 00:00:00 2001 From: Chiranjeet Mishra Date: Thu, 10 Sep 2026 02:29:05 +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 the debugging table. The API has no such field: 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. Copying the example back returns 400 Bad Request with "assistant.model.each value in tools.function.property maxTokens should not exist". maxTokens is defined on the model schemas only, 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 in the API. The same section fixes two other copy-paste failures on the page: async is a tool property rather than a function property, and the complete tool configuration template was missing the type, function and server nesting, so it was not a payload the API would accept either. Verified against https://api.vapi.ai/api-json on 2026-09-10. Co-Authored-By: Claude Opus 5 (1M context) --- fern/tools/custom-tools-troubleshooting.mdx | 86 +++++++++++++-------- 1 file changed, 53 insertions(+), 33 deletions(-) diff --git a/fern/tools/custom-tools-troubleshooting.mdx b/fern/tools/custom-tools-troubleshooting.mdx index b46eb6ad2..2f3b89ea2 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 @@ -76,15 +77,14 @@ Check that your tool schema includes all required parameters: Add `strict: true` to catch validation errors early: -```json title="Tool configuration" {7} +```json title="Tool function definition" {7} { "name": "get_weather", "description": "Get current weather for a city", "parameters": { // ... your parameters }, - "strict": true, - "maxTokens": 500 + "strict": true } ``` @@ -223,23 +223,32 @@ Tool returns data but the assistant doesn't use it in conversation. ## Token truncation -Tool parameters or responses are getting cut off. +Tool call arguments or assistant 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`: -```json title="Tool configuration" {7} +```json title="Assistant model configuration" {6} { - "name": "complex_tool", - "description": "Tool that needs more tokens", - "parameters": { - // ... your parameters - }, - "maxTokens": 500 // Increase from default 100 + "model": { + "provider": "openai", + "model": "gpt-4o", + "messages": [{ "role": "system", "content": "..." }], + "maxTokens": 500 + } } ``` +`maxTokens` accepts a value from `50` to `10000` and defaults to `250`. + + + `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 occurs. @@ -292,9 +301,12 @@ Tool behavior doesn't match your expectations. ```json { - "name": "sync_tool", - "async": false, // or omit (default) - // ... other config + "type": "function", + "async": false, // or omit (default) + "function": { + "name": "sync_tool" + // ... rest of the function definition + } } ``` @@ -309,9 +321,12 @@ Tool behavior doesn't match your expectations. ```json { - "name": "async_tool", + "type": "function", "async": true, - // ... other config + "function": { + "name": "async_tool" + // ... rest of the function definition + } } ``` @@ -353,21 +368,26 @@ 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, - "maxTokens": 500, - "async": false + "server": { + "url": "https://your-server.com/webhook" + } } ``` @@ -389,5 +409,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 |