Developer Guide / Built-in VNS Tools

Built-in VNS Tools

Ready-to-use tools that VNS resolves internally during any voice session — no webhook endpoint required on your server.

Overview

VNS ships with built-in tools that are handled entirely inside Voice Nexus Service. When the AI model invokes one of these tools, VNS intercepts the call and responds directly — your server is never contacted. To make a built-in tool available to the AI, include its definition in the tools array of your CallStart response.

Because VNS resolves these tools internally, you can use them without standing up any extra endpoints. They cover the most common session-management operations: ending a call gracefully, transferring to a live agent, reading call metadata, fetching the current time, sending an SMS, and synchronizing MCP server readiness.

Note: All built-in tools are resolved internally by VNS. No tool webhook call is made to your server when the AI invokes them.

vns_end_conversation

Signals that the conversation is complete. VNS plays the farewell to the caller, lets it finish, and then gracefully terminates the session — so the call never ends before the goodbye is heard.

  • Define both user_input and farewell and make both required.
  • Tell the model to put its complete caller-facing closing sentence in farewell, wait for the tool result, and not speak another farewell itself.

If farewell is missing, VNS falls back to a plain "Goodbye!" for backward compatibility. That fallback is error tolerance, not the recommended contract.

Tool Definition

{
  "name": "vns_end_conversation",
  "description": "If the user says something about ending the conversation, like goodbye, call this function to let the application know.",
  "type": "function",
  "parameters": {
    "type": "object",
    "properties": {
      "user_input": {
        "type": "string",
        "description": "Input from the user indicating they want to end the conversation."
      },
      "farewell": {
        "type": "string",
        "description": "The complete farewell to say to the caller before ending the call."
      }
    },
    "required": ["user_input", "farewell"],
    "additionalProperties": false
  }
}

Example Instruction

Add something like this to your instructions string in the CallStart response:

## END CALL
When the caller is finished, call vns_end_conversation.
Put your complete closing sentence (for example, "Thanks for calling Acme. Have a great day!") in the farewell argument, then wait for the tool result.
Do not speak a separate goodbye yourself; the farewell is played to the caller before the call ends.

vns_transfer_call

Transfers the active call. Supports blind and attended (warm) transfers. The recommended form lets the model pick a named transfer service that you configure in transferServices; list exactly those names in enum. See Transfer Call Options for service configuration, dialing modes, attended decisions, caller restoration, and CallEnd evidence.

Tool Definition (recommended: named service)

{
  "name": "vns_transfer_call",
  "description": "Transfers the current call using a configured transfer service.",
  "type": "function",
  "parameters": {
    "type": "object",
    "properties": {
      "transferService": {
        "type": "string",
        "description": "The configured transfer service to use.",
        "enum": ["Support", "Billing"]
      }
    },
    "required": ["transferService"],
    "additionalProperties": false
  }
}

Legacy Tool Definition (direct number)

Still supported for compatibility. Named transfer services are preferred for managed and attended behavior — per-service options such as hold media, pre-transfer announcements, and decision timeouts are only available on a configured transfer service.

{
  "name": "vns_transfer_call",
  "description": "Transfers the current call to another number.",
  "type": "function",
  "parameters": {
    "type": "object",
    "properties": {
      "transferNumber": {
        "type": "string",
        "description": "The phone number to transfer the call to, preferably in E.164 format like +13035551212"
      },
      "useVnsNumberAsCallerId": {
        "type": "boolean",
        "description": "If true, uses the Called Number as the outbound caller ID for the transferred call, otherwise it uses the caller's number."
      },
      "attended": {
        "type": "boolean",
        "description": "If true, performs an attended transfer where the agent speaks to the destination before completing the transfer."
      }
    },
    "required": ["transferNumber"],
    "additionalProperties": false
  }
}
Attended transfers: the recipient-side tools vns_attended_transfer_accepted and vns_attended_transfer_declined are consultation-only tools used while the AI talks to the destination. They're documented on Transfer Call Options, not here, because the caller-side agent never calls them.

Example Instruction

Add something like this to your instructions string in the CallStart response:

## TRANSFERS
If the caller asks for Support, call vns_transfer_call with transferService set to "Support".
If the caller has a billing question you can't answer, call vns_transfer_call with transferService set to "Billing".
Never read transfer phone numbers to the caller.
To end the call, if requested, call vns_end_conversation.

vns_get_call_info

Returns metadata about the current call session without hard-coding it into your instructions. Provides the session GUID, customer call ID, called number, caller ID, caller ID name, call start time (UTC), and a flag indicating whether the call is inbound or outbound.

Tool Definition

{
  "name": "vns_get_call_info",
  "description": "Call this function to get information about the Called Number, Caller Id, Caller Id Name, the Call Start Time (UTC), whether the call was inbound or outbound, the SessionGuid, and the CustomerCallId.",
  "type": "function",
  "parameters": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

Example Response

VNS feeds this payload back to the AI model:

{
  "sessionGuid": "B7E60598-0729-4410-922F-3A83DF863BFD",
  "calledNumber": "+13035551212",
  "callerId": "+13035559999",
  "callerIdName": "Business Name",
  "outboundTriggered": false,
  "callStart": "2026-04-16T03:35:59.8593832Z",
  "customerCallId": "8ADD2CC6-BB94-4C5F-BD1D-DBDF91D39052"
}

vns_get_utc_datetime

Returns the current UTC date and time. Useful when the AI needs the current time for scheduling, appointment booking, or logging — without embedding a timestamp in your static instructions.

Tool Definition

{
  "name": "vns_get_utc_datetime",
  "description": "Retrieves the current UTC date and time.",
  "type": "function",
  "parameters": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

Example Response

{
  "current_time_utc": "2026-04-16T03:35:59.8593832Z"
}

vns_send_sms

Sends an SMS during the call — for example, a booking confirmation or a link the caller asked for. You authorize the sending numbers in your CallStart response; the model only ever refers to them by a friendly key.

CallStart Authorization Fields

{
  "VoiceElements_Instructions": {
    "smsNumbers": {
      "CustomerService": "+17208829100"
    },
    "smsToNumberUnrestricted": false
  }
}
  • smsNumbers — maps friendly keys (such as CustomerService) to the numbers VNS may send from. The model passes the key as smsId; it never selects the actual sender number directly.
  • smsToNumberUnrestricted — false by default, which limits to to caller, callednumber, or a friendly key from smsNumbers (to text one of your own configured numbers). Set it to true only if the model must be able to text other E.164 numbers.

Tool Definition

{
  "name": "vns_send_sms",
  "description": "Call this function to send an SMS message.",
  "type": "function",
  "parameters": {
    "type": "object",
    "properties": {
      "smsId": {
        "type": "string",
        "description": "Friendly key from smsNumbers that identifies the number used to send the message."
      },
      "to": {
        "type": "string",
        "description": "Who receives the message: 'caller', 'callednumber', or a friendly key from smsNumbers. A custom E.164 number is allowed only when smsToNumberUnrestricted is true."
      },
      "text": {
        "type": "string",
        "description": "The text of the message to be sent."
      }
    },
    "required": ["smsId", "to", "text"],
    "additionalProperties": false
  }
}

Example Instruction

Add something like this to your instructions string in the CallStart response:

## TEXT MESSAGES
If the caller asks for a text confirmation, call vns_send_sms with smsId "CustomerService", to "caller", and a short message containing the confirmation details.
Tell the caller the text is on its way only after the tool result confirms it was sent.

VNS returns the send result to the model as the tool output. SMS provider credentials are managed by Voice Elements and never appear in your configuration or tool results.

vns_allow_mcp_calls

Required when using MCP servers. The AI connects to MCP servers asynchronously after the session starts. When the AI calls this tool, VNS holds the response and waits for the AI to send a confirmation that all MCP servers have finished loading — only then does VNS unblock and allow the AI to proceed. Without it, the AI may attempt to invoke MCP tools before they are available. See the MCP Integration guide →

Tool Definition

{
  "name": "vns_allow_mcp_calls",
  "description": "Call this function to ensure that the mcp servers are ready.",
  "type": "function",
  "parameters": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

Example Instruction

Add something like this to your instructions string in the CallStart response. While the AI waits for the response it should keep the caller engaged:

Before calling any MCP server tool you MUST first call vns_allow_mcp_calls to verify the MCP server is ready. While waiting for vns_allow_mcp_calls to return, tell the caller something like "One moment please, I'll be right with you" or "Just a moment while I get that ready for you".

Ready to Automate Your Phone Lines?

Create your account in VnsPortal and set up your first agent from a template today — or book a live demo and we'll walk you through it.

Get Started Book a Demo

Questions first? Contact sales