Skip to navigation
ToolsMCP tools

MCP tool messages and results

Control what the caller hears while an MCP tool runs and what the model receives back

This page covers what happens around each MCP tool call: what the caller hears while it runs, and how the server’s result reaches the model. To create a tool first, see MCP tools.

Spoken messages during tool calls

While a tool runs, Vapi can speak short messages to the caller. If you don’t configure any, Vapi says a short default phrase, such as “Give me a moment,” before each tool call.

To set your own messages:

  • messages applies to every tool from the server. In the Dashboard, set these under Messages on the MCP tool.
  • toolMessages sets messages for individual tools by the tool’s name on the server, without the prefix. Tools you don’t list use messages. Per-tool messages are API only.

Each message has one of these types:

TypeWhen it plays
request-startWhen the tool call starts.
request-response-delayedWhen the server hasn’t responded after timingMilliseconds.
request-completeWhen the server returns a result.
request-failedWhen the server returns an error (isError: true). Set endCallAfterSpokenEnabled to true to end the call after this message.
{
  "type": "mcp",
  "server": {
    "url": "https://mcp.example.com/mcp"
  },
  "messages": [
    { "type": "request-start", "content": "Let me check that for you." }
  ],
  "toolMessages": [
    {
      "name": "create_ticket",
      "messages": [
        { "type": "request-start", "content": "I'm creating your ticket now." },
        { "type": "request-complete", "content": "Your ticket is created." },
        { "type": "request-failed", "content": "I couldn't create the ticket right now." }
      ]
    }
  ]
}

An empty messages list removes your configured messages, but the default phrase still plays before the tool call. To replace the default phrase, set a request-start message.

For more information about message types, see Dynamic tool messages.

How results reach the model

Your server’s result reaches the model as follows:

  • content: the model receives the result’s content array as JSON text, for example [{"type":"text","text":"Order 1042 shipped on May 3."}].
  • structuredContent: not passed to the model. Put anything the model needs in content.
  • isError: when the result has isError: true, Vapi marks the call as failed and plays your request-failed message. The model gets the same content text with no error flag, so write the error as a clear sentence the model can explain to the caller.
  • Size: Vapi doesn’t shorten results. Large results use model context and can slow or break the conversation, so return only what the model needs.

For example, your server returns this response to a tools/call request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "Order 1042 shipped on May 3." }
    ],
    "structuredContent": { "orderId": "1042", "status": "shipped" },
    "isError": false
  }
}

The model receives only the content array as the tool result:

[{ "type": "text", "text": "Order 1042 shipped on May 3." }]

For the full result format, see Tool result in the MCP specification.

Next steps