---
title: "Update a tool"
method: PUT
path: "/v1/tool/{toolId}"
tags: ["Tool"]
---

# Update a tool

`PUT /v1/tool/{toolId}`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/tool/{toolId}`
- Auth: HTTP bearer

Replaces the tool: its name, scope, inputs, description, grading hints and runtime. A field left out is cleared, so omitting agentId makes the tool project-wide. A change declares a new version; agent versions pinned to an older one keep it.

## Path parameters

- `toolId` string, uuid, required

## Request body

- ToolBody
  - `name` string, required
  - `description` string, required: When the agent should use the tool
  - `agentId` string, uuid, nullable
  - `inputs` object[]
    - `name` string, required
    - `type` 'string' | 'number' | 'boolean', required
    - `description` string
    - `required` boolean
  - `invocationCriteria` string, nullable
  - `expectedResult` string, nullable
  - `runtime` object, nullable: Omit or null for a tool that is only graded
    - `request` object, required
      - `url` string, uri, required
      - `method` 'POST' | 'PUT' | 'PATCH' | 'GET' | 'DELETE'
      - `headers` object[]
        - `name` string, required
        - `value` string, required
      - `body` string, nullable
      - `timeoutMs` integer, nullable
    - `changesData` boolean
    - `responseFields` string[], nullable
    - `messages` object
      - `before` string, nullable
      - `slow` string, nullable
      - `failure` string, nullable

## Response `200`

The tool

- ToolSingleResponse
  - `data` ToolResponse, required
    - `id` string, uuid, required
    - `name` string, required
    - `source` 'CUSTOM' | 'SYSTEM', required: SYSTEM for a built-in tool every project can attach
    - `systemKey` string, nullable, required: The stable key of a built-in tool, such as dtmf
    - `agentId` string, uuid, nullable, required: The agent the tool is scoped to; null for the project
    - `version` integer, nullable, required: The latest version; null before any is declared
    - `description` string, nullable, required
    - `inputs` ToolInput[], required
      - `name` string, required: The input name, as the agent passes it
      - `type` 'string' | 'number' | 'boolean', required: string, number or boolean
      - `description` string, nullable, required: What the input is, so the agent fills it in right
      - `required` boolean, required: The agent must pass it
    - `invocationCriteria` string, nullable, required: When the agent should call it, for grading
    - `expectedResult` string, nullable, required: How it should handle the result, for grading
    - `runtime` ToolRuntime, required: What a hosted agent sends and says when it calls the tool
      - `request` ToolRequest, required
        - `url` string, required: https URL. Placeholders {{args.<input>}} and {{conversation.*}} (id, direction, modality, agentNumber, customerNumber, startedAt) may appear in the path and query.
        - `method` 'POST' | 'PUT' | 'PATCH' | 'GET' | 'DELETE', required
        - `headers` object[], required
          - `name` string, required
          - `value` string, required
        - `body` string, nullable, required: JSON body template. Null sends the inputs as the body (POST, PUT, PATCH) or the query (GET, DELETE).
        - `timeoutMs` integer, nullable, required: How long the agent waits, 1000 to 30000 ms
      - `changesData` boolean, required: The tool books, cancels or sends something: its call is not abandoned when the caller interrupts, and each request carries an Idempotency-Key.
      - `responseFields` string[], nullable, required: Dot paths into the JSON response the agent is given. Null gives it the whole response.
      - `messages` ToolMessages, required
        - `before` string, nullable, required: Said as the request goes out
        - `slow` string, nullable, required: Said once if the request is slow
        - `failure` string, nullable, required: Given to the agent to say when the request fails
    - `createdAt` string, required
    - `updatedAt` string, required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `404`: Not Found
- `409`: Conflict
- `500`: Internal Server Error

## Changes

> 190 revisions in range; 1 not diffed.

- **2026-11-03** `b8f2cda47e7e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/tool/:toolId/put.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/0d68611320e4?raw)