Tools – Usage Guide

Extending the Power of the Digital Human

Digital Humans are more than chatbots—they are assistants, analysts, editors, designers. But to be truly useful in real workflows, they need to do more than just talk.

Tools can also be used to connect the Digital Human with automation platforms like Zapier, Make, or n8n. This allows them to trigger workflows, move data between apps, send messages, update CRMs, or even control physical systems—bridging the gap between natural language and real-world action.

This guide explains how to extend the capabilities of your Digital Human in UNITH using Tools—custom integrations that allow your assistant to take real actions: send data, call APIs, trigger workflows, or fetch internal resources.

What is a “Tool”?

In UNITH, a tool is a special capability that a Digital Human can activate during a conversation to do something beyond just talking.

Each Tool acts as a bridge between natural language and specialized software capabilities. When a user makes a request—explicitly or implicitly—the Digital Human can choose to invoke a Tool, retrieve results, and integrate them into the response in real time.

This makes Tools a key ingredient in transforming Digital Humans from passive conversationalists into active collaborators.

What does a Tool actually do?

A Tool is, in essence, a function call to an external system, triggered by the LLM based on the flow of a conversation. It's like giving the Digital Human a button to push—when the right context appears, it pushes it for you.

Here are some examples:

• When a user says “Can you open a support ticket for me?”, the Digital Human can extract the user’s name, email, and problem, then call a tool (webhook) that creates a ticket in your helpdesk system.

The LLM interprets this logic, collects the required data throughout the conversation, and when all parameters are present, fires off a request to the tool’s endpoint.

Tool Configuration via API

For now, tools are configured programmatically through the UNITH API. Support for tool management directly in interFace is coming soon.

When you configure a tool, you're telling the Digital Human what the tool does, what input it needs, and where to send the data. This is done with a JSON definition, which you send to the UNITH API using a PUT request.

Step 1: Write the Tool JSON

The JSON describes:

• What the tool is called (name)
• What it does (description)
• What parameters it needs from the user (e.g. name, email, issue)
• Where to send the data (url – typically your API or a webhook)

Example: Tool to create a support ticket

Step 2: Apply the Tool to a Digital Human

Use the /head/{id}/conversation-settings endpoint with the PUT method to configure one or more tools for a Digital Human.

Replace:

• {HEAD_ID} with the ID of your Digital Human (available in the "Basic Details" section in interFace)
• The Authorization token with your Bearer Token
• The -d body with your tool JSON

Example full request:

Once this is applied, the tool is immediately available to be triggered by the LLM during conversations.

Step 3. Defining Context in the Prompt

Tools don’t activate themselves—you guide them.

The Digital Human decides when and how to use a tool based on your prompt. The more specific your prompt, the better the tool works.

You must include instructions in the prompt that define:

• Declaring Tools
  • "You have access to one tool: Create_Ticket"
• What condition should trigger the tool
  • “As soon as the user wants to report a problem...”
• Which parameters to collect
  • userName = user's full name
  • userEmail = user's email address
  • userIssue = short description of the user's problem
• How/when to call the tool
  • "As soon as the user provides the last missing parameter, immediately call the tool Create_Ticket with the parameters userName, userEmail and userIssue."
• Any fallback or validation logic
  • “If the user refuses to give an email, explain that it’s required.”

✅ Good prompt:

🚫 Vague prompt:

Optional Tools Parameters

You can use optional parameters to improve the experience even further.

Example Configuration

{
  "tools": [
    {
      "name": "WeatherChecker",
      "description": "Get current weather information for any city worldwide",
      "parameters": [
        {
          "name": "city",
          "type": "string",
          "description": "The city name to check weather for"
        }
      ],
      "url": "https://your-tool-endpoint.com/weather",
      "has_suggestions": 1,
      "direct_msg": 0,
      "api_key": "your-api-key"
    }
  ]
}

Custom Tool Parameters

Tool Response Format

Your custom tool endpoint must return JSON in the following format:

Basic Response

{
  "status": "OK",
  "answer": "It's 75°F and sunny in New York"
}

Response with Suggestions (when has_suggestions: 1)

{
  "status": "OK",
  "answer": "It's 75°F and sunny in New York",
  "suggestions": [
    "Check hourly forecast",
    "Weather for tomorrow",
    "Weather in nearby cities"
  ]
}

Advanced Tool Features

has_suggestions

Allows your tool to provide clickable follow-up conversation suggestions to guide users.

When to Use:

• Guide conversation flow naturally
• Tool responses often lead to related questions
• Improve user engagement with predefined actions

Configuration:

{
  "has_suggestions": 1  // Enable suggestions
}

direct_msg

Bypasses AI processing and sends the tool response directly to the user, reducing latency.

When to Use:

• Tool provides direct responses
• Faster response times are critical
• Tool output doesn't need AI enhancement or contextualization

When NOT to Use:

• Tool responses need AI formatting or enhancement
• You want consistent conversational tone
• Tool returns technical data requiring explanation

Configuration:

  "direct_msg": 1  // Send response directly to user

Knowledge Base with Custom Tools

In Knowledge Base (doc_qa) mode, the built-in context_search tool is automatically included alongside your custom tools, allowing the AI to search documents or trigger workflows as needed.

{
  "conversationSettings": {
    "chat_model_settings": {
      "provider": "openai",
      "llm_name": "gpt-4o-mini",
      "max_llm_tokens": 8096,
      "api_key": "your api key"
    },
    "tools": [
      {
        "name": "UpdateCustomerRecord",
        "description": "Use this tool when the user requests to update their contact information, preferences, or account settings. Updates customer data in the CRM system.",
        "parameters": [
          {
            "name": "customer_id",
            "type": "string",
            "description": "The customer's unique identifier"
          },
          {
            "name": "field_to_update",
            "type": "string",
            "description": "The field being updated (email, phone, address, etc.)"
          },
          {
            "name": "new_value",
            "type": "string",
            "description": "The new value for the field"
          }
        ],
        "url": "https://n8n.example.com/webhook/update-customer",
        "has_suggestions": 0,
        "direct_msg": 0,
        "api_key": "n8n_api_key_xyz789"
      }
    ]
  }
}