---
title: "Create tool"
method: POST
path: "/v2/tools"
tags: ["Tools"]
---

# Create tool

`POST /v2/tools`

Creates a new tool in the workspace.

## Request body

- union
  - object — A custom function tool that allows the model to call predefined functions with structured parameters.
    - `path` string, required — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: `Default Project/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.
    - `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.
    - `path` string, required — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: `Default Project/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.
    - `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.
    - `path` string, required — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: `Default Project/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.
    - `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 — Executes code snippets in a sandboxed environment, currently supporting Python.
    - `path` string, required — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: `Default Project/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.
    - `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.

## Response `200`

Successfully created 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 must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: `Default Project/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 must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: `Default Project/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 must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: `Default Project/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 — 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 must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: `Default Project/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.

## Changes

> 254 revisions in range; 71 not diffed.

- **2026-08-31** `b22330eb2d5a` — 4 info
  - the `_id` response's property default value changed from `tool_01M1BS0MEC1ZYHY3KYE3NCD2VK` to `tool_01M1D09ENC4C6R3E959QKS214K` for the status `200`
  - the `_id` response's property default value changed from `tool_01M1BS0MEDQKQGBVSNK7FTHZ2X` to `tool_01M1D09END768AQFDSRTQY5K74` for the status `200`
  - the `_id` response's property default value changed from `tool_01M1BS0MEER1GSQJEGMTA24EGK` to `tool_01M1D09ENE3GQT33N4675C2TDA` for the status `200`
  - the `_id` response's property default value changed from `tool_01M1BS0MEGXWCH9S8K1YS1Q1RJ` to `tool_01M1D09ENGN4HWZ5ZR2H19PP3B` for the status `200`
- **2026-08-31** `94a16765e3fe` — 4 info
  - the `_id` response's property default value changed from `tool_01M1BBCBG7CK6W3WWX55MREP84` to `tool_01M1BS0MEDQKQGBVSNK7FTHZ2X` for the status `200`
  - the `_id` response's property default value changed from `tool_01M1BBCBG7T5KQD4M75WAN5PEN` to `tool_01M1BS0MEC1ZYHY3KYE3NCD2VK` for the status `200`
  - the `_id` response's property default value changed from `tool_01M1BBCBG812GM3DH630S3VZFQ` to `tool_01M1BS0MEER1GSQJEGMTA24EGK` for the status `200`
  - the `_id` response's property default value changed from `tool_01M1BBCBG8YS162HN50KQPGB5S` to `tool_01M1BS0MEGXWCH9S8K1YS1Q1RJ` for the status `200`
- …earlier changes not shown

[Full history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v2/tools/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/revisions/b22330eb2d5a/schema)