Skip to main content
POST
Create a workspace tool set
Creates a workspace tool set from a name (1–120 characters), an optional description and its members. Its id is ws_<slug of the name>, with a short suffix when that is taken. The response is 201 with the set, in the shape listToolSets returns. 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.

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 201 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

Body

application/json

A workspace tool set's name, optional description and members: catalog tool ids, each active or deprecated.

name
string
required

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

Required string length: 1 - 120
members
string[]
required

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
description
string

A short description of the set

Maximum string length: 2000

Response

Create a workspace tool set

data
object
required
meta
object
required