---
title: "Update tool"
method: PATCH
path: "/v2/tools/{tool_id}"
tags: ["Tools"]
---

# Update tool

`PATCH /v2/tools/{tool_id}`

Updates a tool in the workspace.

## Path parameters

- `tool_id` string, required

## Request body

- union
  - object — Updates an existing function tool configuration.
    - `path` string — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.
    - `key` string — Unique key of the tool as it will be displayed in the UI
    - `display_name` string — The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used.
    - `description` string — A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision.
    - `status` 'live' | 'draft' | 'pending' | 'published' — The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version.
    - `type` 'function', required
    - `function` object
      - `name` string, required — The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
      - `description` string — A description of what the function does, used by the model to choose when and how to call the function.
      - `strict` boolean — Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Currently only compatible with `OpenAI` models.
      - `parameters` object — The parameters the functions accepts, described as a JSON Schema object. See the `OpenAI` [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.
        - `type` 'object', required — The type must be "object"
        - `properties` object, required — The properties of the function parameters
        - `required` string[], required — Array of required parameter names
    - `versionIncrement` 'major' | 'minor' | 'patch'
    - `versionDescription` string
  - object — Updates an existing JSON Schema tool configuration.
    - `path` string — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.
    - `key` string — Unique key of the tool as it will be displayed in the UI
    - `display_name` string — The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used.
    - `description` string — A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision.
    - `status` 'live' | 'draft' | 'pending' | 'published' — The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version.
    - `type` 'json_schema', required
    - `json_schema` object
      - `name` string, required — The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
      - `description` string, required — A description of what the response format is for. This will be shown to the user.
      - `schema` object, required — The schema for the response format, described as a JSON Schema object. See the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.
        - `type` string, required — The JSON Schema type
        - `properties` object, required — The properties of the JSON Schema object
        - `required` string[], required — Array of required property names
      - `strict` boolean — Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. Only compatible with `OpenAI` models.
    - `versionIncrement` 'major' | 'minor' | 'patch'
    - `versionDescription` string
  - object — Updates an existing HTTP tool configuration.
    - `path` string — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.
    - `key` string — Unique key of the tool as it will be displayed in the UI
    - `display_name` string — The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used.
    - `description` string — A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision.
    - `status` 'live' | 'draft' | 'pending' | 'published' — The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version.
    - `type` 'http', required
    - `http` object
      - `blueprint` object, required — The blueprint for the HTTP request. The `arguments` field will be used to replace the placeholders in the `url`, `headers`, `body`, and `arguments` fields.
        - `url` string, required — The URL to send the request to.
        - `method` 'GET' | 'POST' | 'PUT' | 'DELETE', required — The HTTP method to use.
        - `headers` object — The headers to send with the request. Can be a string value or an object with value and encrypted properties.
        - `body` object — The body to send with the request.
        - `timeout` number — The request timeout in seconds. Defaults to 60 seconds when not set. When used in an agent, tool executions are also bound by the agent run `limits.tool_timeout` (default 5 minutes), so raise that limit for longer-running tools.
      - `arguments` object — The arguments to send with the request. The keys will be used to replace the placeholders in the `blueprint` field.
    - `versionIncrement` 'major' | 'minor' | 'patch'
    - `versionDescription` string
  - object — Updates an existing MCP tool configuration.
    - `path` string — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.
    - `key` string — Unique key of the tool as it will be displayed in the UI
    - `display_name` string — The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used.
    - `description` string — A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision.
    - `status` 'live' | 'draft' | 'pending' | 'published' — The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version.
    - `type` 'mcp', required
    - `mcp` object
      - `server_url` string, uri — The MCP server URL (cached for execution)
      - `headers` object — HTTP headers for MCP server requests with encryption support
      - `tools` object[] — Array of tools available from the MCP server
        - `id` string
        - `name` string, required
        - `description` string
        - `schema` object, required
          - `type` 'object', required
          - `properties` object
          - `required` string[]
      - `connection_type` 'http' | 'sse' — The connection type used by the MCP server
      - `template_variables` string[], nullable — Names of template variables detected in server_url and headers. Used by the FE to prompt for one-time values on sync/refresh.
    - `discovery_variables` object
    - `versionIncrement` 'major' | 'minor' | 'patch'
    - `versionDescription` string
  - object — Updates an existing code execution tool configuration.
    - `path` string — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.
    - `key` string — Unique key of the tool as it will be displayed in the UI
    - `display_name` string — The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used.
    - `description` string — A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision.
    - `status` 'live' | 'draft' | 'pending' | 'published' — The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version.
    - `type` 'code', required
    - `code_tool` object
      - `parameters` object — The parameters the functions accepts, described as a JSON Schema object. See the `OpenAI` [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.
        - `type` 'object', required — The type must be "object"
        - `properties` object, required — The properties of the function parameters
        - `required` string[], required — Array of required parameter names
      - `language` 'python', required
      - `code` string, required — The code to execute.
    - `versionIncrement` 'major' | 'minor' | 'patch'
    - `versionDescription` string

## Response `200`

Successfully updated the tool.

- union
  - object — A custom function tool that allows the model to call predefined functions with structured parameters.
    - `_id` string
    - `path` string, required — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.
    - `key` string, required — Unique key of the tool as it will be displayed in the UI
    - `display_name` string — The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used.
    - `description` string, required — A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision.
    - `created_by_id` string, nullable — The id of the user that created the tool
    - `updated_by_id` string, nullable — The id of the user that last updated the tool
    - `project_id` string, required
    - `workspace_id` string, required
    - `created` string, required
    - `updated` string, required
    - `status` 'live' | 'draft' | 'pending' | 'published' — The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version.
    - `type` 'function', required
    - `function` object, required
      - `name` string, required — The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
      - `description` string — A description of what the function does, used by the model to choose when and how to call the function.
      - `strict` boolean — Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Currently only compatible with `OpenAI` models.
      - `parameters` object — The parameters the functions accepts, described as a JSON Schema object. See the `OpenAI` [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.
        - `type` 'object', required — The type must be "object"
        - `properties` object, required — The properties of the function parameters
        - `required` string[], required — Array of required parameter names
  - object — A tool that enforces structured output format using JSON Schema for consistent response formatting.
    - `_id` string
    - `path` string, required — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.
    - `key` string, required — Unique key of the tool as it will be displayed in the UI
    - `display_name` string — The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used.
    - `description` string, required — A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision.
    - `created_by_id` string, nullable — The id of the user that created the tool
    - `updated_by_id` string, nullable — The id of the user that last updated the tool
    - `project_id` string, required
    - `workspace_id` string, required
    - `created` string, required
    - `updated` string, required
    - `status` 'live' | 'draft' | 'pending' | 'published' — The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version.
    - `type` 'json_schema', required
    - `json_schema` object, required
      - `name` string, required — The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
      - `description` string, required — A description of what the response format is for. This will be shown to the user.
      - `schema` object, required — The schema for the response format, described as a JSON Schema object. See the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.
        - `type` string, required — The JSON Schema type
        - `properties` object, required — The properties of the JSON Schema object
        - `required` string[], required — Array of required property names
      - `strict` boolean — Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. Only compatible with `OpenAI` models.
  - object — Executes HTTP requests to interact with external APIs and web services using customizable blueprints.
    - `_id` string
    - `path` string, required — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.
    - `key` string, required — Unique key of the tool as it will be displayed in the UI
    - `display_name` string — The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used.
    - `description` string, required — A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision.
    - `created_by_id` string, nullable — The id of the user that created the tool
    - `updated_by_id` string, nullable — The id of the user that last updated the tool
    - `project_id` string, required
    - `workspace_id` string, required
    - `created` string, required
    - `updated` string, required
    - `status` 'live' | 'draft' | 'pending' | 'published' — The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version.
    - `type` 'http', required
    - `http` object, required
      - `blueprint` object, required — The blueprint for the HTTP request. The `arguments` field will be used to replace the placeholders in the `url`, `headers`, `body`, and `arguments` fields.
        - `url` string, required — The URL to send the request to.
        - `method` 'GET' | 'POST' | 'PUT' | 'DELETE', required — The HTTP method to use.
        - `headers` object — The headers to send with the request. Can be a string value or an object with value and encrypted properties.
        - `body` object — The body to send with the request.
        - `timeout` number — The request timeout in seconds. Defaults to 60 seconds when not set. When used in an agent, tool executions are also bound by the agent run `limits.tool_timeout` (default 5 minutes), so raise that limit for longer-running tools.
      - `arguments` object — The arguments to send with the request. The keys will be used to replace the placeholders in the `blueprint` field.
  - object — A tool from a Model Context Protocol (MCP) server that provides standardized access to external capabilities.
    - `_id` string
    - `path` string, required — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.
    - `key` string, required — Unique key of the tool as it will be displayed in the UI
    - `display_name` string — The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used.
    - `description` string, required — A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision.
    - `created_by_id` string, nullable — The id of the user that created the tool
    - `updated_by_id` string, nullable — The id of the user that last updated the tool
    - `project_id` string, required
    - `workspace_id` string, required
    - `created` string, required
    - `updated` string, required
    - `status` 'live' | 'draft' | 'pending' | 'published' — The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version.
    - `type` 'mcp', required
    - `mcp` object, required
      - `server_url` string, uri, required — The MCP server URL (cached for execution)
      - `headers` object — HTTP headers for MCP server requests with encryption support
      - `tools` object[], required — Array of tools available from the MCP server
        - `id` string
        - `name` string, required
        - `description` string
        - `schema` object, required
          - `type` 'object', required
          - `properties` object
          - `required` string[]
      - `connection_type` 'http' | 'sse', required — The connection type used by the MCP server
      - `template_variables` string[], nullable — Names of template variables detected in server_url and headers. Used by the FE to prompt for one-time values on sync/refresh.
  - object — Executes code snippets in a sandboxed environment, currently supporting Python.
    - `_id` string
    - `path` string, required — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.
    - `key` string, required — Unique key of the tool as it will be displayed in the UI
    - `display_name` string — The name of the tool as it will be displayed in the UI. This is optional and if not provided, the `key` will be used.
    - `description` string, required — A description of the tool, used by the model to choose when and how to call the tool. We do recommend using the `description` field as accurate as possible to give enough context to the model to make the right decision.
    - `created_by_id` string, nullable — The id of the user that created the tool
    - `updated_by_id` string, nullable — The id of the user that last updated the tool
    - `project_id` string, required
    - `workspace_id` string, required
    - `created` string, required
    - `updated` string, required
    - `status` 'live' | 'draft' | 'pending' | 'published' — The status of the tool. `Live` is the latest version of the tool. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version.
    - `type` 'code', required
    - `code_tool` object, required
      - `parameters` object — The parameters the functions accepts, described as a JSON Schema object. See the `OpenAI` [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.
        - `type` 'object', required — The type must be "object"
        - `properties` object, required — The properties of the function parameters
        - `required` string[], required — Array of required parameter names
      - `language` 'python', required
      - `code` string, required — The code to execute.

## Other responses

- `404` — Tool not found.

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/versions/41c02aedc7c0/schema)