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
   </Card>
   <Card title="Parameters cut off" href="#token-truncation">
-    **Symptoms:** Tool parameters or responses truncated Increase token limits
+    **Symptoms:** Tool parameters or responses truncated Increase the model
+    token limit
   </Card>
 </CardGroup>
 
@@ -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`.
+
+<Warning>
+  `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`.
+</Warning>
+
 <Note>
   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
+      }
     }
     ```
   </Tab>
@@ -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
+      }
     }
     ```
   </Tab>
@@ -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            |