Create a Tool
POST /v1/tools
| Property | Value |
|---|---|
| Operation | create_tool |
| Group | Tools |
| Scope | tools:write |
| Route class | control |
| Idempotency | Idempotency-Key accepted: a retry with the same key replays the first answer |
| Audit | Audited tool.create (mutation) |
| Released in | 1.49.0 |
| Phase 0 host | Served (the hosted api pins 1.65.0) |
Creates a Tool at revision 1. The name, the parameters, the response schema and, for an http Tool, the URL through the egress guard are checked, and every issue is a detail of 422 validation_failed (ToolIssueCode). type mcp is refused with capability_not_available and nothing is stored. The auth secret of an http Tool is write-only.
Request
Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the tools:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.
curl -X POST "$VOCAL_API/v1/tools" \
-H "Authorization: Bearer $VOCAL_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "get_appointment",
"type": "http",
"description": "<description>",
"parameters": {}
}'const response = await fetch(`${process.env.VOCAL_API}/v1/tools`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
'Idempotency-Key': crypto.randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({
"name": "get_appointment",
"type": "http",
"description": "<description>",
"parameters": {}
}),
});
console.log(response.status, await response.text());import os
import uuid
import requests
response = requests.post(
f"{os.environ['VOCAL_API']}/v1/tools",
headers={
"Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"name": "get_appointment",
"type": "http",
"description": "<description>",
"parameters": {},
},
)
print(response.status_code, response.text)Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
idempotency-key | header | string | no | A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response. |
Request body
Content type application/json, required: ToolCreateRequest.
| Field | Type | Required | Description |
|---|---|---|---|
annotations | ToolAnnotationsInput | no | |
description | string | yes | Model-facing: what the Tool does and when to use it. |
filler | ToolFillerInput or null | no | None when omitted. |
http | HttpToolConfigInput | no | Required for an http Tool and refused for any other type. |
idempotent | boolean | no | A repeat is harmless: the guard may retry after a connection failure or a 502, 503 or 504, and the request carries an Idempotency-Key derived from the Call and the Tool call. False when omitted. |
name | ToolName | yes | |
parameters | ToolParameters | yes | |
response_schema | ToolResponseSchema or null | no | None when omitted. |
timeout_ms | integer | no | 5,000 when omitted. |
type | ToolType | yes |
Responses
| Status | Content type | Shape | Error codes |
|---|---|---|---|
201 | application/json | Tool | |
400 | application/json | ErrorEnvelope | invalid_request |
401 | application/json | ErrorEnvelope | unauthenticated |
403 | application/json | ErrorEnvelope | forbidden, org_suspended |
409 | application/json | ErrorEnvelope | idempotency_in_progress, idempotency_key_reused |
422 | application/json | ErrorEnvelope | validation_failed, capability_not_available |
429 | application/json | ErrorEnvelope | rate_limited |
500 | application/json | ErrorEnvelope | internal_error |
Fields of the 201 answer
The shape is Tool.
| Field | Type | Required | Description |
|---|---|---|---|
annotations | ToolAnnotations | yes | |
archived_at | Timestamp or null | yes | When DELETE archived the Tool, or null. An archived Tool takes no write and no test (409 tool_archived) and cannot be attached; the Agent versions that froze it keep running it. |
created_at | Timestamp | yes | |
definition_sha256 | string | yes | The SHA-256 of the canonical definition without the auth secret, in lowercase hex; equal to a PinnedTool's when the Agent version froze this revision's definition. |
description | string | yes | Model-facing: what the Tool does and when to use it. |
filler | ToolFiller or null | yes | |
http | HttpToolConfig or null | yes | The request of an http Tool; null otherwise. |
id | ToolId | yes | |
idempotent | boolean | yes | |
name | ToolName | yes | |
object | "tool" | yes | |
organization_id | OrganizationId | yes | |
parameters | ToolParameters | yes | |
response_schema | ToolResponseSchema or null | yes | |
revision | integer | yes | Counts writes to the Tool; returned as the ETag and required in If-Match. |
timeout_ms | integer | yes | The deadline of one invocation, in milliseconds. |
type | ToolType | yes | |
updated_at | Timestamp | yes |