create-tool

What this skill does

# 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:[email protected]",
      "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 i