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.

PATCH https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/tools/{tool_id}

Before you call

First Query tool details confirm the tool to be updated. Prepare the personal access token, target workspace ID, and tool ID that have access to the target workspace.

The example below uses:

• $AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.

• $WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.

• $TOOL_ID: ID of the tool to update.

Request example

curl -X PATCH "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/tools/$TOOL_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "更新后的说明",
    "status": "active"
  }'

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.

{
  "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"
  }
}

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

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

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 3, 2026