diff --git a/fern/docs.yml b/fern/docs.yml
index c3cf15a0e..c3c9c0b4f 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -172,6 +172,9 @@ navigation:
- page: Built-in call tools
path: tools/default-tools.mdx
icon: fa-light fa-gear
+ - page: Voicemail tool
+ path: tools/voicemail-tool.mdx
+ icon: fa-light fa-voicemail
- page: Custom tools
path: tools/custom-tools.mdx
icon: fa-light fa-screwdriver-wrench
diff --git a/fern/tools/voicemail-tool.mdx b/fern/tools/voicemail-tool.mdx
new file mode 100644
index 000000000..502bc9b22
--- /dev/null
+++ b/fern/tools/voicemail-tool.mdx
@@ -0,0 +1,235 @@
+---
+title: Voicemail Tool
+subtitle: Learn how to use the assistant-controlled voicemail tool for flexible voicemail handling
+slug: tools/voicemail-tool
+---
+
+
+**Beta Feature**: The voicemail tool is currently in beta. Features and behavior may change as we continue to improve this functionality based on user feedback.
+
+
+## Overview
+
+The voicemail tool gives your assistant direct control over when and how to leave voicemail messages. Unlike [automatic voicemail detection](/calls/voicemail-detection), which operates independently of your assistant, this tool allows your assistant to decide when it's reached a voicemail system and leave a configured message.
+
+**Key benefits:**
+- **Maximum flexibility** - Assistant decides when and what to say
+- **Cost-effective** - Only triggers when needed
+- **Context-aware** - Messages can be customized based on conversation
+- **Simple integration** - Works like other built-in tools
+
+## How it works
+
+When you add the voicemail tool to your assistant:
+
+1. Your assistant listens for voicemail indicators (greetings mentioning "unavailable", "leave a message", etc.)
+2. Upon detecting voicemail, the assistant calls the tool
+3. The tool delivers your configured message
+4. The call ends automatically after message delivery
+
+
+This approach differs from [automatic voicemail detection](/calls/voicemail-detection), which detects voicemail at the system level. The voicemail tool puts detection and response entirely in the assistant's hands.
+
+
+## Configuration
+
+Add the voicemail tool to your assistant's tools array:
+
+
+```json title="API Configuration"
+{
+ "model": {
+ "provider": "openai",
+ "model": "gpt-4o",
+ "messages": [
+ {
+ "type": "system",
+ "content": "You are a sales representative for Acme Corp. If at any point you determine you're speaking to a voicemail system (greeting mentions 'unavailable', 'leave a message', 'voicemail', etc.), immediately use the leave_voicemail tool."
+ }
+ ],
+ "tools": [
+ {
+ "type": "voicemail",
+ "function": {
+ "name": "leave_voicemail",
+ "description": "Leave a voicemail message when you detect you've reached a voicemail system"
+ },
+ "messages": [
+ {
+ "type": "request-start",
+ "content": "Hi, this is {{company}}. {{message}}. Please call us back at {{phone}}."
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+```typescript title="TypeScript SDK"
+import { VapiClient } from "@vapi-ai/server-sdk";
+
+const vapi = new VapiClient({ token: process.env.VAPI_API_KEY });
+
+const assistant = await vapi.assistants.create({
+ model: {
+ provider: "openai",
+ model: "gpt-4o",
+ messages: [{
+ type: "system",
+ content: `You are a sales representative for Acme Corp.
+ If at any point you determine you're speaking to a voicemail system
+ (greeting mentions 'unavailable', 'leave a message', 'voicemail', etc.),
+ immediately use the leave_voicemail tool.`
+ }],
+ tools: [{
+ type: "voicemail",
+ function: {
+ name: "leave_voicemail",
+ description: "Leave a voicemail message when you detect you've reached a voicemail system"
+ },
+ messages: [{
+ type: "request-start",
+ content: "Hi, this is {{company}}. {{message}}. Please call us back at {{phone}}."
+ }]
+ }]
+ }
+});
+```
+```python title="Python SDK"
+from vapi import Vapi
+
+client = Vapi(token=os.getenv("VAPI_API_KEY"))
+
+assistant = client.assistants.create(
+ model={
+ "provider": "openai",
+ "model": "gpt-4o",
+ "messages": [{
+ "type": "system",
+ "content": """You are a sales representative for Acme Corp.
+ If at any point you determine you're speaking to a voicemail system
+ (greeting mentions 'unavailable', 'leave a message', 'voicemail', etc.),
+ immediately use the leave_voicemail tool."""
+ }],
+ "tools": [{
+ "type": "voicemail",
+ "function": {
+ "name": "leave_voicemail",
+ "description": "Leave a voicemail message when you detect you've reached a voicemail system"
+ },
+ "messages": [{
+ "type": "request-start",
+ "content": "Hi, this is {{company}}. {{message}}. Please call us back at {{phone}}."
+ }]
+ }]
+ }
+)
+```
+
+
+## Message Configuration
+
+Define the voicemail message in the tool configuration:
+
+```json
+{
+ "messages": [
+ {
+ "type": "request-start",
+ "content": "Hi, this is {{company}}. {{message}}. Please call us back at {{phone}}."
+ }
+ ]
+}
+```
+
+
+Use template variables like `{{company}}`, `{{message}}`, and `{{phone}}` to make your voicemail messages dynamic while keeping them consistent.
+
+
+## Advanced Examples
+
+### Dynamic voicemail with context
+
+```json
+{
+ "model": {
+ "provider": "openai",
+ "model": "gpt-4o",
+ "messages": [
+ {
+ "type": "system",
+ "content": "You are calling leads about their recent inquiry. If you reach voicemail, use the leave_voicemail tool and mention their specific interest."
+ }
+ ],
+ "tools": [
+ {
+ "type": "voicemail",
+ "function": {
+ "name": "leave_voicemail",
+ "description": "Leave a personalized voicemail message"
+ },
+ "messages": [
+ {
+ "type": "request-start",
+ "content": "Hi {{customer_name}}, this is {{agent_name}} from {{company}} following up on your inquiry about {{product_interest}}. I'd love to discuss how we can help. Please call me back at {{callback_number}} or I'll try you again tomorrow. Thanks!"
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+
+
+## Best Practices
+
+### Detection prompting
+Be specific about voicemail indicators in your system prompt:
+- "unavailable"
+- "leave a message"
+- "voicemail"
+- "at the tone"
+- "beep"
+
+### Message structure
+Keep voicemail messages:
+- **Brief** - Under 30 seconds
+- **Clear** - State name, company, and purpose
+- **Actionable** - Include callback number or next steps
+- **Professional** - Match your brand voice
+
+### Error handling
+Consider edge cases:
+- Long voicemail greetings
+- Voicemail box full scenarios
+- Systems requiring keypad input
+
+## Voicemail Tool vs. Automatic Detection
+
+| Feature | Voicemail Tool | [Automatic Detection](/calls/voicemail-detection) |
+|---------|----------------|---------------------------------------------------|
+| Control | Assistant-driven | System-driven |
+| Flexibility | High - custom logic | Medium - predefined behavior |
+| Cost | Lower - only when used | Higher - continuous monitoring |
+| Setup complexity | Simple - just add tool | Moderate - configure detection |
+| Message customization | Full control | Limited to configured message |
+| Detection accuracy | Depends on prompt | Provider-specific (Vapi, Google, etc.) |
+
+
+Choose the **voicemail tool** when you need maximum flexibility and cost efficiency. Choose **automatic detection** when you need guaranteed system-level detection without relying on assistant prompting.
+
+
+## Common Use Cases
+
+- **Sales outreach** - Personalized follow-up messages
+- **Appointment reminders** - Leave detailed appointment information
+- **Customer service** - Callback scheduling with ticket numbers
+- **Lead qualification** - Leave targeted messages based on lead data
+
+## Next steps
+
+- Learn about other [default tools](/tools/default-tools)
+- Explore [automatic voicemail detection](/calls/voicemail-detection) for system-level handling
+- See how to create [custom tools](/tools/custom-tools) for your specific needs
+