[Mehayla]

What & why

Expands the Server Response Format section of the Function tools page (fern/tools/custom-tools.mdx) to cover the server-response scenarios customers repeatedly get stuck on but the page didn't document. Today the page shows only a single successful results response, so builders hit a wall on errors, parallel calls, and non-function tool types.

Gap type: Incomplete content (with a discoverability angle — the info exists on the Troubleshoot tools page, but builders never reach it from the main authoring page).

What changed

Three new subsections after the success example:

• Returning an error instead of a result — the error field + the must-return-HTTP-200 rule + single-line-string requirement.
• Responding to more than one tool call — per-item toolCallId mapping for parallel toolCallList requests, with independent success/error per call.
• Response format depends on the tool type — note that the results shape is the Function-tool contract and other server-backed types differ, plus a maintainer TODO to add a per-tool-type response table.

All new content is grounded in existing Vapi docs (the Troubleshoot tools page) and cross-links to it.

Evidence (last ~4 weeks, customer-facing feedback)

• Custom Tools is the 🌿 ✨ [Scheduled] Upgrade Fern CLI #1 documentation gap: the docs' own Ask AI assistant went silent or refused on 189 Custom Tools conversations in the trailing 28 days — far above the next real topic — and it's the top failing topic this week too.
• Top failing sub-themes map directly to this edit: Tool-Type-Specific Response Contracts (19), Coverage of Tool Request States (15), Tool Call Request Payload Shape (12), Per-Item ToolCallId Mapping (6).
• Recurring verbatim question pattern: multiple distinct users asking "what JSON format should my custom function tool server return to Vapi?" and how to handle multiple tool_calls / request states.

Notes for reviewers

• Opened as a draft with maintainer edits enabled so the docs team can adjust wording/placement directly.
• The PR branch has been synced to the current main so the diff shows only the added subsections.
• One inline {/* TODO(maintainers) */} marks where a per-tool-type response-shape table (Function vs Query/Knowledge Base vs Custom TTS/Transcriber) would fully close the gap — left for the team to confirm exact shapes.