# Update Tool

> PUT /api/v1/tools/{tool_uuid} — request parameters and responses from the Menace Voice API schema.

`PUT /api/v1/tools/{tool_uuid}`

{/* Generated by scripts/sync_docs_api.mjs. Edit the API schema source to change the contract. */}

See [authentication](/api-reference/authentication) for workspace API access. Public embed and artifact endpoints use their documented session or access tokens.

## API contract for documentation tools

Generated from the OpenAPI schema. Do not infer a different parameter type from an example. Authentication headers are alternatives as explained in the authentication guide.

### Parameters

| Name | Location | Type | Required | Description and constraints |
| --- | --- | --- | --- | --- |
| tool_uuid | path | string | yes |  |
| authorization | header | string or null | no |  |
| X-API-Key | header | string or null | no |  |

### Request body: application/json

Required body. Schema: UpdateToolRequest (object).

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| name | string or null | no |  |
| description | string or null | no |  |
| icon | string or null | no |  |
| icon_color | string or null | no |  |
| definition | HttpApiToolDefinition (object) or EndCallToolDefinition (object) or TransferCallToolDefinition (object) or CalculatorToolDefinition (object) or CurrentTimeToolDefinition (object) or McpToolDefinition (object) or null | no |  |
| status | string or null | no |  |

### Response 200

Successful Response

application/json: ToolResponse (object).

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| id | integer | yes |  |
| tool_uuid | string | yes |  |
| name | string | yes |  |
| description | string or null | yes |  |
| category | string | yes |  |
| icon | string or null | yes |  |
| icon_color | string or null | yes |  |
| status | string | yes |  |
| definition | object | yes |  |
| created_at | string | yes | format: "date-time" |
| updated_at | string or null | yes |  |
| created_by | CreatedByResponse (object) or null | no |  |

### Response 404

Not found

### Response 422

Validation Error

application/json: HTTPValidationError (object).

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| detail | array of ValidationError (object) | no |  |

## OpenAPI

````yaml api-reference/openapi.json put /api/v1/tools/{tool_uuid}
openapi: 3.1.0
info:
  title: Menace Voice API
  description: API for Menace Voice agents
  version: 1.0.0
servers:
  - url: https://voice.menaceui.com
    description: Production
  - url: http://localhost:8000
    description: Local development
paths:
  /api/v1/tools/{tool_uuid}:
    put:
      tags:
        - main
      summary: Update Tool
      description: |-
        Update a tool.

        Args:
            tool_uuid: The UUID of the tool to update
            request: The update request

        Returns:
            The updated tool
      operationId: update_tool_api_v1_tools__tool_uuid__put
      parameters:
        - name: tool_uuid
          in: path
          required: true
          schema:
            type: string
            title: Tool Uuid
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            title: Authorization
        - name: X-API-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateToolRequest"
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolResponse"
        "404":
          description: Not found
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
components:
  schemas:
    CalculatorToolDefinition:
      properties:
        schema_version:
          type: integer
          title: Schema Version
          description: Schema version.
          default: 1
        type:
          type: string
          const: calculator
          title: Type
          description: Tool type.
      type: object
      required:
        - type
      title: CalculatorToolDefinition
      description: Tool definition for Calculator tools.
    ContextDestinationMappingConfig:
      properties:
        rules:
          anyOf:
            - items:
                $ref: "#/components/schemas/ContextDestinationRule"
              type: array
            - type: "null"
          title: Rules
          description: Ordered routing rules evaluated top to bottom; first match wins.
        context_path:
          anyOf:
            - type: string
            - type: "null"
          title: Context Path
          description: Deprecated single-rule context path. Use rules instead; accepted
            for backward compatibility.
        routes:
          anyOf:
            - items:
                $ref: "#/components/schemas/ContextDestinationRoute"
              type: array
            - type: "null"
          title: Routes
          description: Deprecated single-rule routes. Use rules instead; accepted for
            backward compatibility.
        fallback_destination:
          anyOf:
            - type: string
              maxLength: 255
            - type: "null"
          title: Fallback Destination
          description: Optional provider-native destination or context template used when
            no rule matched.
      type: object
      title: ContextDestinationMappingConfig
      description: >-
        Resolve a transfer destination from gathered or initial context.


        Rules are evaluated in order. The first rule whose context value matches

        one of its routes wins; ``fallback_destination`` applies only when no
        rule

        matched. Destinations may be provider-native values or context
        templates.
    ContextDestinationRoute:
      properties:
        context_value:
          type: string
          maxLength: 255
          minLength: 1
          title: Context Value
          description: Context value that selects this destination.
        destination:
          type: string
          maxLength: 255
          minLength: 1
          title: Destination
          description: VICIdial in-group, SIP endpoint, E.164 phone number, or context
            template used when this route matches.
      type: object
      required:
        - context_value
        - destination
      title: ContextDestinationRoute
      description: Map one context value to a transfer destination.
    ContextDestinationRule:
      properties:
        context_path:
          type: string
          maxLength: 255
          minLength: 1
          title: Context Path
          description: Context path used for routing. An unprefixed path checks gathered
            context first, then initial context; use initial_context.* or
            gathered_context.* to select one explicitly.
        routes:
          items:
            $ref: "#/components/schemas/ContextDestinationRoute"
          type: array
          maxItems: 100
          minItems: 1
          title: Routes
      type: object
      required:
        - context_path
        - routes
      title: ContextDestinationRule
      description: One context lookup with its value-to-destination routes.
    CreatedByResponse:
      properties:
        id:
          type: integer
          title: Id
        provider_id:
          type: string
          title: Provider Id
      type: object
      required:
        - id
        - provider_id
      title: CreatedByResponse
      description: Response schema for the user who created a tool.
    CurrentTimeToolDefinition:
      properties:
        schema_version:
          type: integer
          title: Schema Version
          description: Schema version.
          default: 1
        type:
          type: string
          const: current_time
          title: Type
          description: Tool type.
      type: object
      required:
        - type
      title: CurrentTimeToolDefinition
      description: Tool definition for current time and timezone conversion tools.
    EndCallConfig:
      properties:
        messageType:
          type: string
          enum:
            - none
            - custom
            - audio
          title: Messagetype
          description: Type of goodbye message.
          default: none
        customMessage:
          anyOf:
            - type: string
            - type: "null"
          title: Custommessage
          description: Custom message to play before ending the call.
        audioRecordingId:
          anyOf:
            - type: string
            - type: "null"
          title: Audiorecordingid
          description: Recording ID for audio goodbye message.
        endCallReason:
          type: boolean
          title: Endcallreason
          description: When enabled, the model must provide a reason for ending the call.
            The reason is set as call disposition and added to call tags.
          default: false
        endCallReasonDescription:
          anyOf:
            - type: string
            - type: "null"
          title: Endcallreasondescription
          description: Description shown to the model for the reason parameter. Used only
            when endCallReason is enabled.
      type: object
      title: EndCallConfig
      description: Configuration for End Call tools.
    EndCallToolDefinition:
      properties:
        schema_version:
          type: integer
          title: Schema Version
          description: Schema version.
          default: 1
        type:
          type: string
          const: end_call
          title: Type
          description: Tool type.
        config:
          $ref: "#/components/schemas/EndCallConfig"
          description: End Call configuration.
      type: object
      required:
        - type
        - config
      title: EndCallToolDefinition
      description: Tool definition for End Call tools.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: "#/components/schemas/ValidationError"
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    HttpApiConfig:
      properties:
        method:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
          title: Method
          description: HTTP method to use for the request.
          llm_hint: Use one of GET, POST, PUT, PATCH, DELETE.
        url:
          type: string
          title: Url
          description: Target HTTP or HTTPS URL.
          llm_hint: Use the final endpoint URL. Authentication belongs in credential_uuid,
            not embedded in the URL.
        headers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: "null"
          title: Headers
          description: Static headers to include with every request.
          llm_hint: Do not place secrets here. Store secrets in the UI credential manager
            and reference them with credential_uuid.
        credential_uuid:
          anyOf:
            - type: string
            - type: "null"
          title: Credential Uuid
          description: Reference to an external credential for request authentication.
          llm_hint: Use a credential_uuid returned by list_credentials. The MCP flow does
            not create credential secrets.
        parameters:
          anyOf:
            - items:
                $ref: "#/components/schemas/ToolParameter"
              type: array
            - type: "null"
          title: Parameters
          description: Parameters the model must provide when calling this tool.
        preset_parameters:
          anyOf:
            - items:
                $ref: "#/components/schemas/PresetToolParameter"
              type: array
            - type: "null"
          title: Preset Parameters
          description: Parameters injected by Menace Voice from fixed values or workflow
            context templates.
        timeout_ms:
          anyOf:
            - type: integer
              minimum: 1
            - type: "null"
          title: Timeout Ms
          description: Request timeout in milliseconds.
          default: 5000
        customMessage:
          anyOf:
            - type: string
            - type: "null"
          title: Custommessage
          description: Custom message to play after tool execution.
        customMessageType:
          anyOf:
            - type: string
              enum:
                - text
                - audio
            - type: "null"
          title: Custommessagetype
          description: Type of custom message.
        customMessageRecordingId:
          anyOf:
            - type: string
            - type: "null"
          title: Custommessagerecordingid
          description: Recording ID for an audio custom message.
        body_template:
          anyOf:
            - additionalProperties: true
              type: object
            - type: "null"
          title: Body Template
          description: Optional JSON body template for POST, PUT, and PATCH requests.
          llm_hint: Use {{parameter_name}} placeholders to position LLM and preset
            parameters anywhere in the body, including nested objects and
            arrays; also {{initial_context.*}}. A value that is exactly one
            placeholder keeps the value's original JSON type. Omit this field to
            send all parameters as a flat top-level JSON object. Ignored for GET
            and DELETE.
      type: object
      required:
        - method
        - url
      title: HttpApiConfig
      description: Configuration for HTTP API tools.
    HttpApiToolDefinition:
      properties:
        schema_version:
          type: integer
          title: Schema Version
          description: Schema version.
          default: 1
        type:
          type: string
          const: http_api
          title: Type
          description: Tool type.
        config:
          $ref: "#/components/schemas/HttpApiConfig"
          description: HTTP API configuration.
      type: object
      required:
        - type
        - config
      title: HttpApiToolDefinition
      description: Tool definition for HTTP API tools.
    HttpTransferResolverConfig:
      properties:
        type:
          type: string
          const: http
          title: Type
          description: Resolver type.
          default: http
        url:
          type: string
          title: Url
          description: HTTP or HTTPS endpoint for transfer resolution.
        headers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: "null"
          title: Headers
          description: Static headers to include with every resolver request.
        credential_uuid:
          anyOf:
            - type: string
            - type: "null"
          title: Credential Uuid
          description: Reference to an external credential for resolver authentication.
        timeout_ms:
          type: integer
          maximum: 5000
          minimum: 500
          title: Timeout Ms
          description: Resolver request timeout in milliseconds.
          default: 3000
        wait_message:
          anyOf:
            - type: string
            - type: "null"
          title: Wait Message
          description: Optional short message played while Menace Voice resolves routing.
        parameters:
          anyOf:
            - items:
                $ref: "#/components/schemas/ToolParameter"
              type: array
            - type: "null"
          title: Parameters
          description: Parameters the model may provide when calling this transfer tool.
        preset_parameters:
          anyOf:
            - items:
                $ref: "#/components/schemas/PresetToolParameter"
              type: array
            - type: "null"
          title: Preset Parameters
          description: Parameters injected by Menace Voice from fixed values or workflow
            context templates.
      type: object
      required:
        - url
      title: HttpTransferResolverConfig
      description: HTTP endpoint used to resolve transfer destination at call time.
    McpToolConfig:
      properties:
        transport:
          type: string
          const: streamable_http
          title: Transport
          description: MCP transport protocol.
          default: streamable_http
        url:
          type: string
          title: Url
          description: MCP server URL. Must use http:// or https://.
          llm_hint: Use the server's streamable HTTP MCP endpoint.
        credential_uuid:
          anyOf:
            - type: string
            - type: "null"
          title: Credential Uuid
          description: Reference to an external credential for MCP server auth.
          llm_hint: Use a credential_uuid returned by list_credentials. Credentials are
            created by the user in the UI.
        tools_filter:
          items:
            type: string
          type: array
          title: Tools Filter
          description: Allowlist of MCP tool names to expose. Empty exposes all tools.
          llm_hint: Use exact MCP tool names from the remote server catalog when you need
            to restrict the exposed tools.
        timeout_secs:
          type: integer
          minimum: 0
          title: Timeout Secs
          description: Connection timeout in seconds.
          default: 30
        sse_read_timeout_secs:
          type: integer
          minimum: 0
          title: Sse Read Timeout Secs
          description: SSE read timeout in seconds.
          default: 300
        discovered_tools:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Discovered Tools
          description: Server-managed cache of the MCP server's tool catalog [{name,
            description}]. Populated best-effort by the backend.
          llm_hint: Do not author this field; the server fills it.
      type: object
      required:
        - url
      title: McpToolConfig
      description: Configuration for a customer MCP server tool definition.
    McpToolDefinition:
      properties:
        schema_version:
          type: integer
          title: Schema Version
          description: Schema version.
          default: 1
        type:
          type: string
          const: mcp
          title: Type
          description: Tool type.
        config:
          $ref: "#/components/schemas/McpToolConfig"
          description: MCP server configuration.
      type: object
      required:
        - type
        - config
      title: McpToolDefinition
      description: Persisted MCP tool definition.
    PresetToolParameter:
      properties:
        name:
          type: string
          title: Name
          description: Parameter name used as a key in the request body.
        type:
          type: string
          enum:
            - string
            - number
            - boolean
            - object
            - array
          title: Type
          description: JSON type for the resolved value.
          llm_hint: Allowed values are string, number, boolean, object, and array.
        value_template:
          type: string
          title: Value Template
          description: Fixed value or template, e.g. {{initial_context.phone_number}}.
          llm_hint: Use {{initial_context.*}} for call-start context and
            {{gathered_context.*}} for values extracted during the call.
        required:
          type: boolean
          title: Required
          description: Whether the parameter must resolve to a non-empty value.
          default: true
      type: object
      required:
        - name
        - type
        - value_template
      title: PresetToolParameter
      description: A parameter injected by Menace Voice at runtime.
    ToolParameter:
      properties:
        name:
          type: string
          title: Name
          description: Parameter name used as a key in the tool request body.
          llm_hint: Use a stable snake_case name the agent can naturally fill.
        type:
          type: string
          enum:
            - string
            - number
            - boolean
            - object
            - array
          title: Type
          description: JSON type for the parameter value.
          llm_hint: Allowed values are string, number, boolean, object, and array.
        description:
          type: string
          title: Description
          description: Description shown to the model for this parameter.
          llm_hint: "Write this as an instruction to the agent: what value to provide and
            when."
        required:
          type: boolean
          title: Required
          description: Whether this parameter is required when the tool is called.
          default: true
      type: object
      required:
        - name
        - type
        - description
      title: ToolParameter
      description: A parameter that the tool accepts from the model at call time.
    ToolResponse:
      properties:
        id:
          type: integer
          title: Id
        tool_uuid:
          type: string
          title: Tool Uuid
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
        category:
          type: string
          title: Category
        icon:
          anyOf:
            - type: string
            - type: "null"
          title: Icon
        icon_color:
          anyOf:
            - type: string
            - type: "null"
          title: Icon Color
        status:
          type: string
          title: Status
        definition:
          additionalProperties: true
          type: object
          title: Definition
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: "null"
          title: Updated At
        created_by:
          anyOf:
            - $ref: "#/components/schemas/CreatedByResponse"
            - type: "null"
      type: object
      required:
        - id
        - tool_uuid
        - name
        - description
        - category
        - icon
        - icon_color
        - status
        - definition
        - created_at
        - updated_at
      title: ToolResponse
      description: Response schema for a reusable tool.
    TransferCallConfig:
      properties:
        destination_source:
          type: string
          enum:
            - static
            - dynamic
            - context_mapping
          title: Destination Source
          description: Whether the destination is static/template, resolved by HTTP, or
            selected by ordered gathered/initial-context mapping rules.
          default: static
        destination:
          type: string
          title: Destination
          description: Phone number, SIP endpoint, or template to transfer the call to,
            e.g. +1234567890, PJSIP/1234, or
            {{initial_context.transfer_destination}}.
          default: ""
        messageType:
          type: string
          enum:
            - none
            - custom
            - audio
          title: Messagetype
          description: Type of message to play before transfer.
          default: none
        customMessage:
          anyOf:
            - type: string
            - type: "null"
          title: Custommessage
          description: Custom message to play before transferring.
        audioRecordingId:
          anyOf:
            - type: string
            - type: "null"
          title: Audiorecordingid
          description: Recording ID for audio message before transfer.
        timeout:
          type: integer
          maximum: 120
          minimum: 5
          title: Timeout
          description: Maximum seconds to wait for the destination to answer.
          default: 30
        call_disposition:
          anyOf:
            - type: string
              maxLength: 64
            - type: "null"
          title: Call Disposition
          description: Optional disposition to record after a successful transfer. When
            omitted, Menace Voice records its provider-specific transfer
            default.
        parameters:
          anyOf:
            - items:
                $ref: "#/components/schemas/ToolParameter"
              type: array
            - type: "null"
          title: Parameters
          description: Parameters the model may provide when calling this transfer tool,
            for example state, department, or transfer reason.
        resolver:
          anyOf:
            - $ref: "#/components/schemas/HttpTransferResolverConfig"
            - type: "null"
          description: Optional resolver that determines transfer routing at call time.
        context_mapping:
          anyOf:
            - $ref: "#/components/schemas/ContextDestinationMappingConfig"
            - type: "null"
          description: Optional ordered context-to-destination routing rules.
      type: object
      title: TransferCallConfig
      description: Configuration for Transfer Call tools.
    TransferCallToolDefinition:
      properties:
        schema_version:
          type: integer
          title: Schema Version
          description: Schema version.
          default: 1
        type:
          type: string
          const: transfer_call
          title: Type
          description: Tool type.
        config:
          $ref: "#/components/schemas/TransferCallConfig"
          description: Transfer Call configuration.
      type: object
      required:
        - type
        - config
      title: TransferCallToolDefinition
      description: Tool definition for Transfer Call tools.
    UpdateToolRequest:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 255
            - type: "null"
          title: Name
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
        icon:
          anyOf:
            - type: string
              maxLength: 50
            - type: "null"
          title: Icon
        icon_color:
          anyOf:
            - type: string
              maxLength: 7
            - type: "null"
          title: Icon Color
        definition:
          anyOf:
            - oneOf:
                - $ref: "#/components/schemas/HttpApiToolDefinition"
                - $ref: "#/components/schemas/EndCallToolDefinition"
                - $ref: "#/components/schemas/TransferCallToolDefinition"
                - $ref: "#/components/schemas/CalculatorToolDefinition"
                - $ref: "#/components/schemas/CurrentTimeToolDefinition"
                - $ref: "#/components/schemas/McpToolDefinition"
              discriminator:
                propertyName: type
                mapping:
                  calculator: "#/components/schemas/CalculatorToolDefinition"
                  current_time: "#/components/schemas/CurrentTimeToolDefinition"
                  end_call: "#/components/schemas/EndCallToolDefinition"
                  http_api: "#/components/schemas/HttpApiToolDefinition"
                  mcp: "#/components/schemas/McpToolDefinition"
                  transfer_call: "#/components/schemas/TransferCallToolDefinition"
            - type: "null"
          title: Definition
        status:
          anyOf:
            - type: string
            - type: "null"
          title: Status
      type: object
      title: UpdateToolRequest
      description: Request schema for updating a reusable tool.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
````