Tool Templates

Define reusable tool configurations that can be easily added to multiple assistants.

Tool templates let you define reusable tool configurations that can be easily added to multiple assistants. Instead of copying tool definitions, create templates and reference them when configuring assistants.

What are Tool Templates?

A tool template defines:

Tool type - Function, end call, or transfer
Name and description - For LLM understanding
Parameters - JSON Schema for inputs
Configuration - URLs, async settings, etc.

Creating a Tool Template

Function Tool Template

curl -X POST https://api.hmsovereign.com/api/v1/tool-templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lookup_customer",
    "description": "Look up customer information by phone number or email. Use when you need to verify customer identity or retrieve their account details.",
    "type": "function",
    "url": "https://api.example.com/webhooks/lookup",
    "async": false,
    "parameters": {
      "type": "object",
      "properties": {
        "phone": {
          "type": "string",
          "description": "Customer phone number in E.164 format"
        },
        "email": {
          "type": "string",
          "description": "Customer email address"
        }
      }
    }
  }'

Response:

{
  "tool_template": {
    "id": "template-uuid",
    "name": "lookup_customer",
    "description": "Look up customer information...",
    "type": "function",
    "url": "https://api.example.com/webhooks/lookup",
    "async": false,
    "parameters": { ... },
    "created_at": "2025-12-13T10:00:00.000Z"
  }
}

End Call Tool Template

curl -X POST https://api.hmsovereign.com/api/v1/tool-templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "end_call",
    "description": "End the call when the conversation is complete",
    "type": "end_call"
  }'

Transfer Call Tool Template

curl -X POST https://api.hmsovereign.com/api/v1/tool-templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "transfer_to_support",
    "description": "Transfer to human support team",
    "type": "transfer_call",
    "destinations": [
      {
        "type": "number",
        "number": "+31612345678",
        "description": "Human support assistant for complex issues",
        "message": "I'm transferring you to a colleague, one moment please."
      }
    ]
  }'

Template Fields

Field	Type	Required	Description
`name`	string	Yes	Tool name (used by LLM)
`description`	string	Yes	What the tool does
`type`	string	Yes	`function`, `end_call`, or `transfer_call`
`url`	string	No	Webhook URL for function tools
`async`	boolean	No	Fire-and-forget mode (default: false)
`async_response`	string	No	Response for async tools
`parameters`	object	No	JSON Schema for inputs
`destinations`	array	No	Transfer destinations (for transfer_call)

Using Templates with Assistants

Templates are used by adding tools to an assistant's llm_config.tools array. Each tool that originates from a template includes a _template_id field that links it back to the template.

When you update a template, all assistants that use it are automatically synced — the tool definition is updated in every agent's llm_config.tools.

To add a template-based tool to an assistant, include it in llm_config.tools with the _template_id field:

curl -X PATCH https://api.hmsovereign.com/api/v1/assistants/ASSISTANT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "llm_config": {
      "tools": [
        {
          "_template_id": "lookup-template-uuid",
          "name": "lookup_customer",
          "description": "Look up customer information by phone number or email.",
          "parameters": {
            "type": "object",
            "properties": {
              "phone": { "type": "string" }
            }
          },
          "url": "https://api.example.com/webhooks/lookup"
        }
      ]
    }
  }'

The easiest way to add templates to an assistant is via the dashboard — select templates directly in the assistant editor and they are added automatically with the correct _template_id reference.

Template Examples

Check Appointment Availability

{
  "name": "check_availability",
  "description": "Check available appointment slots for a given date and service type. Use when customer wants to book an appointment.",
  "type": "function",
  "url": "https://api.example.com/webhooks/availability",
  "parameters": {
    "type": "object",
    "properties": {
      "date": {
        "type": "string",
        "description": "Date to check in YYYY-MM-DD format"
      },
      "service": {
        "type": "string",
        "description": "Type of service requested"
      }
    },
    "required": ["date"]
  }
}

Book Appointment

{
  "name": "book_appointment",
  "description": "Book an appointment for the customer. Only use after confirming the date, time, and service with the customer.",
  "type": "function",
  "url": "https://api.example.com/webhooks/book",
  "parameters": {
    "type": "object",
    "properties": {
      "date": {
        "type": "string",
        "description": "Appointment date in YYYY-MM-DD format"
      },
      "time": {
        "type": "string",
        "description": "Appointment time in HH:MM format"
      },
      "service": {
        "type": "string"
      },
      "customer_name": {
        "type": "string"
      },
      "notes": {
        "type": "string"
      }
    },
    "required": ["date", "time", "customer_name"]
  }
}

Log Event (Async)

{
  "name": "log_interest",
  "description": "Log that the customer expressed interest in a product for sales follow-up",
  "type": "function",
  "url": "https://api.example.com/webhooks/log",
  "async": true,
  "async_response": "I've noted your interest for our team to follow up.",
  "parameters": {
    "type": "object",
    "properties": {
      "product": {
        "type": "string",
        "description": "Product the customer is interested in"
      },
      "notes": {
        "type": "string",
        "description": "Additional notes about the interest"
      }
    },
    "required": ["product"]
  }
}

Multi-Destination Transfer

{
  "name": "transfer_call",
  "description": "Transfer the call to the appropriate department",
  "type": "transfer_call",
  "destinations": [
    {
      "type": "number",
      "number": "+31612345678",
      "description": "Sales team - for pricing, quotes, and new business",
      "message": "I'm transferring you to our sales team."
    },
    {
      "type": "number",
      "number": "+31687654321",
      "description": "Technical support - for product issues and troubleshooting",
      "message": "I'm transferring you to technical support."
    },
    {
      "type": "number",
      "number": "+31698765432",
      "description": "Billing - for invoice and payment questions",
      "message": "I'm transferring you to the billing department."
    }
  ]
}

Listing Templates

curl https://api.hmsovereign.com/api/v1/tool-templates \
  -H "Authorization: Bearer YOUR_API_KEY"

Updating a Template

curl -X PATCH https://api.hmsovereign.com/api/v1/tool-templates/TEMPLATE_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description for better LLM understanding"
  }'

Deleting a Template

curl -X DELETE https://api.hmsovereign.com/api/v1/tool-templates/TEMPLATE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Note: Deleting a template does not affect assistants currently using it. Tools are stored as objects in the assistant configuration, not as references.

On this page