# Tools: Test a tool (https://docs.envocal.ai/api-reference/tools/test-a-tool/) > Sends the tool's real request once, with the variable values you give, and returns what the other system answered: as an agent would call it in a conversation. This reaches the other system for real, so a tool that changes something there changes it. ## POST `/v1/tenants/{tenantId}/tools/{id}/test` Sends the tool's real request once, with the variable values you give, and returns what the other system answered: as an agent would call it in a conversation. This reaches the other system for real, so a tool that changes something there changes it. Give every agent variable the tool needs in `agentVariables`, under the variable's name. The answer's `statusCode` is the other system's: a `200` here with `statusCode` 401 means the request was sent and refused there. `outputVariables` holds what the tool's `responseMapping` read from the answer, under the dynamic variables' names. **Required permission:** `tools:write` ### Parameters | Name | In | | Type | Description | | --- | --- | --- | --- | --- | | `tenantId` | path | required | string | Tenant id, or `current` for the key's own tenant. Must be the key's tenant or one of its sub-tenants. | | `id` | path | required | string (uuid) | Tool id. | ### Request body `application/json`: PublicToolTestDto | Field | Type | | Description | | --- | --- | --- | --- | | `agentVariables` | object | nullable | Arguments as the AI model would pass them, by agent variable name, e.g. `{"order_id": "12345"}`. | | `dynamicVariables` | object | nullable | Dynamic (conversation) variables by name, e.g. `{"customer_id": "C-42"}`. | | `systemVariables` | object | nullable | System variables by name, e.g. `{"system_caller_number": "+46701234567"}`. | ### Request examples **Values for the tool's agent variables**: Each value under the variable's name. Every required agent variable has to be given. ```json { "agentVariables": { "order_id": "12345" } } ``` **Agent, dynamic and system variables**: A number or a boolean is sent as itself, not as text. Dynamic variables are the values an earlier tool would have stored; system variables are what the conversation would provide. ```json { "agentVariables": { "start_time": "2026-03-14T09:30:00", "people": 2, "first_visit": true, "reason": "check-up" }, "dynamicVariables": { "customer_id": "C-42" }, "systemVariables": { "system_caller_number": "+46701234567" } } ``` ### Responses **200** — ToolExecuteResult: The other system's response, and the dynamic variables read from it. | Field | Type | | Description | | --- | --- | --- | --- | | `statusCode` | integer | | HTTP status code returned by the external system. | | `responseHeaders` | object | | Response headers. | | `bodyText` | string | nullable | Response body as text. | | `bodyJson` | object | nullable | Response body parsed as JSON, when it is JSON. | | `outputVariables` | object | | Dynamic variables read from the response by the tool's `responseMapping`. The public API gives them under the variables' names. | **The other system answered**: `statusCode` is the other system's status. `outputVariables` holds what the tool's `responseMapping` read from the answer, under the dynamic variables' names. ```json { "statusCode": 200, "responseHeaders": { "Content-Type": "application/json" }, "bodyText": "{\"data\":{\"customer\":{\"id\":\"C-42\",\"name\":\"Ada\"}}}", "bodyJson": { "data": { "customer": { "id": "C-42", "name": "Ada" } } }, "outputVariables": { "customer_id": "C-42" } } ``` **400**: The request could not be made: a variable is missing, the credential or a secret isn't set up, the address can't be reached or isn't allowed, or the other system didn't answer in time. `error` says which. **A required agent variable was not given**: `error` says what stopped the request from being sent. ```json { "error": "Missing agent variable: order_id. Send every agent variable; a value may be empty." } ``` **401**: Missing, invalid, revoked or expired API key. **403**: The key lacks the required permission, or the tenant/resource is outside its reach. **404**: Not found in this tenant. **429**: Rate limit exceeded. Retry after the number of seconds in the Retry-After header. ### Example ```bash curl -X POST "https://api.envocal.ai/v1/tenants/current/tools/{id}/test" \ -H "Authorization: Bearer evk_eu_..." \ -H "Content-Type: application/json" \ -d '{"agentVariables":{"order_id":"12345"}}' ```