VocalDocscontracts 1.65.0

Send one real request of an http Tool

POST /v1/tools/{tool_id}/test

PropertyValue
Operationtest_tool
GroupTools
Scopetools:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited tool.test (mutation)
Released in1.49.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Validates the arguments against the Tool's parameters and sends one real request through the egress guard, signed with the Organization's tool signing secret, with the retries an idempotent Tool allows, and answers its status and measurements; a refusal of the guard is the status blocked, not an error. Only an http Tool is tested: a function Tool needs a live Call, and is refused with validation_failed and tool_type_not_testable. It writes an Audit event, never the arguments or the result.

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/tool_.../test" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {}
  }'

Parameters

NameInTypeRequiredDescription
tool_idpathToolIdyesThe id of a Tool: tool_ and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
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: ToolTestRequest.

FieldTypeRequiredDescription
argumentsmap of anyyesThe arguments to send, validated against the Tool's parameters as a model's would be; refused with tool_parameters_invalid details when they fail. Synthetic values only: the test is a real request.

Responses

StatusContent typeShapeError codes
200application/jsonToolTestResult
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
404application/jsonErrorEnvelopenot_found
409application/jsonErrorEnvelopetool_archived, idempotency_in_progress, idempotency_key_reused
422application/jsonErrorEnvelopevalidation_failed
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 200 answer

The shape is ToolTestResult.

FieldTypeRequiredDescription
attemptsintegeryesRequests sent: 1, up to 3 with the retries of an idempotent Tool, or 0 when refused before sending.
elapsed_msintegeryesFrom the first resolution to the result, a measurement of this request.
error_codeToolErrorCode or nullyesNull when status is ok.
http_statusinteger or nullyesThe status of the last response, or null when none arrived.
object"tool_test_result"yes
redirectsintegeryesRedirects followed.
response_bytesinteger or nullyesThe body bytes read, at most the response cap; null when no response arrived.
resultany or nullyesThe result as the model would receive it: the parsed body truncated to 8 KiB, or null on a failure. Content of the customer's own endpoint, returned to the caller of the test only.
signedbooleanyesTrue when the request carried Vocal-Signature under the Organization's tool signing secret.
statusToolCallStatusyes
tested_atTimestampyes
tool_idToolIdyes
tool_revisionintegeryesThe revision that was tested.