Skip to main content
POST
/
tools
Create a new tool definition
curl --request POST \
  --url https://api.example.com/tools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "get_order_status",
  "description": "Fetch an order status using an orderId.",
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string"
      }
    },
    "required": [
      "orderId"
    ]
  },
  "endpoint": {
    "url": "https://api.client.com/tools/get-order-status",
    "method": "POST",
    "timeoutMs": 10000
  },
  "auth": {
    "type": "bearer"
  },
  "active": true
}
'
{
  "data": {
    "id": "645e9e4acc61621ce9521a89",
    "name": "get_order_status",
    "description": "Fetch an order status using an orderId.",
    "parameters": {
      "type": "object",
      "properties": {
        "orderId": {
          "type": "string"
        }
      },
      "required": [
        "orderId"
      ]
    },
    "endpoint": {
      "url": "https://api.client.com/tools/get-order-status",
      "method": "POST",
      "timeoutMs": 10000
    },
    "auth": {
      "type": "bearer"
    },
    "createdAt": "2025-11-27T16:00:00.000Z",
    "updatedAt": "2025-11-27T16:00:00.000Z",
    "active": true
  }
}

Authorizations

​
Authorization
string
header
required

Use Authorization: Bearer <api_key>.

Body

application/json
​
name
string
required

Tool function name. Must be unique.

Required string length: 1 - 64
Pattern: ^[a-zA-Z0-9._-]+$
Example:

"get_order_status"

​
description
string
required

What this tool does. This is shown to the LLM to help it decide when to call the tool.

Required string length: 1 - 500
Example:

"Fetch an order status using an orderId."

​
parameters
object
required

JSON Schema object describing the tool function parameters.

Example:
{
  "type": "object",
  "properties": { "orderId": { "type": "string" } },
  "required": ["orderId"]
}
​
endpoint
object
required

Invocation settings for the tool endpoint.

Example:
{
  "url": "https://api.client.com/tools/get-order-status",
  "method": "POST",
  "timeoutMs": 10000
}
​
auth
object

Authentication used when calling the endpoint. Secrets should be stored securely server-side.

Example:
{ "type": "bearer" }
​
active
boolean
default:true

Whether this tool is enabled and can be used by the agent.

Example:

true

Response

Tool definition created successfully

​
data
object
required