Skip to content
MoreVoiceDevelopers

Test a custom tool

POST
/tools/test
import { createClient, createResources } from "@morevoice/sdk";


const mv = createResources({
  client: createClient({ baseUrl: "https://api.morevoice.ai/v1", auth: process.env.MOREVOICE_API_KEY }),
});


const toolTest = await mv.tools.test({
  arguments: {
    date: "2026-11-04",
  },
  tool: {
    headers: {
      Authorization: "Bearer crm-secret",
    },
    name: "find_slots",
    timeout_seconds: 10,
    url: "https://crm.example.com/voice/tools",
  },
});
console.log(toolTest);

Runs a custom tool once with the arguments you give, the way a call runs it: the same request body, signed with your tool signing secret (Standard Webhooks headers; test-mode keys sign with the test secret) and sent through the same network guard. Webhook failures (an HTTP error, a timeout) are reported in the result; a URL that cannot be called at all is a 400.

Try it in the API playground with a test-mode key.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
MoreVoice-Version
string
/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example
2026-11-01
Idempotency-Key
string
>= 1 characters <= 255 characters

A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.

Example
5f0c1e8a-7b2d-4c3e-9f1a-2b6d8e4c0a17

Request Body

Section titled “Request Body”
Media typeapplication/json
object
arguments

The arguments, as the model would pass them (default {}).

object
key
additional properties
assistant_id

The assistant whose stored tool (with its stored headers) to test.

string
<= 200 characters /^asst_[0-9A-Za-z]+$/
tool

A custom tool as you send it. headers are write-only: stored with the assistant, never returned.

object
contract

Default legacy.

string
Allowed values: legacy v1
description

What the tool does and when to call it.

string
<= 2000 characters
enabled

Default true.

boolean
headers

Extra request headers, e.g. Authorization. Write-only. On update, leave it out to keep the stored headers; send {} to remove them.

object
key
additional properties
string
<= 4096 characters
mock_response

The answer of a mock tool.

string
<= 10000 characters
name
required

The function name the model calls (unique per assistant).

string
/^[a-zA-Z0-9_-]{1,64}$/
parameters

JSON Schema (an object schema) of the arguments.

object
key
additional properties
request_start_message

Spoken while the tool runs.

string
<= 500 characters
timeout_seconds

How long to wait for the webhook, 1–60 (default 15).

number
>= 1 <= 60
type

Default: webhook when url is set, else mock.

string
Allowed values: webhook mock
url

The webhook URL (http or https). Required for webhook tools.

string
<= 2048 characters
tool_name

The stored tool’s name (with assistant_id).

string
/^[a-zA-Z0-9_-]{1,64}$/
Example
{
  "arguments": {
    "date": "2026-11-04"
  },
  "tool": {
    "headers": {
      "Authorization": "Bearer crm-secret"
    },
    "name": "find_slots",
    "timeout_seconds": 10,
    "url": "https://crm.example.com/voice/tools"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

The outcome of one tool run. The request is exactly a call’s: the same body, signed with your tool signing secret (Standard Webhooks headers), through the same network guard; the call is {"id": "test"}.

object
duration_ms
required

How long the tool took.

integer
>= -9007199254740991 <= 9007199254740991
error
required
Any of:
object
code
required

Why the tool failed.

string
Allowed values: http_error timeout network response_too_large tool_error
message
required

A human-readable explanation.

string
status
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
livemode
required

true in live mode, false in test mode.

boolean
object
required
string
Allowed value: tool_test
ok
required

True when the tool answered (a 2xx for webhooks).

boolean
result
required

What the model would receive: the parsed JSON (or text) of the answer.

tool
required

The tool’s name.

string
type
required

webhook tools were called over HTTP (signed); mock tools answered their mock_response.

string
Allowed values: webhook mock
Example
{
  "duration_ms": 182,
  "error": null,
  "livemode": true,
  "object": "tool_test",
  "ok": true,
  "result": {
    "slots": [
      "10:30",
      "11:00"
    ]
  },
  "tool": "find_slots",
  "type": "webhook"
}

400

Section titled “400”

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing",
    "message": "Missing required parameter: to.",
    "param": "to",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "invalid_request_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

401

Section titled “401”

No valid API key was sent.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "invalid_api_key",
    "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key",
    "message": "Invalid API key.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "authentication_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

403

Section titled “403”

The key may not do this (a missing scope, a plan limit, or a compliance block).

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "missing_scope",
    "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope",
    "message": "This API key lacks the calls:write scope.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "permission_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

409

Section titled “409”

The request conflicts with the object’s state, or the Idempotency-Key was reused with other parameters.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "idempotency_mismatch",
    "doc_url": "https://docs.morevoice.ai/api/errors#idempotency-mismatch",
    "message": "This Idempotency-Key was already used with different parameters.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "idempotency_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

429

Section titled “429”

Too many requests, or no call capacity right now. Retry after the Retry-After delay.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "rate_limited",
    "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited",
    "message": "Too many requests. Retry after 1 second.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "rate_limit_error"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.

X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.

500

Section titled “500”

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

Media typeapplication/json

Every /v1 error.

object
error
required
object
code
required

A stable, machine-readable code from the error-code catalogue.

string
details

Structured context, e.g. required_scope or the compliance verdict.

object
key
additional properties
doc_url
required

A link to the documentation of this code.

string
message
required

A human-readable explanation. Do not parse it.

string
param

The request parameter the error relates to, e.g. to or metadata[order_id].

string
request_id
required

The X-Request-Id of this request. Quote it when you contact support.

string
type
required

The category of the error.

string
Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error
Example
{
  "error": {
    "code": "internal_error",
    "doc_url": "https://docs.morevoice.ai/api/errors#internal-error",
    "message": "Something went wrong on MoreVoice's side.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "api_error"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s ID (req_…). Quote it when you contact support.