Update tool¶

Partially update a platform tool in the current workspace. This action does not create a tool when the target tool does not exist.

HTTP
PATCH $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/tools/{tool_id}

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First Query tool details confirm the tool to be updated.

Set the operation-specific values used in the request:

$TOOL_ID: ID of the tool to update.

Request¶

Input examples

Shell
curl -X PATCH "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/tools/$TOOL_ID" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "更新后的说明",
    "status": "active"
  }'

Parameter reference

Path parameters

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	The current workspace ID.
`tool_id`	string	Yes	The tool ID to update.

Query parameters

Parameters	Type	Is it required	Description
`tool_workspace_id`	string	No	The workspace the tool belongs to; can only be the current workspace or `system`. System tools are read-only when `system` is specified and updates will be rejected.

Request body

The fields in the request body are optional; fields not provided retain their original values.

Field	Type	Is it required	Description
`name`	string	No	Tool name, description, status, category and display information. The status can be `draft`, `active`, `disabled`, or `archived`.
`description`	string	No	Tool name, description, status, category and display information. The status can be `draft`, `active`, `disabled`, or `archived`.
`status`	string	No	Tool name, description, status, category and display information. The status can be `draft`, `active`, `disabled`, or `archived`.
`kind`	string	No	Tool name, description, status, category and display information. The status can be `draft`, `active`, `disabled`, or `archived`.
`category`	string	No	Tool name, description, status, category and display information. The status can be `draft`, `active`, `disabled`, or `archived`.
`icon_ref`	string	No	Tool name, description, status, category and display information. The status can be `draft`, `active`, `disabled`, or `archived`.
`phase`	string	No	Tool name, description, status, category and display information. The status can be `draft`, `active`, `disabled`, or `archived`.
`tags`	string[]	No	Tool label; providing this field will replace the original label. Only updating `tags` does not increment the resource version.
`source_ref`	object	No	Source; can contain `type`, `id`, `uri`, `version`, and `config`.
`input_schema`	object	No	Input and output JSON Schema.
`output_schema`	object	No	Input and output JSON Schema.
`side_effect_class`	string	No	Side effect classification: `read`, `write`, or `external_effect`.
`credential_ref`	string	No	Credentials, approvals, and masking policy references.
`approval_policy_ref`	string	No	Credentials, approvals, and masking policy references.
`redaction_policy_ref`	string	No	Credentials, approvals, and masking policy references.
`sync`	object	No	Synchronization status, can include `status`, `last_sync_at`, and `last_sync_error`.
`market_metadata`	object	No	Market metadata, tags, annotations, and extended metadata.
`labels`	object	No	Market metadata, tags, annotations, and extended metadata.
`annotations`	object	No	Market metadata, tags, annotations, and extended metadata.
`metadata`	object	No	Market metadata, tags, annotations, and extended metadata.

[] after a type denotes an array. [] in a field path denotes each item in an array.

MCP tools cannot modify kind, source_ref, or credential_ref through this interface; nor can ordinary tools be updated to MCP tools.

Successful response¶

Returns 200 and the updated tool on success. In addition to updating only tags, the resource version is incremented.

Response example

JSON
{
  "code": 0,
  "data": {
    "id": "tool_01",
    "workspace_id": "ws_01",
    "name": "查询工具",
    "description": "更新后的说明",
    "status": "active",
    "kind": "http_api",
    "side_effect_class": "read",
    "version": 2,
    "bindable": true,
    "supported_runtimes": [],
    "created_at": "2026-01-02T15:04:05Z",
    "updated_at": "2026-01-02T15:04:05Z"
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.id`	string	Tool ID and workspace.
`data.workspace_id`	string	Tool ID and workspace.
`data.name`	string	Updated basic definition.
`data.description`	string	Updated basic definition.
`data.status`	string	Updated basic definition.
`data.kind`	string	Updated basic definition.
`data.side_effect_class`	string	Side effect classification and current resource version.
`data.version`	integer	Side effect classification and current resource version.
`data.bindable`	boolean	Current binding capabilities, reasons for unbinding, and supported operating environments.
`data.bindability_reason`	string	Current binding capabilities, reasons for unbinding, and supported operating environments.
`data.supported_runtimes`	string[]	Current binding capabilities, reasons for unbinding, and supported operating environments.
`data.updated_at`	string	Last updated time, using RFC 3339 format.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Error response¶

Response example

JSON
{
  "code": 2,
  "message": "<错误信息>"
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	Invalid path, request field, or MCP tool update scope.	Check tool IDs, field values, and tool category restrictions.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`403`	`5`（`PERMISSION_DENIED`）	The current identity does not have permission to update the tool.	Check workspace authorization.
`403`	`7`（`FORBIDDEN`）	The specified system tool is read-only.	Do not modify system tools; create or update your own tools in the current workspace.
`404`	`3`（`NOT_FOUND`）	The tool does not exist in the specified workspace.	Check tool ID and `tool_workspace_id`.
`503`	`15`（`UNAVAILABLE`）	Tool resource services or authorization dependencies are temporarily unavailable.	Try again later.

Follow-up operations¶

Use the same resource identifier Query tool details to confirm the update result.

Last updated on Sep 15, 2026