docs: maxTokens is a model property, not a tool property

[chiranjeet-vapi]

Problem

fern/tools/custom-tools-troubleshooting.mdx tells readers to set maxTokens on a tool, in three code blocks and in the debugging table. A customer followed the "Increase token limits" section and got:

{"message":["assistant.model.each value in tools.function.property maxTokens should not exist"],"error":"Bad Request","statusCode":400}

Reproduced

Posting the page's own example back to POST https://api.vapi.ai/assistant on 2026-09-10:

{"message":["model.each value in tools.function.property maxTokens should not exist"],"error":"Bad Request","statusCode":400}

Same validator. The report reads assistant.model because it was nested under an assistant key; a direct POST to /assistant roots at model.

Why

Checked against https://api.vapi.ai/api-json on 2026-09-10:

OpenAIFunction properties          name, strict, description, parameters
OpenAIFunctionParameters           type, properties, required
JsonSchema properties              type, items, properties, description,
                                   pattern, format, required, enum, title

maxTokens is defined on the model schemas only (OpenAIModel, AnthropicModel, GoogleModel and the rest), with minimum: 50, maximum: 10000 and a documented default of 250. The page said the default was 100, which is not a value the API has anywhere.

What changed

All in fern/tools/custom-tools-troubleshooting.mdx. No other page in the repo places maxTokens outside model.

1. Token truncation section now points at model.maxTokens, gives the real range and default, and carries a warning with the verbatim 400 so the error string is searchable.
2. "maxTokens": 500 removed from the schema validation example and from the complete tool configuration template.
3. Debugging table row now says model.maxTokens.
4. Quick diagnosis card reworded to match the renamed heading.

Not in this PR

The "Complete tool configuration" template is separately broken: pasted as a tool it returns tools.type must be one of ..., and with type added it returns tools.property name should not exist, because name, description, strict and parameters belong inside a function wrapper. Left alone here to keep this PR to the reported issue. Happy to raise it separately.

🤖 Generated with Claude Code

[lightsage-app]

Lightsage docs evals

Waiting for the staging docs URL before running evals.

Lightsage will start the selected PR evals automatically when GitHub reports a successful docs deployment for this PR. This usually happens within 15 minutes.

Commit: c5c4729
Status: waiting for staging docs URL