[stephenvapiai]

Why

Customer feedback from the last 28 days (support tickets, Discord, and docs.vapi.ai's Ask AI assistant) shows Custom/Function tools as the single highest-volume, highest-failure documentation gap right now:

• Custom Tools is the 🌿 ✨ [Scheduled] Update API Spec #2 topic by volume in the last complete week (89 conversations) and over the trailing 28 days (345 conversations), across support tickets, Discord, and Ask AI conversations.
• It is by far the 🌿 ✨ [Scheduled] Upgrade Fern CLI #1 topic where Vapi's own Ask AI assistant fails to answer (163 refused/silent/guardrail-blocked conversations over 28 days) -- more than 4x the next topic ("General").
• Within Custom Tools, the sub-themes cluster tightly around the exact wire contract: "Help With Webhook Payload And Response Contract" (50), "Unclear Tool-calls Request Payload Structure" (39), "Tool Call Outputs And Messages" (30), and "Tool Response Format And Error Handling Requirements" (19). Sample conversations repeatedly ask things like "how do I handle custom tool server response format results, including toolCallId, result, and error messages" and "how does a custom tool server respond to a tool call."
• Checking docs.vapi.ai/tools/custom-tools (the primary Function tools guide, where builders land first) confirmed the gap: its "Server Response Format" section shows only the success result shape and never mentions the error field, its trigger semantics, or the always-return-HTTP-200 rule.
• The error field already exists and is documented on /tools/custom-tools-troubleshooting and referenced on /tools/api-request-vs-function, but a builder implementing their first Function tool from the primary guide would never see it there -- this is a discoverability/incompleteness gap, not a missing feature.

What changed

Edited the existing "Server Response Format: Providing Results and Context" section on fern/tools/custom-tools.mdx only:

• Documents the error field as the failure counterpart to result, and clarifies that Vapi selects the Request Failed message based on the presence of error, not by inspecting result's content.
• Adds a failure JSON example alongside the existing success example.
• Adds the always-return-HTTP-200 rule (with a cross-link to /tools/custom-tools-troubleshooting for other response-format failure modes) and a note on mixing result/error across multiple tool calls in one response.

What this does NOT touch

• The "Request Format" section of this same file was edited 4 days ago in Apply documentation edit pass #1244 (fixing the toolCallList/function nesting). This PR does not re-touch that section -- confirmed by reading that commit's diff before drafting.
• No other file in the repo is touched.

Evidence

• Vapi Wisdom Knowledge Graph, org_id=7c8156fb-e5bb-4f19-be0d-aaf5703c8adc, sources: Zendesk/Plain support tickets, Discord, Fern Ask AI conversations, Posthog NPS, trailing 7/28-day windows ending 2026-09-28.
• Note: the most recent ~6.5 days show materially lower tagged-conversation volume (212 of 402 raw records tagged, 53%) than the prior week (1,015 of 1,220, 83%), consistent with normal tagging/ingestion lag rather than a real drop in customer contact -- ranking here is based on the last complete week and the 28-day baseline, not the partial current week.

Opened automatically by the Vapi Help Center Update automation.

[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: 00bea08
Status: waiting for staging docs URL