Tool types

zoxaAI has two separate tool formats that look similar but have different field names and validation rules:

Pick the right one for the call you're making. The shapes are not interchangeable — sending a saved-tool transferCall config inline will fail validation because the inline schema rejects fields like messageType and audioRecordingId on transferCall.

Saved-tool definition

All saved-tool definitions share two common keys:

function (HTTP API)

Call an external HTTP API. The LLM fills in parameters; the runner makes the request.

{
  "schema_version": 1,
  "type": "function",
  "config": {
    "method": "GET",
    "url": "https://api.acme.com/orders/{orderId}",
    "headers": { "X-Tenant": "acme" },
    "credential_uuid": "cred-abc12345-6789-0123-4567-89abcdef0123",
    "parameters": [
      { "name": "orderId", "type": "string", "description": "Order ID", "required": true }
    ],
    "timeout_ms": 5000,
    "customMessages": ["Looking that up now...", "Still checking..."],
    "customMessageType": "text"
  }
}

Validation

• method and parameter type are strict enums; timeout_ms is 1000..30000; a non-empty url must be http(s)://.
• Creation (POST /tools) accepts a placeholder-empty config (url: "", empty KB groups, empty transfer destination) so the dashboard can store a blank tool for editing. Saving (PUT /tools/{uuid}) refuses incomplete definitions: an HTTP tool needs a url, a transfer tool a destination, a KB tool at least one group — 400 with a clear detail otherwise.
• definition.type must always match the tool's category (fixed at creation).
• Conditional requirements everywhere: messageType/customMessageType custom/text needs its message(s), audio needs its recording id.

endCall

Lets the LLM explicitly end the call. Configurable goodbye message.

{
  "schema_version": 1,
  "type": "endCall",
  "config": {
    "messageType": "custom",
    "customMessage": "Thanks for calling. Goodbye!"
  }
}

transferCall

Warm or cold transfer the call to a phone number or SIP endpoint.

{
  "schema_version": 1,
  "type": "transferCall",
  "config": {
    "destination": "+14155551234",
    "messageType": "custom",
    "customMessage": "Transferring you now.",
    "timeout": 30,
    "recordTransfer": true
  }
}

calculator

Built-in math evaluator. Lets the LLM compute arithmetic without hallucinating arithmetic. No config.

{
  "schema_version": 1,
  "type": "calculator"
}

query (knowledge base)

Retrieve from one or more named knowledge-base groups during the call.

{
  "schema_version": 1,
  "type": "query",
  "config": {
    "groups": [
      {
        "name": "billing",
        "description": "Pricing, refunds, plan changes.",
        "documentIds": ["doc-uuid-1", "doc-uuid-2"]
      },
      {
        "name": "support",
        "description": "Troubleshooting and how-to.",
        "documentIds": ["doc-uuid-3"]
      }
    ],
    "messages": ["Let me check on that..."],
    "timeout": 5
  }
}

Documents must already be processed (i.e. chunks indexed) before queries return useful results. See Files → upload.

testTool (inline only)

A simulated tool for exercising the full tool-calling flow — invocation, dead-air task sound, success/failure handling — without a real backend. Unlike the types above it is not a saved-tool category: it exists only as an inline object in an agent config's tools[] array.

The description drives when the LLM calls it; execution is a configurable delay followed by the configured outcome.

{
  "type": "testTool",
  "name": "order_lookup",
  "description": "Call this whenever the user asks about their order status.",
  "config": {
    "delaySeconds": 6,
    "outcome": "success",
    "responseText": "Order #123 ships tomorrow.",
    "messages": ["Let me pull that up.", "One moment, checking now."]
  }
}

Referencing tools from agents

An agent config's tools array — saved (POST /agents) or transient (POST /call) — accepts a mix of saved-tool UUID strings and inline tool objects. Inline objects use the canonical inline format, not the saved-tool format above. See Inline tool format for the exact shapes. Every config also carries an endCall tool — auto-seeded when you don't define one.

{
  "type": "outbound",
  "callConfig": { /* ... */ },
  "toNumber": "+14155550199",
  "agent": {
    "name": "Support bot",
    "systemPrompt": "...",
    "llm": { "provider": "openai", "model": "gpt-5.4-mini" },
    "tools": [
      "abc12345-...",
      {
        "type": "endCall",
        "name": "end_call",
        "description": "End when the caller says goodbye.",
        "config": { "messageType": "custom", "customMessages": ["Goodbye!"] }
      }
    ]
  }
}

Transfer support

Every telephony provider supports transferCall. Web (browser) calls have no phone leg to transfer — there the runner rejects the transfer and the agent continues the call.