docs: make the complete tool configuration template a valid payload

[chiranjeet-vapi]

Stacked on #1209, which touches the same code block. Merge that one first; this diff shrinks to a single block once it lands.

Problem

The "Complete tool configuration" template on the custom tools troubleshooting page is not a payload the API accepts. It has name, description, parameters, strict and async all flat on the tool, with no type and no function wrapper.

Reproduced

POST https://api.vapi.ai/assistant, 2026-09-10, pasting the template as a tool:

model.each value in tools.type must be one of the following values: dtmf, endCall,
transferCall, ... function, mcp, apiRequest, ...

Add type and it fails again on the missing wrapper:

model.each value in tools.property name should not exist

The corrected template validates. Posted with a deliberate unrelated error to force rejection, the tool itself produces no validation failure, only the unrelated one.

What changed

One code block, plus a line naming which fields sit where. name, description, parameters and strict go inside function. type, async and server sit on the tool.

server is optional, confirmed: a correctly nested tool without one returns no error. It is included because a custom tool without a server has nowhere to send its tool-calls webhook, which is what this page is about.

Not in this PR

The "Async vs sync behavior" tabs show async inside the function object. That is wrong in the same way, but it does not 400. The API accepts async there and ignores it, since async is read at tool level, so it is a silently-inert example rather than a broken one. Left alone here; happy to fix it if wanted.

🤖 Generated with Claude Code

[lightsage-app]

Lightsage docs evals

Result: passed
Staging docs: https://api.vapi.ai/api-json`
Commit: e934974

Average score: 100/100
Passed: 3/3

Eval ID	Status	Score	Model	Tools	Docs 404
08e24c18-82a0-45de-abdc-d237bd12bc0f	Pass	100	claude-code/global.anthropic.claude...	8	0
08e24c18-82a0-45de-abdc-d237bd12bc0f	Pass	100	cursor/auto	13	1
08e24c18-82a0-45de-abdc-d237bd12bc0f	Pass	100	codex/gpt-5.4	36	1

[stephenvapiai]

Three small follow-up edits an editorial pass turned up on this page. All apply cleanly on top of this PR's head (27b043f) and land in the same block, so they're easiest to fold in here.

1. type + function wrapper on the "Enable schema validation" example. It was still flat (name/description/parameters/strict), the same shape this PR fixes for the complete template, so pasting it back hits model.each value in tools.property name should not exist. Wrapped it and moved the line highlight to strict.
2. API-reference pointer + default wording. Linked model to the verified #request.body.model anchor (the same deep-link pattern the provider pages already use), and softened "defaults to 250" to "currently 250": api-json declares no default for maxTokens on any model schema, so the 50–10000 range is spec-backed but 250 is a runtime value.
3. Symptom card wording. "truncated Increase the model token limit" was a run-on; trimmed to just the symptom, since the card already links to the fix section.

Verified against https://api.vapi.ai/api-json: maxTokens is defined on model schemas only, and CreateFunctionToolDTO requires type: "function" plus a function wrapper.

Patch (applies on 27b043f):

diff --git a/fern/tools/custom-tools-troubleshooting.mdx b/fern/tools/custom-tools-troubleshooting.mdx
index 3d1b978..a610b30 100644
--- a/fern/tools/custom-tools-troubleshooting.mdx
+++ b/fern/tools/custom-tools-troubleshooting.mdx
@@ -31,8 +31,7 @@ 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 the model
-    token limit
+    **Symptoms:** Tool parameters or responses are truncated.
   </Card>
 </CardGroup>
 
@@ -77,14 +76,17 @@ 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 configuration" {9}
 {
-  "name": "get_weather",
-  "description": "Get current weather for a city",
-  "parameters": {
-    // ... your parameters
-  },
-  "strict": true
+  "type": "function",
+  "function": {
+    "name": "get_weather",
+    "description": "Get current weather for a city",
+    "parameters": {
+      // ... your parameters
+    },
+    "strict": true
+  }
 }

@@ -228,8 +230,9 @@ Tool parameters or responses are getting cut off.

Increase the model token limit

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.
+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. When unset, the model
+applies its own default (currently 250).

`maxTokens` is a model property, not a tool property. Setting it inside ```