API reference · Tools

Update a tool

PUThttps://goblins-call-api.onrender.com/v1/tools/:id

Changes the fields you send and leaves the rest as they are. The agent a tool belongs to cannot be changed.

Needs a workspace API key.

Path parameters

idstringRequired

The tool’s ID, such as tool_5d2e8a41c07b.

Body

namestringOptional1–128 chars

An identifier the model uses to ask for the tool, such as check_order_status. It is saved in lower case with anything but letters, digits and _ turned into _. Instructions mention it as @check_order_status.

descriptionstringOptionalup to 5,000 chars

What the tool does and when to use it. The model reads this to decide.

kindenumOptionalduring_call · before_call; default during_call

during_call tools are run by the model in the middle of a conversation. before_call tools run once as the call starts, and their response is added to the agent’s instructions.

methodenumOptionalGET · POST; default GET

The HTTP method of the request to your endpoint.

urlstringOptional

Your endpoint. Must be a public http(s) address; redirects are not followed. May contain {{placeholders}}.

paramsobject[]Optional

The arguments the model supplies, each { "key": "order_id", "value": "A-1042" }. value is an example shown to the model, and what is sent when the model leaves the argument out. Sent as the query string of a GET, or as the JSON body of a POST that has no body of its own.

headersobject[]Optional

Extra request headers, each { "key", "value" }. Values may contain {{placeholders}}.

bodystringOptional

A body template for a POST, with {{placeholders}}. Sent as JSON unless a Content-Type header says otherwise.

authenumOptionalnone · bearer · api_key · basic; default none

How the request authenticates to your endpoint.

authTokenstringOptional

The bearer token, API key or basic-auth password. Stored encrypted.

authKeyHeaderstringOptionaldefault X-API-Key

The header an api_key credential is sent in.

authUsernamestringOptional

The username for basic auth.

timeoutMsintegerOptional500–60,000; default 10,000

How long to wait for your endpoint. A request is cut off at 30 seconds whatever is set here.

outputsobject[]Optional

The fields your endpoint answers with, each { "name", "description" }, for your own reference in the studio.

sampleOutputstringOptional

An example response. The model is shown it so it knows what to expect back.

Errors

400

The body failed validation. details lists each field and what is wrong with it.

400URL_NOT_ALLOWED

The URL is not a public http(s) address.

404

No tool in your workspace has that ID.

Every request can also answer 401, 429 and 500: see Errors.

curl -X PUT "https://goblins-call-api.onrender.com/v1/tools/tool_5d2e8a41c07b" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "timeoutMs": 8000,
  "description": "Looks up an order by its number and says when it will arrive."
}'

Response · 200 OK

{
  "tool": {
    "id": "tool_5d2e8a41c07b",
    "userId": "usr_8c1d2e3f4a5b",
    "agentId": "ua_3f9a1c2b",
    "name": "check_order_status",
    "description": "Looks up an order by its number, which the caller reads out. Use it when the caller asks where their order is.",
    "kind": "during_call",
    "method": "GET",
    "url": "https://your-app.com/api/orders/{{order_id}}",
    "timeoutMs": 5000,
    "params": [{ "key": "order_id", "value": "A-1042" }],
    "headers": [],
    "auth": "bearer",
    "authToken": "…",
    "outputs": [{ "name": "status" }, { "name": "eta" }],
    "createdAt": "2026-10-11T08:20:03.000Z",
    "updatedAt": "2026-10-11T08:20:03.000Z"
  }
}