VocalDocscontracts 1.65.0

Create a Tool

POST /v1/tools

PropertyValue
Operationcreate_tool
GroupTools
Scopetools:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited tool.create (mutation)
Released in1.49.0
Phase 0 hostServed (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": {}
  }'

Parameters

NameInTypeRequiredDescription
idempotency-keyheaderstringnoA 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.

FieldTypeRequiredDescription
annotationsToolAnnotationsInputno
descriptionstringyesModel-facing: what the Tool does and when to use it.
fillerToolFillerInput or nullnoNone when omitted.
httpHttpToolConfigInputnoRequired for an http Tool and refused for any other type.
idempotentbooleannoA 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.
nameToolNameyes
parametersToolParametersyes
response_schemaToolResponseSchema or nullnoNone when omitted.
timeout_msintegerno5,000 when omitted.
typeToolTypeyes

Responses

StatusContent typeShapeError codes
201application/jsonTool
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
409application/jsonErrorEnvelopeidempotency_in_progress, idempotency_key_reused
422application/jsonErrorEnvelopevalidation_failed, capability_not_available
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 201 answer

The shape is Tool.

FieldTypeRequiredDescription
annotationsToolAnnotationsyes
archived_atTimestamp or nullyesWhen 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_atTimestampyes
definition_sha256stringyesThe 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.
descriptionstringyesModel-facing: what the Tool does and when to use it.
fillerToolFiller or nullyes
httpHttpToolConfig or nullyesThe request of an http Tool; null otherwise.
idToolIdyes
idempotentbooleanyes
nameToolNameyes
object"tool"yes
organization_idOrganizationIdyes
parametersToolParametersyes
response_schemaToolResponseSchema or nullyes
revisionintegeryesCounts writes to the Tool; returned as the ETag and required in If-Match.
timeout_msintegeryesThe deadline of one invocation, in milliseconds.
typeToolTypeyes
updated_atTimestampyes