diff --git a/fern/tools/custom-tools-troubleshooting.mdx b/fern/tools/custom-tools-troubleshooting.mdx
index b46eb6ad2..3d1b9784d 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>
 
@@ -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
-}
-```
+<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
@@ -353,24 +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,
-  "maxTokens": 500,
-  "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
 
 <Check>**Always return HTTP 200** - Even for errors</Check>
@@ -389,5 +394,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            |