Copy page

Guides

Tools and Actions

Tools let your agent take actions during live calls — look up orders, create tickets, send messages, query databases, and more. The agent's LLM decides when to invoke a tool based on the conversation, executes it, and incorporates the result into its next response.

Prerequisites: Neuratel account, agent created

---

How tool execution works

1. You define tools with a name, description, and parameter schema.
2. During a call, the LLM evaluates whether a tool is relevant to the current turn.
3. The agent sends a request to the tool's URL with the extracted parameters.
4. The tool returns a result.
5. The agent reads the result and continues the conversation.

The caller hears no gap — background audio plays during tool execution, and the agent responds as soon as the result arrives.

---

Function calling tools

Function tools are custom HTTP endpoints that the agent can call. Define them in the tools.items array of your agent configuration.

Tool schema format

Each tool requires a name, description, and parameters object following JSON Schema:

Code
{
  "tools": {
    "items": [
      {
        "type": "function",
        "name": "check_order_status",
        "description": "Check the status of a customer order by order ID",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string",
              "description": "The order ID to check"
            }
          },
          "required": ["order_id"]
        },
        "url": "https://your-api.com/orders/{order_id}"
      }
    ]
  }
}

Adding tools via the API

Code
curl -X PATCH https://api.neuratel.ai/v1/agents/agent_abc123 \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": {
      "items": [
        {
          "type": "function",
          "name": "check_order_status",
          "description": "Check the status of a customer order by order ID",
          "parameters": {
            "type": "object",
            "properties": {
              "order_id": {
                "type": "string",
                "description": "The order ID to check"
              }
            },
            "required": ["order_id"]
          },
          "url": "https://your-api.com/orders/{order_id}"
        },
        {
          "type": "function",
          "name": "create_support_ticket",
          "description": "Create a support ticket for follow-up after the call",
          "parameters": {
            "type": "object",
            "properties": {
              "subject": {
                "type": "string",
                "description": "Short summary of the issue"
              },
              "description": {
                "type": "string",
                "description": "Detailed description of the problem"
              },
              "priority": {
                "type": "string",
                "enum": ["low", "medium", "high"],
                "description": "Ticket priority level"
              }
            },
            "required": ["subject", "description"]
          },
          "url": "https://your-api.com/tickets"
        }
      ]
    }
  }'

Code
import httpx

client = httpx.Client(
    base_url="https://api.neuratel.ai",
    headers={"Authorization": "Bearer nk_live_your_api_key"},
)

client.patch("/v1/agents/agent_abc123", json={
    "tools": {
        "items": [
            {
                "type": "function",
                "name": "check_order_status",
                "description": "Check the status of a customer order by order ID",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "order_id": {
                            "type": "string",
                            "description": "The order ID to check",
                        }
                    },
                    "required": ["order_id"],
                },
                "url": "https://your-api.com/orders/{order_id}",
            },
            {
                "type": "function",
                "name": "create_support_ticket",
                "description": "Create a support ticket for follow-up after the call",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "subject": {"type": "string", "description": "Short summary of the issue"},
                        "description": {"type": "string", "description": "Detailed description"},
                        "priority": {
                            "type": "string",
                            "enum": ["low", "medium", "high"],
                        },
                    },
                    "required": ["subject", "description"],
                },
                "url": "https://your-api.com/tickets",
            },
        ]
    }
})

Code
await fetch("https://api.neuratel.ai/v1/agents/agent_abc123", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer nk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tools: {
      items: [
        {
          type: "function",
          name: "check_order_status",
          description: "Check the status of a customer order by order ID",
          parameters: {
            type: "object",
            properties: {
              order_id: {
                type: "string",
                description: "The order ID to check",
              },
            },
            required: ["order_id"],
          },
          url: "https://your-api.com/orders/{order_id}",
        },
        {
          type: "function",
          name: "create_support_ticket",
          description: "Create a support ticket for follow-up after the call",
          parameters: {
            type: "object",
            properties: {
              subject: { type: "string", description: "Short summary of the issue" },
              description: { type: "string", description: "Detailed description" },
              priority: { type: "string", enum: ["low", "medium", "high"] },
            },
            required: ["subject", "description"],
          },
          url: "https://your-api.com/tickets",
        },
      ],
    },
  }),
});

---

MCP server integration

The Model Context Protocol (MCP) is an open standard for connecting LLMs to external data and tools. Neuratel supports MCP server connections, giving your agents access to tools exposed by any MCP-compatible server.

Connect an MCP server

Code
curl -X POST https://api.neuratel.ai/v1/integrations \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mcp",
    "name": "Order Management",
    "server_url": "https://your-mcp-server.com/mcp",
    "description": "Order lookup, creation, and cancellation"
  }'

Code
integration = client.post("/v1/integrations", json={
    "type": "mcp",
    "name": "Order Management",
    "server_url": "https://your-mcp-server.com/mcp",
    "description": "Order lookup, creation, and cancellation",
}).json()

print(integration["id"])  # int_abc123

Code
const integration = await fetch("https://api.neuratel.ai/v1/integrations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "mcp",
    name: "Order Management",
    server_url: "https://your-mcp-server.com/mcp",
    description: "Order lookup, creation, and cancellation",
  }),
}).then((r) => r.json());

console.log(integration.id); // int_abc123

List tools from a connected MCP server

Code
curl https://api.neuratel.ai/v1/integrations/mcp/int_abc123/tools \
  -H "Authorization: Bearer nk_live_your_api_key"

Response:

Code
{
  "tools": [
    {
      "name": "lookup_order",
      "description": "Look up order status by order ID",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" }
        },
        "required": ["order_id"]
      }
    },
    {
      "name": "cancel_order",
      "description": "Cancel an order by order ID",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" },
          "reason": { "type": "string" }
        },
        "required": ["order_id"]
      }
    }
  ]
}

---

Built-in tools

Every agent has access to three built-in tools that do not require any configuration:

Tool	Description
Call transfer	Transfer the call to a phone number defined in the transfer config
Knowledge base lookup	Search attached knowledge bases for relevant information
Voicemail	Take a message when the caller requests it

Built-in tools are invoked automatically when the LLM determines they are needed based on the system prompt and conversation context. You do not need to define them in tools.items.

---

Writing effective tool descriptions

The LLM uses the tool description to decide when to call it. A poorly written description leads to missed invocations or incorrect usage.

Good:

Code
"Check the status of a customer order by order ID. Returns current status, estimated delivery date, and tracking number."

Bad:

Code
"Order lookup"

Guidelines:

• Start with a verb: "Check", "Create", "Send", "Look up"
• Include what the tool returns
• Mention constraints: "Only works for orders placed in the last 90 days"
• Write parameter descriptions as if explaining to someone unfamiliar with your system

---

Testing tools

In the dashboard

1. Open your agent in Agent Studio.
2. Go to the Tools tab.
3. Click Test Tool next to any tool.
4. Enter sample parameter values.
5. Click Execute and inspect the response.

Via call logs

After a test call, check the tool_calls field in the call record:

Code
curl https://api.neuratel.ai/v1/voice-sessions/call_xyz789 \
  -H "Authorization: Bearer nk_live_your_api_key"

Each tool call in the response includes the parameters the LLM sent, the response received, and the latency.

---

Debugging

Symptom	Cause	Fix
Tool never called	Description does not match conversation context	Rewrite the description to match how callers phrase their requests
Tool called with wrong parameters	Parameter descriptions are ambiguous	Add clearer descriptions and examples to each parameter
Tool times out	Endpoint is too slow	Ensure your endpoint responds within 5 seconds
Tool called at the wrong time	Too many tools with overlapping descriptions	Reduce tool count or make descriptions more specific

---

Related

• Agent Studio — Tools tab
• Knowledge Base — document-backed RAG search
• Events and Webhooks — receive events after tool executions
• Workflow Builder — orchestrate multi-step tool flows