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"
    }
  ],
  "function": {
    "name": "transfer_to_billing",
    "description": "Transfer the caller to the billing department"
  }
}

SIP transfer:

json

{
  "type": "transferCall",
  "destinations": [
    {
      "type": "sip",
      "sipUri": "sip:billing@company.com",
      "description": "Transfer to billing via SIP"
    }
  ]
}

End Call Tool

Allows the assistant to end the call programmatically.

json

{
  "type": "endCall",
  "function": {
    "name": "end_call",
    "description": "End the call when the conversation is complete"
  }
}

DTMF Tool

Send DTMF tones (touch-tone signals) during a call for IVR navigation.

json

{
  "type": "dtmf",
  "function": {
    "name": "press_digits",
    "description": "Press phone keypad digits to navigate phone menus",
    "parameters": {
      "type": "object",
      "properties": {
        "digits": {
          "type": "string",
          "description": "Digits to press (0-9, *, #)"
        }
      },
      "required": ["digits"]
    }
  }
}

Voicemail Tool

Detect and handle voicemail.

json

{
  "type": "voicemail",
  "function": {
    "name": "leave_voicemail",
    "description": "Leave a voicemail message"
  }
}

Google Calendar Tool

json

{
  "type": "google.calendar.event.create",
  "function": {
    "name": "create_calendar_event",
    "description": "Schedule a meeting on Google Calendar"
  }
}

Google Sheets Tool

json

{
  "type": "google.sheets.row.append",
  "function": {
    "name": "log_to_sheet",
    "description": "Log call data to a Google Sheet"
  }
}

Slack Tool

json

{
  "type": "slack.message.send",
  "function": {
    "name": "notify_slack",
    "description": "Send a notification to Slack"
  }
}

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",
        "arguments": {
          "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.arguments.location);
        result = `${toolCall.arguments.location}: ${weather.temp}°F, ${weather.condition}`;
        break;
      case "lookup_order":
        const order = await lookupOrder(toolCall.arguments.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 — Detailed server setup guide
Vapi Tools Docs — Official documentation

Additional Resources

This skills repository includes a Vapi documentation MCP server (

vapi-docs

) that gives your AI agent access to the full Vapi knowledge base. Use the

searchDocs

tool to look up anything beyond what this skill covers — advanced configuration, troubleshooting, SDK details, and more.

Auto-configured: If you cloned or installed these skills, the MCP server is already configured via

.mcp.json

(Claude Code),

.cursor/mcp.json

(Cursor), or

.vscode/mcp.json

(VS Code Copilot).

Manual setup: If your agent doesn't auto-detect the config, run:

bash

claude mcp add vapi-docs -- npx -y mcp-remote https://docs.vapi.ai/_mcp/server

See the README for full setup instructions across all supported agents.

create-tool

NPX Install

Tags

SKILL.md Content

Vapi Tool Creation

Quick Start

Create a Function Tool (cURL)

TypeScript (Server SDK)

Tool Types

Function Tool

Transfer Call Tool

End Call Tool

DTMF Tool

Voicemail Tool

Google Calendar Tool

Google Sheets Tool

Slack Tool

MCP Tool

Tool Server Implementation

Request Format

Response Format

Example Server (Express.js)

Attaching Tools to Assistants

By tool ID (recommended for reusable tools)

Inline (for one-off tools)

Managing Tools

Async Tools

Tool Messages

References

Additional Resources