docs(learnings): idle-message/voicemail conflict, verbose-ban priming, tool-id TTS leaks

Three intertwined gotchas surfaced during a customer voicemail-edge sim
hardening pass:

- voicemail-detection.md: idleTimeoutSeconds < silenceTimeoutSeconds + a
  "stay silent on voicemail" prompt strategy deadlocks the moment
  voicemailDetection has a coverage hole — every failed transcript ends
  with the idle-message injection. Cannot be fixed at the prompt level.

- assistants.md (new "Prompt Authoring" section): verbose negative-directive
  lists prime the banned phrases under output uncertainty. A 50+ phrase ban
  regressed a sim suite from 12/15 to 3/15. Short positive directives beat
  exhaustive negative enumeration.

- tools.md: naming a tool resource ID in system-prompt prose causes the LLM
  to emit it as TTS content instead of (or in addition to) invoking it via
  tool_calls. Refer to capabilities by natural-language intent.

All three entries are generalized — no customer or org-specific identifiers.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dhruva-vapi

docs/learnings/assistants.md

@@ -532,3 +532,21 @@ When HIPAA is enabled (on org or assistant) and HIPAA provider validation is enf
 ### `toolIds` and inline `tools` can coexist
 
 They are merged, not mutually exclusive. But be aware of potential duplicates.
+
+---
+
+## Prompt Authoring
+
+### Verbose negative-directive lists prime the banned phrases
+
+Listing many forbidden phrases in a system prompt ("never say 'X', 'Y', 'Z', …") can paradoxically *increase* their emission rate rather than decrease it. Every banned phrase you enumerate is a token plant in the model's active context — under output uncertainty (the rule says "stay silent," but the platform is asking for *some* output), the model preferentially samples from recently-activated tokens. The verbose ban becomes a verbose menu of likely outputs.
+
+**Concrete failure pattern:** In one validation, a 50+ phrase ban list targeting voicemail edge cases regressed a sim-suite pass rate from 80% (12/15) to 20% (3/15). The model emitted nonsense single tokens that mapped to the banned-phrase region of the prompt — short fragments like one-word utterances ending in periods that didn't appear anywhere else in the conversation surface.
+
+**Recommendation:**
+- Prefer a short *positive* directive ("emit empty `content`") over an exhaustive negative enumeration.
+- If specific phrase bans are necessary, keep the list to 3–5 representative examples and rely on a principle clause ("…or any narration of your intent") rather than exhaustive listing.
+- Validate prompt changes against a sim suite before rolling forward — verbose-ban regressions don't show up in single test calls; they require a few iterations of statistical signal to surface.
+- This generalizes beyond voicemail: any "stay silent" / "don't say X" rule benefits from positive framing.
+
+Cross-reference: see [voicemail-detection.md](voicemail-detection.md) for the platform-level conflict that often motivates these prompt rules in the first place.

docs/learnings/tools.md

@@ -123,6 +123,14 @@ If `endCallFunctionEnabled: true` is set on the assistant and no explicit `endCa
 
 When the LLM invokes an endCall tool, the call's `endedReason` is set to `assistant-ended-call` — not `customer-ended-call` or a generic hangup reason. Use this in post-call analysis and structured output evaluations.
 
+### Naming a tool resource ID in system-prompt prose causes TTS leak
+
+If your system prompt references a specific tool by its resource ID ("call the `your-end-call-feature-abc12345` tool"), the model can emit the resource ID as `content` (TTS-bound speech) instead of, or in addition to, invoking it via `tool_calls`. The TTS pipeline speaks the ID aloud as audio. If the call has anything looping audio back through STT (a personality bot in a sim, or a real human listening), the transcript captures partial syllables of the spoken ID.
+
+**Concrete signature:** A tool resource ID like `your-feature-name-abc12345` shows up in the AI transcript as something like `"feature name, a b c one two three four five"` — short, mangled fragments that map character-by-character to the tool ID.
+
+**Recommendation:** Refer to tool capabilities by **natural-language intent** in prose ("end the call", "transfer to a specialist", "look up the customer"), never by resource ID. The tool-calling layer picks the correct registered function from `toolIds` based on intent. If the LLM is reluctant to invoke a tool, fix the tool's `function.description` rather than naming the tool in the prompt body — see [transfers.md](transfers.md) for the same pattern in the transfer-tool context.
+
 ---
 
 ## handoff Tools

docs/learnings/voicemail-detection.md

@@ -269,3 +269,35 @@ The detection assistant doesn't need post-call analysis — save the LLM call.
 | Agent hangs up on humans saying "sorry" | "sorry" misclassified as voicemail context | Add false-positive prevention rules |
 | Agent stuck on IVR forever | No timeout or exit condition | Set `silenceTimeoutSeconds` and `maxDurationSeconds` |
 | Greeting plays twice (handoff + fronter firstMessage) | Fronter has its own `firstMessage` | Set fronter `firstMessage: ""` or use model-generated mode |
+| Idle message ("Are you still there?") fires on voicemail edge cases | `idleTimeoutSeconds` < `silenceTimeoutSeconds` while assistant strategy is "stay silent on voicemail" | See "Idle messages collide with silence-based voicemail handling" below |
+
+---
+
+## Idle Messages and Voicemail Silence
+
+### Idle messages collide with silence-based voicemail handling
+
+When `messagePlan.idleMessages` is set with a tight `idleTimeoutSeconds` (e.g. 6s) AND the voicemail strategy is "stay silent and let platform-level `voicemailDetection` hang up the call," the two settings deadlock on every edge case where Vapi's detection has a coverage hole (full-mailbox prompts, some carrier-specific custom greetings, late-beep messages).
+
+**What you might expect:** The static `voicemailMessage` plays and the call ends. Idle messages don't fire because there's no assistant-side silence — the platform handles everything.
+
+**What actually happens:** When `voicemailDetection` misses, the LLM gets a turn. If the system prompt instructs it to stay silent on voicemail signals, the assistant goes silent — and `idleMessages` injects "Are you still there?" after `idleTimeoutSeconds`. Result: every voicemail-edge call ends with the idle prompt in the transcript, breaking any sim rubric that scores `idle_prompt_after_voicemail` or any post-call analysis that flags assistant utterances on voicemail. Cannot be fixed at the prompt level — even a perfect-silence prompt can't beat the platform timer.
+
+**Concrete signature:** Every failed transcript on a voicemail-edge sim suite ends with `AI: Are you still there?` while `endedReason` is `silence-timed-out`.
+
+**Recommendation:**
+- **Preferred — two-agent relay.** Use a classifier squad member that ends the call before the main assistant ever gets a voicemail turn. The main assistant's `idleTimeoutSeconds` stays tight for human conversations.
+- **Fallback — single-agent.** Set `idleTimeoutSeconds` >= `silenceTimeoutSeconds` so silence-timeout terminates the call before idle injection. This costs you idle-prompt responsiveness for genuinely-silent humans but eliminates the conflict.
+- Don't try to suppress this with system-prompt rules — the idle injection happens at the platform layer, not the LLM layer.
+
+```yaml
+# Single-agent fallback (less ideal — loses tight human-side idle responsiveness)
+silenceTimeoutSeconds: 15
+messagePlan:
+  idleMessageMaxSpokenCount: 1
+  idleMessages:
+    - Are you still there?
+  idleTimeoutSeconds: 30  # >= silenceTimeoutSeconds → idle never fires before call ends
+```
+
+Cross-reference: see [squads.md](squads.md) for the two-agent relay pattern, and [assistants.md](assistants.md) for prompt-authoring guidance on silence rules.