Skip to main content
POST
Create a custom agent tool

Authorizations

Authorization
string
header
required

Dashboard JWT token from Clerk

Body

application/json
name
string
required

Lowercase snake_case identifier the model calls (e.g. lookup_order).

Required string length: 3 - 64
description
string
required

What the tool does — the model reads this to decide when to call it.

Required string length: 1 - 1000
executor_url
string
required

HTTPS endpoint Orbit POSTs to when an agent invokes the tool.

Maximum string length: 2000
json_schema
object

JSON-Schema for the tool's parameters (max 32KB serialized).

executor_secret
string

Optional secret, stored encrypted, used to HMAC-sign each dispatch.

Required string length: 8 - 512
enabled
boolean
default:true
timeout_ms
integer
default:30000

Per-call timeout in milliseconds.

Required range: 1000 <= x <= 60000
confirmation
enum<string>
default:never

Whether the tool call requires operator approval before it runs.

Available options:
never,
always

Response

201 - application/json

The custom tool was created

data
object
meta
object