Overview

What this reference explains

A tool is a callable action a voice assistant can invoke mid-call. Sulus supports these tool types:

• apiRequest — calls an external HTTP endpoint with a configurable method, headers, request body schema and static fields, then optionally extracts variables from the response.
• function — a named function with a JSON-schema parameter list; the assistant decides when to call it and with what arguments.
• transferCall — transfers the live call to a number, SIP URI, another assistant, or a dynamically resolved destination.
• endCall — ends the call.
• dtmf — sends touch-tone digits during the call.
• handoff — hands the conversation off to another assistant or squad, carrying context across.
• voicemail — leaves a voicemail when the call reaches an answering machine.
• query — searches knowledge bases during the conversation.
• mcp — connects an MCP server. When each call or chat starts, the voice platform connects to the server's public https:// URL and gives the assistant every tool it exposes. Like other types it has a tool name and description, but no parameters: the server defines its own tools. Authenticate with server.credentialId (recommended) or server.headers.

This reference shows how the tools system works under the hood: every dashboard action goes through these endpoints, with exact fields, validation limits, storage columns and error responses.

The draft-and-publish lifecycle

Tools follow the same safe two-stage lifecycle as assistants and squads:

• Drafts are local-only. Creating or editing a draft never touches the live voice platform. Draft ids are recognisable local slugs (prefix draft_).
• Publishing goes live. The full store/update endpoints, and the dedicated publish endpoint, write to the live voice platform first, then mirror locally and flip the tool to published. If the live write fails, nothing is saved.
• A published tool saved as a draft is demoted to status: draft locally — the live tool keeps running untouched until it is published again, at which point the same upstream tool is patched in place.
• Duplicating always creates a local draft copy named "<name> (Copy)" — the live platform is never contacted.

Global Tools

A tool with no owner (user_id is null) is a platform Global Tool, made available across accounts. Global Tools are read-only for everyone except super admins: attempting to update, delete, or bulk-assign a Global Tool returns 403. Only a super admin may mark a tool global (the isGlobal switch on store/update), which clears its owner.

Personal credentials

The Credentials group manages the authenticated user's own server-auth credentials, used to authenticate outbound apiRequest/function calls (referenced by server.credentialId). A credential's auth type is immutable once created — changing it requires creating a new credential. Credentials support three authentication types: bearer, oauth2, and hmac, with an optional public-key encryption layer. Secrets are never returned by the API once stored.

Identifiers

The public identifier of a tool is external_tool_id: a UUID once published, or a local draft_… slug while it is a draft. Every path parameter written as {id} takes this value. The numeric row id is never exposed. A personal credential's public identifier is exposed as id.

Response envelope

The panel envelope, with tool-specific decorations:

{"success": true, "data": { …tool… , "read_only": false, "coreData": { … } }}

read_only is computed on every response (true for a Global Tool viewed by a non-super-admin). A platform mirror object also appears under coreData on store/update/publish responses; it is internal and not part of the documented contract.

Feature availability

This module is gated by the tools feature. When disabled, every endpoint under /tools returns 403 with {"message":"This feature is not enabled for your account. Please contact your administrator.","feature":"tools"}.