> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voicebot.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Create and manage custom tools for your assistants

<Frame>
  <img src="https://voicebot-cdn.s3.eu-central-1.amazonaws.com/dashboard/tools-overview.png" alt="Tools Overview" />
</Frame>

## Custom Tools

Tools extend your assistant's capabilities by connecting to external services or implementing custom functionality. Each tool is configured through a simple four-step process.

<Note>
  Tools can be used to integrate with your existing systems, fetch data, or perform custom actions during calls.
</Note>

## Creating a Tool

<Tabs>
  <Tab title="Connection">
    <Frame>
      <img src="https://voicebot-cdn.s3.eu-central-1.amazonaws.com/dashboard/tools-connection.png" alt="Connection Configuration" />
    </Frame>

    ### Server Configuration

    <ParamField path="serverUrl" type="string" required label="Server URL">
      Endpoint where your tool implementation is hosted

      This is the URL that will be called when your tool is invoked
    </ParamField>

    <ParamField path="secretToken" type="password" label="Secret Token">
      Authentication token sent with each request

      Sent as `x-amira-secret` header for request verification
    </ParamField>

    <ParamField path="timeout" type="number" label="Timeout (seconds)">
      Maximum time to wait for server response

      Must be between 1 and 120 seconds
    </ParamField>

    ### Custom Headers

    <ParamField path="headers" type="array" label="Headers">
      Additional headers for server requests

      Each header can be configured with:

      * **Key**: Header name
      * **Value**: Header value
      * **Type**: String, Number, Boolean, or Object
    </ParamField>

    <Note>
      The Server URL is required to proceed. Other connection settings are optional but recommended for security and reliability.
    </Note>
  </Tab>

  <Tab title="Schema">
    <Frame>
      <img src="https://voicebot-cdn.s3.eu-central-1.amazonaws.com/dashboard/tools-schema.png" alt="Schema Definition" />
    </Frame>

    ### Data Structure

    Define the expected data structure for your tool:

    <ParamField path="properties" type="array" label="Properties">
      Each property requires:

      * **Name**: Unique identifier
      * **Type**: Data type (string, number, boolean, object, array)
      * **Required**: Whether the field is mandatory
      * **Description**: Clear explanation of the property's purpose
    </ParamField>

    <Note>
      A well-defined schema helps the AI understand and correctly format data for your tool.
    </Note>
  </Tab>

  <Tab title="Details">
    <Frame>
      <img src="https://voicebot-cdn.s3.eu-central-1.amazonaws.com/dashboard/tools-details.png" alt="Tool Details" />
    </Frame>

    ### Tool Information

    <ParamField path="name" type="string" required label="Name">
      Unique identifier for your tool

      Example: getUserInfo, lookupAddress, validateEmail
    </ParamField>

    <ParamField path="description" type="textarea" label="Description">
      Detailed explanation of your tool's purpose and functionality

      Help the AI understand when and how to use this tool effectively
    </ParamField>

    <ParamField path="asyncTool" type="boolean" label="Async Tool">
      Enable for non-blocking tool execution

      When enabled, the assistant continues conversation without waiting for tool response
    </ParamField>

    <Note>
      The tool name is required and should clearly indicate its functionality.
    </Note>
  </Tab>

  <Tab title="Messages">
    <Frame>
      <img src="https://voicebot-cdn.s3.eu-central-1.amazonaws.com/dashboard/tools-messages.png" alt="User Messages" />
    </Frame>

    ### User Feedback

    <ParamField path="startMessage" type="string" label="Start Message">
      Shown when tool execution begins

      Example: "Fetching user information..."
    </ParamField>

    <ParamField path="delayedMessage" type="string" label="Delayed Response Message">
      Displayed during longer processing times

      Example: "Still processing your request..."
    </ParamField>

    <ParamField path="successMessage" type="string" label="Success Message">
      Shown upon successful completion

      Example: "Information retrieved successfully"
    </ParamField>

    <ParamField path="errorMessage" type="string" label="Error Message">
      Displayed if tool execution fails

      Example: "Unable to fetch information. Please try again."
    </ParamField>

    <Note>
      Clear user messages improve the conversation experience by keeping users informed of tool status.
    </Note>
  </Tab>
</Tabs>

## Best Practices

<CardGroup cols={3}>
  <Card title="Security" icon="shield-check">
    Always use authentication and validate requests using the secret token
  </Card>

  <Card title="Reliability" icon="clock">
    Set appropriate timeouts and handle errors gracefully
  </Card>

  <Card title="User Experience" icon="user">
    Provide clear feedback messages for all tool states
  </Card>
</CardGroup>

<Note>
  Test your tools thoroughly before using them in production environments. Monitor their performance and user feedback to optimize their effectiveness.
</Note>