---
title: "Turn a tool on or off, say what it does, lock inputs, or set what agents read"
method: PATCH
path: "/client/mcp/tools/{id}"
tags: ["Tool gateway"]
---

# Turn a tool on or off, say what it does, lock inputs, or set what agents read

`PATCH /client/mcp/tools/{id}`

## Request

- Base URL: `https://api.roar-ai.com`
- URL: `https://api.roar-ai.com/client/mcp/tools/{id}`
- Auth: HTTP bearer

Body `{"status":"active"|"disabled"}`, `{"effect":"reads"|"changes"|null}`, `{"fixedArgs":{…}|null}` and/or `{"descriptionOverride":"…"|null}`. Off hides it from every agent on their next call. `effect` overrides the server’s own `readOnlyHint` (null goes back to it): a tool that changes things is hidden by a read-only grant and waits for approval under “ask”. `fixedArgs` replaces the tool’s locked inputs: each name must be one of its inputs and each value must fit that input’s rules (400 otherwise); agents stop seeing those inputs and the gateway always sends these values. `descriptionOverride` (at most 1,000 characters, plain text) is what agents read instead of the server’s description. A key may only narrow: it may set `"changes"`; `"reads"` and null effect take a signed-in owner or admin, and so does ANY change to `fixedArgs` or `descriptionOverride` — a lock rewrites every agent’s arguments and an override is text every agent follows. Only a signed-in owner or admin is shown locked values; everyone else reads `"[locked]"`. Owner or admin, or a key with `mcp:write`.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `status` 'active' | 'disabled'
  - `effect` 'reads' | 'changes', nullable
  - `fixedArgs` object, nullable
  - `descriptionOverride` string, nullable

## Response `204`

Changed

## Other responses

- `400`: A lock that does not fit the tool, or a description that is empty or too long
- `403`: A key tried to change a lock or a description
- `404`: No such tool

---

[API](https://skmtc.dev/roar-ai/apis/roar-ai-api.md) · [All operations](https://skmtc.dev/roar-ai/apis/roar-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roar-ai/apis/roar-ai-api/revisions/37e4d0d5a7fe?raw)