Custom tools troubleshooting

Overview

Troubleshoot and fix common issues with custom tool integrations in your Vapi assistants.

In this guide, you’ll learn to:

• Diagnose why tools aren’t triggering
• Fix response format errors
• Resolve parameter and token issues
• Handle multiple tool scenarios

Quick diagnosis

Start with the most common issue for your symptoms:

Tool won’t trigger

Your assistant doesn’t call the tool even when it should.

Check your assistant prompting

Verify required parameters

Check that your tool schema includes all required parameters:

1
{
2
  "name": "get_weather",
3
  "parameters": {
4
    "type": "object",
5
    "properties": {
6
      "city": {
7
        "type": "string",
8
        "description": "City name for weather lookup"
9
      }
10
    },
11
    "required": ["city"] // Must be array of required parameter names
12
  }
13
}

Enable schema validation

Add strict: true to catch validation errors early:

1
{
2
  "name": "get_weather",
3
  "description": "Get current weather for a city",
4
  "parameters": {
5
    // ... your parameters
6
  },
7
  "strict": true,
8
  "maxTokens": 500
9
}

No result returned error

Logs show “ok, no result returned” or similar messages.

Use the correct response format

Your webhook must return this exact JSON structure:

1
{
2
  "results": [
3
    {
4
      "toolCallId": "call_123",
5
      "result": "Your response as single-line string"
6
    }
7
  ]
8
}

Common format mistakes

1
// Return this with HTTP 200
2
{
3
  "results": [
4
    {
5
      "toolCallId": "call_123",
6
      "error": "Something went wrong"
7
    }
8
  ]
9
}

1
{
2
  "result": "Line 1\nLine 2\nLine 3"
3
}

1
{
2
  "result": "Line 1, Line 2, Line 3"
3
}

Response ignored

Tool returns data but the assistant doesn’t use it in conversation.

Fix line breaks and formatting

1
{
2
  "results": [
3
    {
4
      "toolCallId": "call_123",
5
      "result": "Temperature: 72°F\nCondition: Sunny\nHumidity: 45%"
6
    }
7
  ]
8
}

Verify HTTP status and JSON structure

Token truncation

Tool parameters or responses are getting cut off.

Increase token limits

The default token limit is only 100. Increase it for complex tools:

1
{
2
  "name": "complex_tool",
3
  "description": "Tool that needs more tokens",
4
  "parameters": {
5
    // ... your parameters
6
  },
7
  "maxTokens": 500 // Increase from default 100
8
}

Multiple tools scenarios

Some tools in parallel calls fail or return wrong results.

Handle multiple tool responses

Return all results in the same order as the calls were triggered:

1
{
2
  "results": [
3
    {
4
      "toolCallId": "call_1",
5
      "result": "First tool success"
6
    },
7
    {
8
      "toolCallId": "call_2",
9
      "error": "Second tool failed"
10
    },
11
    {
12
      "toolCallId": "call_3",
13
      "result": "Third tool success"
14
    }
15
  ]
16
}

Async vs sync behavior

Tool behavior doesn’t match your expectations.

1
{
2
  "name": "sync_tool",
3
  "async": false,  // or omit (default)
4
  // ... other config
5
}

Reference: Required formats

Response format template

1
{
2
  "results": [
3
    {
4
      "toolCallId": "call_123",
5
      "result": "Single-line string response"
6
    }
7
  ]
8
}

Tool schema template

1
{
2
  "name": "tool_name",
3
  "description": "Clear description of what the tool does",
4
  "parameters": {
5
    "type": "object",
6
    "properties": {
7
      "param1": {
8
        "type": "string",
9
        "description": "Parameter description"
10
      }
11
    },
12
    "required": ["param1"]
13
  },
14
  "strict": true,
15
  "maxTokens": 500,
16
  "async": false
17
}

Critical response rules

Debugging with call logs

Look for these key error messages in your call logs: