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 https //docs unith ai/zapier integration , https //docs unith ai/make integration , or https //docs unith ai/n8n integration 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 in this guide, you’ll learn what tools are and how they work how to configure them via api how to define prompt logic so the llm knows when and how to use them best practices to ensure reliable behavior use of optional parameters for tool calling 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 https //app unith ai/ is coming soon note no api config needed if you're using zapier if you're using zapier , there's no need to configure tools manually via the api you can use the official https //docs unith ai/zapier integration , which handles tool exposure and triggering automatically if you prefer working with other automation platforms , you can also follow our dedicated guides for https //docs unith ai/make integration or https //docs unith ai/n8n integration 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 { "conversationsettings" { "tools" \[ { "name" "create ticket", "description" "opens a support ticket with the user's information ", "parameters" \[ { "name" "username", "description" "user's full name", "type" "string" }, { "name" "useremail", "description" "user's email address", "type" "string" }, { "name" "userphone", "description" "user's phone number", "type" "string" }, { "name" "userissue", "description" "description of the issue reported", "type" "string" } ], "url" "https //yourdomain com/api/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 https //platform api unith ai/head/ {head id} {head id} /conversation settings replace {head id} with the id of your digital human (available in the "basic details" section in interface) the authorization token with your https //docs unith ai/user#wyclw the d body with your tool json example full request curl x 'put' \\ 'https //platform api unith ai/head/ 1234567890 1234567890 /conversation settings' \\ h 'accept application/json' \\ h 'authorization bearer abcdef123456 abcdef123456 ' \\ h 'content type application/json' \\ d ' { "conversationsettings" { "tools" \[ { "name" "create ticket", "description" "opens a support ticket ", "parameters" \[ ], "url" "https //yourdomain com/api/ticket" } ] } { "conversationsettings" { "tools" \[ { "name" "create ticket", "description" "opens a support ticket ", "parameters" \[ ], "url" "https //yourdomain com/api/ticket" } ] } } ' 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 available tools you have access to one tool \ create ticket this tool opens a support ticket with the user's information it requires the following parameters username = the user's full name useremail = the user's email address userissue = a short description of the problem trigger condition & parameter collection as soon as the user wants to report an issue—this could include phrases like “i need help”, “i have a problem”, “can i open a ticket?”, or similar—ask for the username, useremail and userissue tool activation logic once the user provides the last missing parameter, immediately call the tool create ticket with the parameters username, useremail and userissue fallback & validation if the user refuses to provide their email address, explain that it is required in order to open a support ticket if any of the required fields is missing or unclear, ask a follow up question to complete the information before triggering the tool 🚫 vague prompt you can use tools to help the user if they have a problem, try to collect their information and open a ticket important notes the llm can make inferred decisions —it doesn’t need fixed rules but benefits from examples or clear intent instructions the model only triggers a tool when the conditions are met , so you can avoid accidental calls 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 parameter required description example (advanced) has suggestions ❌ enable follow up suggestions (1=yes, 0=no) 1 (advanced) direct msg ❌ bypass ai processing for tool response (1=yes, 0=no) 0 api key ❌ authentication key for the tool endpoint "sk abc123 " 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 ) https //docs unith ai/create a digital human , 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" } ] } }