---
name: create-tool
description: Create custom tools for Vapi voice assistants including function tools, API request tools, transfer call tools, end call tools, and integrations with Google Calendar, Sheets, Slack, and more. Use when adding capabilities to voice agents, building tool servers, or integrating external APIs.
license: MIT
compatibility: Requires internet access and a Vapi API key (VAPI_API_KEY).
metadata:
author: vapi
version: "1.0"
---
# Vapi Tool Creation
Create tools that give voice assistants the ability to take actions during calls — look up data, book appointments, transfer calls, send messages, and more.
> **Setup:** Ensure `VAPI_API_KEY` is set. See the `setup-api-key` skill if needed.
## Quick Start
### Create a Function Tool (cURL)
```bash
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name, e.g. San Francisco"
}
},
"required": ["location"]
}
},
"server": {
"url": "https://your-server.com/api/tools"
}
}'
```
### TypeScript (Server SDK)
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: process.env.VAPI_API_KEY! });
const tool = await vapi.tools.create({
type: "function",
function: {
name: "get_weather",
description: "Get current weather for a location",
parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "City name, e.g. San Francisco",
},
},
required: ["location"],
},
},
server: {
url: "https://your-server.com/api/tools",
},
});
console.log("Tool created:", tool.id);
```
## Tool Types
### Function Tool
The most common tool type. Your server receives the function call and returns a result.
```json
{
"type": "function",
"function": {
"name": "lookup_order",
"description": "Look up order status by order number",
"parameters": {
"type": "object",
"properties": {
"orderNumber": {
"type": "string",
"description": "The order number to look up"
}
},
"required": ["orderNumber"]
}
},
"server": {
"url": "https://your-server.com/api/tools"
},
"messages": [
{
"type": "request-start",
"content": "Let me look that up for you..."
},
{
"type": "request-complete",
"content": "I found your order information."
},
{
"type": "request-failed",
"content": "I'm having trouble looking that up. Let me try again."
}
]
}
```
### Transfer Call Tool
Transfer the caller to another number or SIP endpoint.
```json
{
"type": "transferCall",
"destinations": [
{
"type": "number",
"number": "+1234567890",
"message": "Transferring you to our billing department now.",
"description": "Transfer to billing department when customer has billing questions"
}
]
}
```
SIP transfer:
```json
{
"type": "transferCall",
"destinations": [
{
"type": "sip",
"sipUri": "sip:[email protected]",
"description": "Transfer to billing via SIP"
}
]
}
```
### End Call Tool
Allows the assistant to end the call programmatically.
```json
{
"type": "endCall"
}
```
### DTMF Tool
Send DTMF tones (touch-tone signals) during a call for IVR navigation.
```json
{
"type": "dtmf"
}
```
### Voicemail Tool
Detect and handle voicemail.
```json
{
"type": "voicemail",
"beepDetectionEnabled": true
}
```
### Google Calendar Tool
```json
{
"type": "google.calendar.event.create",
"name": "create_calendar_event",
"description": "Schedule a meeting on Google Calendar"
}
```
### Google Sheets Tool
```json
{
"type": "google.sheets.row.append",
"name": "log_to_sheet",
"description": "Log call data to the configured Google Sheet"
}
```
### Slack Tool
```json
{
"type": "slack.message.send",
"name": "notify_slack",
"description": "Send urgent notifications to the #customer-support Slack channel"
}
```
Connect Google or Slack under the dashboard's tool-provider integrations before using these built-in tools. Configure the spreadsheet, sheet range, calendar, or Slack channel in the dashboard as required; never put OAuth tokens in a tool payload.
### MCP Tool
Connect to Model Context Protocol servers.
```json
{
"type": "mcp",
"server": {
"url": "https://your-mcp-server.com"
}
}
```
## Tool Server Implementation
When the assistant calls a tool, Vapi sends a POST request to your server URL.
### Request Format
```json
{
"message": {
"type": "tool-calls",
"toolCallList": [
{
"id": "call_abc123",
"name": "get_weather",
"parameters": {
"location": "San Francisco"
}
}
],
"call": {
"id": "call-uuid",
"orgId": "org-uuid",
"type": "webCall"
}
}
}
```
### Response Format
Your server must return:
```json
{
"results": [
{
"toolCallId": "call_abc123",
"result": "San Francisco: 65°F, partly cloudy"
}
]
}
```
### Example Server (Express.js)
```typescript
import express from "express";
const app = express();
app.use(express.json());
app.post("/api/tools", async (req, res) => {
const { message } = req.body;
const results = [];
for (const toolCall of message.toolCallList) {
let result: string;
switch (toolCall.name) {
case "get_weather":
const weather = await fetchWeather(toolCall.parameters.location);
result = `${toolCall.parameters.location}: ${weather.temp}°F, ${weather.condition}`;
break;
case "lookup_order":
const order = await lookupOrder(toolCall.parameters.orderNumber);
result = `Order ${order.number}: ${order.status}`;
break;
default:
result = "Unknown tool";
}
results.push({ toolCallId: toolCall.id, result });
}
res.json({ results });
});
app.listen(3000);
```
## Attaching Tools to Assistants
### By tool ID (recommended for reusable tools)
```bash
curl -X PATCH https://api.vapi.ai/assistant/{assistant-id} \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": {
"provider": "openai",
"model": "gpt-4.1",
"toolIds": ["tool-id-1", "tool-id-2"],
"messages": [{"role": "system", "content": "Your prompt here"}]
}
}'
```
### Inline (for one-off tools)
Define tools directly in the assistant's model configuration — see the `create-assistant` skill.
## Managing Tools
```bash
# List all tools
curl https://api.vapi.ai/tool -H "Authorization: Bearer $VAPI_API_KEY"
# Get a tool
curl https://api.vapi.ai/tool/{id} -H "Authorization: Bearer $VAPI_API_KEY"
# Update a tool
curl -X PATCH https://api.vapi.ai/tool/{id} \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"function": {"description": "Updated description"}}'
# Delete a tool
curl -X DELETE https://api.vapi.ai/tool/{id} \
-H "Authorization: Bearer $VAPI_API_KEY"
```
## Async Tools
For long-running operations, mark a tool as async. The assistant continues speaking while the tool executes:
```json
{
"type": "function",
"async": true,
"function": {
"name": "send_email",
"description": "Send a confirmation email (runs in background)"
},
"server": {
"url": "https://your-server.com/api/tools"
}
}
```
## Tool Messages
Control what the assistant says during tool execution:
```json
{
"messages": [
{
"type": "request-start",
"content": "One moment while I look that up..."
},
{
"type": "request-complete",
"content": "Got it!"
},
{
"type": "request-failed",
"content": "Sorry, I couldn't complete that action."
},
{
"type": "request-response-delayed",
"content": "This is taking a bit longer than usual, please hold.",
"timingMilliseconds": 5000
}
]
}
```
## References
- [Tool Server Implementation](references/tool-server.md) — Detailed server setup guide
- [Vapi Tools Docs](https://docs.vapi.ai/tools) — Official documentation
## Additional Resources
Vapi provides a **documentation MCP server** that gives compatible AI agents access to the Vapi knowledge base. Use its documentation search for advanced configuration, troubleshooting, SDK details, and anything beyond this skill.
To add the Vapi documentation MCP server manually in Claude Code, run:
```bash
claude mcp add vapi-docs -- npx -y mcp-remote https://docs.vapi.ai/_mcp/server
```
See the [Vapi MCP integration guide](https://docs.vapi.ai/cli/mcp) for setup instructions across supported agents.