Skip to main content
POST
Test an unsaved tool

Authorizations

Authorization
string
header
required

An API key from Settings → API keys, sent as Authorization: Bearer kb_live_…. A workspace key starts kb_; a personal key starts kbp_ and acts as its owner.

Headers

Idempotency-Key
string
required

A unique key (a UUID works) for this request. Retrying with the same key returns the first answer instead of running twice.

Maximum string length: 255
Kallabot-Version
enum<string>

The API version to answer as, a date (YYYY-MM-DD). Leave it out for the current version (2026-11-07). An unknown version is refused with 400 unsupported_api_version.

Available options:
2026-11-07
Example:

"2026-11-07"

Body

application/json

An unsaved tool, run by the same executor a call uses.

schema
ApiToolSchema · object
required

The body of an kind='api' tool (see services.tool_execution for templating).

kind
enum<string>
default:api
Available options:
api,
mcp_server
name
string
default:draft_tool
Required string length: 1 - 80
arguments
Arguments · object
tool_name
string | null
Required string length: 1 - 64
variables
Variables · object

Response

Successful Response

What a test run did. Which fields appear depends on the tool's kind.

ok
boolean
required

True when the tool worked.

status

An API tool's HTTP status, or an MCP server's connection status.

error
string | null

An error code when it failed.

message
string | null

A readable explanation of a failure.

input_schema
Input Schema · object | null

The arguments the tool takes (JSON Schema).

request
Request · object | null

The HTTP request sent, with secrets masked.

raw
any

The raw response, with secrets masked.

result
any

What the tool returned.

model_sees
string | null

The text the agent would read.

timing
Timing · object | null

{duration_ms}.

tool
string | null

The MCP tool that ran.

server_info
Server Info · object | null

What the MCP server says about itself.

hash
string | null

A fingerprint of the MCP server's tool list (for approve-tools).

tools
Tools · object[] | null

The MCP server's tools, when listed.

sheet
string | null

A Google Sheets tool's tab.

columns
Columns · object[] | null

A Google Sheets tool's header row now.

changed
string[] | null

Columns whose header changed since the tool was saved.