> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domesystems.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Tool Status

> SetToolStatus transitions a catalog tool through its lifecycle states
 (active / deprecated / blocked). Workspace operators use this to hide
 dangerous tools from agents (blocked → filtered from tools/list and
 denied at tools/call) or to mark superseded tools (deprecated → still
 callable, surfaced with a warning chip; gateway-side propagation as
 _meta.dome.deprecated lands in #685).

 Blocked transitions trigger regeneration of the workspace-scoped
 managed Cedar bundle (generator=blocked_tools, file=blocked-tools.cedar).
 The bundle is one `forbid` policy per blocked tool; Cedar's forbid-wins
 semantics override the per-connection tool-<connection>.cedar permits.

 Permission: gateway.manage. Allowed callers: identity.PlatformUser.



## OpenAPI

````yaml POST /v1/catalog/tools/{tool_id}/status
openapi: 3.0.3
info:
  title: Dome Platform API
  description: Connect and REST APIs for the Dome agent governance platform.
  version: 2.0.0
servers:
  - url: https://api.domesystems.ai
    description: Production
security: []
tags:
  - name: Agents
  - name: Authorization
  - name: Guards
  - name: Tools
  - name: Tool Catalog
  - name: Models
  - name: Model Pools
  - name: Quotas
  - name: Gateways
  - name: Webhooks
  - name: Audit
  - name: Workspaces
  - name: Access Control
  - name: Tenants
  - name: Platform Keys
  - name: Enrollment
  - name: Platform
  - name: Identity
paths:
  /v1/catalog/tools/{tool_id}/status:
    post:
      tags:
        - Tool Catalog
      description: |-
        SetToolStatus transitions a catalog tool through its lifecycle states
         (active / deprecated / blocked). Workspace operators use this to hide
         dangerous tools from agents (blocked → filtered from tools/list and
         denied at tools/call) or to mark superseded tools (deprecated → still
         callable, surfaced with a warning chip; gateway-side propagation as
         _meta.dome.deprecated lands in #685).

         Blocked transitions trigger regeneration of the workspace-scoped
         managed Cedar bundle (generator=blocked_tools, file=blocked-tools.cedar).
         The bundle is one `forbid` policy per blocked tool; Cedar's forbid-wins
         semantics override the per-connection tool-<connection>.cedar permits.

         Permission: gateway.manage. Allowed callers: identity.PlatformUser.
      operationId: MCPToolCatalog_SetToolStatus
      parameters:
        - name: tool_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetToolStatusRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetToolStatusResponse'
components:
  schemas:
    SetToolStatusRequest:
      type: object
      properties:
        workspace_id:
          type: string
        tool_id:
          type: string
        status:
          type: string
          description: Required. One of "active", "deprecated", "blocked".
        status_message:
          type: string
          description: >-
            Optional. Operator note shown alongside the tool in dashboards and
            CLI.
      description: >-
        SetToolStatusRequest targets one catalog tool by (workspace_id,
        tool_id).
         The handler verifies the tool belongs to the workspace before writing.
    SetToolStatusResponse:
      type: object
      properties:
        tool:
          $ref: '#/components/schemas/Tool'
    Tool:
      type: object
      properties:
        id:
          type: string
        connection_id:
          type: string
        name:
          type: string
        description:
          type: string
        input_schema:
          type: string
          format: bytes
        current_schema_hash:
          type: string
        first_seen_at:
          type: string
          format: date-time
        last_seen_at:
          type: string
          format: date-time
        status:
          type: string
          description: |-
            Lifecycle status. One of "active", "deprecated", "blocked".
             Empty on the wire is treated as "active" by clients for forward-compat.
        status_message:
          type: string
          description: >-
            Operator-supplied note ("use create_page_v2", "dangerous
            mass-delete", ...).
        status_changed_at:
          type: string
          description: >-
            When the most recent transition happened. Unset for tools never
            transitioned.
          format: date-time
        status_changed_by:
          type: string
          description: |-
            Plain UUID of the platform user who set the current status (no FK).
             Survives user deletion. Empty for tools never transitioned.

````