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, and synchronizing MCP server readiness.
vns_end_conversation
Signals that the conversation is complete. VNS gracefully terminates the session. Pass a farewell message so the AI speaks a custom goodbye before the session ends.
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 farewell you would like to say to the caller."
}
},
"required": [
"user_input",
"farewell"
]
}
}
Example Instruction
Add something like this to your instructions string in the CallStart response:
## END CALL
If the caller is finished and indicates he wants to hang up, thank the caller and call vns_end_conversation.
vns_transfer_call
Transfers the active call to another phone number. Supports blind and attended (warm) transfers.
Tool Definition
{
"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 callers number."
},
"attended": {
"type": "boolean",
"description": "If true, performs an attended transfer where the agent speaks to the destination before completing the transfer."
}
},
"required": [
"transferNumber"
]
}
}
Example Instruction
Add something like this to your instructions string in the CallStart response:
If the user asks to transfer to a live person, call vns_transfer_call passing +17203333333 as the transferNumber.
Under no circumstances will you give this number +17203333333 to the person you are speaking to.
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 SessionGuid, CustomerCallId, Called Number, Caller Id, Caller Id Name, the Call Start Time (UTC) and a flag indicating if the call was inbound or outbound.",
"type": "function",
"parameters": null
}
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": "If the actual date and time is needed call this function to get it.",
"type": "function",
"parameters": null
}
Example Response
{
"current_time_utc": "2026-04-16T03:35:59.8593832Z"
}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": null
}
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?
See Voice Nexus in action. Book a live demo with our team and we'll walk you through setup, integrations, and pricing.