<span id="删除工具"></span>

# Delete a tool

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Delete workspace tool metadata. Check references before deleting; unbinding and disabling are separate operations.

```text
DELETE https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/tools/{tool_id}
```

<span id="调用前准备"></span>

## Before you call this API

Obtain a personal access token and workspace ID for the current environment as described in [AI Studio](../../../../../developer/api/ai-studio/index.md). The current effective role must permit the action. Get the exact ID from the current workspace resource list and first check agents referencing it.

<span id="请求参数"></span>

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
curl -X DELETE "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/tools/$TOOL_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

:::::
:::::{tab-item} Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace_id` | string | Yes | Target workspace ID in the current environment, matching the header. |
| `X-Workspace-ID` | string | Yes | Workspace ID in the current environment. |
| `X-API-Key` | string | Yes | Personal access token in the current environment. |
| `tool_id` | string | Yes | Tool ID in the current workspace to delete. |
| `tool_workspace_id` | string | No | Query parameter, defaulting to the current workspace. system sources are read-only; this cannot delete another workspace's objects. |

This action accepts no expected-version or force-cascade fields. If referenced, inspect the relevant resource reference list and unbind according to the intended change; do not automatically unbind other agents. When localization succeeds, 422 includes details.reason=TOOL_IN_USE and domain. See shared error information.

:::::
::::::
:::::::

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": 0,
  "data": {
    "deleted": true
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | integer | 0 on success. |
| `data.deleted` | boolean | true on successful deletion. |

:::::
::::::
:::::::

<span id="错误响应"></span>

## Error responses

| HTTP / code | Conditions and handling |
| --- | --- |
| 400 / 2 | Invalid object or workspace identifier. |
| 403 / 5 | System source target or current authorization denied. |
| 404 / 3 | Target not found; repeated deletion does not guarantee success again. |
| 422 / 2 | Active binding references remain in agent definitions or workspace overrides. Resolve references first. |
| 503 / 15 | Resource or authorization dependencies unavailable. |
| 500 / 1 | Localization failed while references prevented deletion. |

The authentication stage may also return string code/msg. See [errors and environments](errors-environments.md).
