Troubleshoot tools

Overview

Troubleshoot and fix common issues with Function 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:

{
  "name": "get_weather",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name for weather lookup"
      }
    },
    "required": ["city"] // Must be array of required parameter names
  }
}

Enable schema validation

Add strict: true to catch validation errors early:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get current weather for a city",
    "parameters": {
      // ... your parameters
    },
    "strict": true
  }
}

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:

{
  "results": [
    {
      "toolCallId": "call_123",
      "result": "Your response as single-line string"
    }
  ]
}

Common format mistakes

// Return this with HTTP 200
{
  "results": [
    {
      "toolCallId": "call_123",
      "error": "Something went wrong"
    }
  ]
}

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

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

Response ignored

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

Fix line breaks and formatting

{
  "results": [
    {
      "toolCallId": "call_123",
      "result": "Temperature: 72°F\nCondition: Sunny\nHumidity: 45%"
    }
  ]
}

Verify HTTP status and JSON structure

Token truncation

Tool parameters or responses are getting cut off.

Increase the model token limit

Tool call arguments are generated by the model, so they draw on the same per-turn token budget as speech. Raise maxTokens on the assistant’s model, not on the tool. It accepts a value from 50 to 10000. When unset, the model applies its own default (currently 250).

Multiple tools scenarios

Some tools in parallel calls fail or return wrong results.

Handle multiple tool responses

Return a result for every tool call in the results array. Match each result to its call with toolCallId. Results can appear in any order.

{
  "results": [
    {
      "toolCallId": "call_1",
      "result": "First tool success"
    },
    {
      "toolCallId": "call_2",
      "error": "Second tool failed"
    },
    {
      "toolCallId": "call_3",
      "result": "Third tool success"
    }
  ]
}

Async vs sync behavior

Tool behavior doesn’t match your expectations.

{
  "name": "sync_tool",
  "async": false,  // or omit (default)
  // ... other config
}

For an async Function tool, Vapi returns an immediate Success. result to the assistant and does not use the webhook’s eventual response as the tool result. Inspect the later webhook response in Logs → Webhooks and check your server logs for the completed action. See Call logs for the Function and API Request log locations.

Reference: Required formats

Response format template

{
  "results": [
    {
      "toolCallId": "call_123",
      "result": "Single-line string response"
    }
  ]
}

Tool schema template

{
  "type": "function",
  "async": false,
  "function": {
    "name": "tool_name",
    "description": "Clear description of what the tool does",
    "parameters": {
      "type": "object",
      "properties": {
        "param1": {
          "type": "string",
          "description": "Parameter description"
        }
      },
      "required": ["param1"]
    },
    "strict": true
  },
  "server": {
    "url": "https://your-server.com/webhook"
  }
}

name, description, parameters and strict belong inside function. type, async and server sit on the tool itself.

Critical response rules

Debugging with call logs

Look for these key error messages in your call logs: