Skip to main content
PATCH
Update a workspace tool set
Renames, redescribes or repopulates the workspace tool set named by id (its name in listToolSets, e.g. ws_research). Builtin tool sets are read-only. The response is the set. Members are catalog tool ids (toolId, as listTools returns them), 1–100 and distinct, each an active or deprecated tool. An unknown or archived tool is 400, so a set never names a tool agents cannot be given. A membership change reaches every agent holding the set at its next dispatch: each holder’s cached configuration is expired in the same write. When more than 100 agents (or 2,000 active grants) hold the set, the change is refused with 409 and nothing is written; revoke the set from some agents first. A change to the name or description alone expires nothing.

Authority and retries

Requires tools:manage at the platform scope. Skill sets and tool sets have no org-unit home, so a credential granted tools:manage only at an org unit is refused with 403 and nothing is written. A Forge agent can never hold tools:manage. MCP clients reach this operation through forge_call_operation. Send an Idempotency-Key to make a retry safe. The same key and the same body within 24 hours return the recorded 200 only while you still hold tools:manage at the platform scope; otherwise the answer is 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422.

Errors

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

setId
string
required

The workspace tool set's id (its name in listToolSets, e.g. ws_research)

Minimum string length: 1

Body

application/json

The workspace tool set's id and a new name, description or members. A member change reaches every agent holding the set at its next dispatch.

name
string

The set's display name (1-120 characters)

Required string length: 1 - 120
description
string

The new description

Maximum string length: 2000
members
string[]

Catalog tool ids (toolId), each an active or deprecated catalog tool, 1-100 and distinct

Required array length: 1 - 100 elements
Minimum string length: 1

Response

Update a workspace tool set

data
object
required
meta
object
required