> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create tool > Creates a new tool in the workspace. ## OpenAPI ````yaml post /v2/tools openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://api.orq.ai security: - ApiKey: [] tags: - name: Guardrail Rules - name: Policies - name: Routing Rules - name: Files description: File upload and retrieval operations. - name: FilesService - name: Projects description: Projects organize resources within a workspace - name: ProjectsService - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: SkillsService - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. - name: ReportingService description: |- ReportingService exposes a single QueryReport RPC that maps allowlisted analytics payloads onto safe rollup queries. Callers never send SQL; the backend picks the rollup family and grain from the metric catalogue, the requested range, and the requested grouping. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/tools: post: tags: - Tools summary: Create tool description: Creates a new tool in the workspace. operationId: CreateTool requestBody: description: The tool to create content: application/json: schema: oneOf: - type: object properties: path: type: string description: >- 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. example: Default key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- 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: type: string description: >- 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: type: string enum: - live - draft - pending - published default: live description: >- 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: type: string enum: - function function: type: object properties: name: type: string description: >- 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: type: string description: >- A description of what the function does, used by the model to choose when and how to call the function. strict: type: boolean description: >- 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: type: object properties: type: type: string enum: - object description: The type must be "object" properties: type: object additionalProperties: {} description: The properties of the function parameters required: type: array items: type: string description: Array of required parameter names required: - type - properties - required additionalProperties: {} description: >- 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. required: - name required: - path - key - description - type - function title: Function Tool description: >- A custom function tool that allows the model to call predefined functions with structured parameters. - type: object properties: path: type: string description: >- 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. example: Default key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- 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: type: string description: >- 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: type: string enum: - live - draft - pending - published default: live description: >- 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: enum: - json_schema type: string json_schema: type: object properties: name: type: string minLength: 1 maxLength: 64 description: >- 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: type: string description: >- A description of what the response format is for. This will be shown to the user. schema: type: object properties: type: type: string description: The JSON Schema type properties: type: object additionalProperties: {} description: The properties of the JSON Schema object required: type: array items: type: string description: Array of required property names required: - type - properties - required additionalProperties: {} description: >- 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. strict: type: boolean description: >- 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. required: - name - description - schema required: - path - key - description - type - json_schema title: JSON Schema Tool description: >- A tool that enforces structured output format using JSON Schema for consistent response formatting. - type: object properties: path: type: string description: >- 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. example: Default key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- 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: type: string description: >- 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: type: string enum: - live - draft - pending - published default: live description: >- 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: type: string enum: - http http: type: object properties: blueprint: type: object properties: url: type: string description: The URL to send the request to. method: type: string enum: - GET - POST - PUT - DELETE description: The HTTP method to use. headers: type: object additionalProperties: anyOf: - type: string - type: object properties: value: type: string encrypted: type: boolean default: false required: - value default: Content-Type: value: application/json encrypted: false description: >- The headers to send with the request. Can be a string value or an object with value and encrypted properties. body: type: object additionalProperties: {} description: The body to send with the request. required: - url - method description: >- The blueprint for the HTTP request. The `arguments` field will be used to replace the placeholders in the `url`, `headers`, `body`, and `arguments` fields. arguments: type: object additionalProperties: type: object properties: type: type: string enum: - string - number - boolean description: The type of the argument. description: type: string description: A description of the argument. send_to_model: type: boolean default: true description: >- Whether to send the argument to the model. If set to false, the argument will not be sent to the model and needs to be provided by the user or it will be left blank. default_value: anyOf: - type: string - type: number - type: boolean description: The default value of the argument. required: - type - description description: >- The arguments to send with the request. The keys will be used to replace the placeholders in the `blueprint` field. required: - blueprint required: - path - key - description - type - http title: HTTP Tool description: >- Executes HTTP requests to interact with external APIs and web services using customizable blueprints. - type: object properties: path: type: string description: >- 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. example: Default key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- 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: type: string description: >- 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: type: string enum: - live - draft - pending - published default: live description: >- 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: enum: - mcp type: string mcp: type: object properties: server_url: type: string format: uri description: The MCP server URL (cached for execution) headers: type: object additionalProperties: type: object properties: value: type: string encrypted: type: boolean default: false required: - value default: {} description: >- HTTP headers for MCP server requests with encryption support connection_type: type: string enum: - http - sse description: The connection type used by the MCP server required: - server_url - connection_type discovery_variables: type: object additionalProperties: type: string required: - path - key - description - type - mcp title: MCP Tool description: >- A tool from a Model Context Protocol (MCP) server that provides standardized access to external capabilities. - type: object properties: path: type: string description: >- 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. example: Default key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- 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: type: string description: >- 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: type: string enum: - live - draft - pending - published default: live description: >- 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: type: string enum: - code code_tool: type: object properties: parameters: type: object properties: type: type: string enum: - object description: The type must be "object" properties: type: object additionalProperties: {} description: The properties of the function parameters required: type: array items: type: string description: Array of required parameter names required: - type - properties - required additionalProperties: {} description: >- 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. language: type: string enum: - python code: type: string minLength: 1 description: The code to execute. required: - language - code required: - path - key - description - type - code_tool title: Code Execution Tool description: >- Executes code snippets in a sandboxed environment, currently supporting Python. responses: '200': description: Successfully created the tool. content: application/json: schema: oneOf: - type: object properties: _id: type: string default: tool_01KRM5REGW0Q73QFDDXPTWP6A8 path: type: string description: >- 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. example: Default key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- 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: type: string description: >- 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: type: string description: The id of the user that created the tool updated_by_id: type: string description: The id of the user that last updated the tool project_id: type: string workspace_id: type: string created: type: string updated: type: string status: type: string enum: - live - draft - pending - published default: live description: >- 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: type: string enum: - function function: type: object properties: name: type: string description: >- 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: type: string description: >- A description of what the function does, used by the model to choose when and how to call the function. strict: type: boolean description: >- 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: type: object properties: type: type: string enum: - object description: The type must be "object" properties: type: object additionalProperties: {} description: The properties of the function parameters required: type: array items: type: string description: Array of required parameter names required: - type - properties - required additionalProperties: {} description: >- 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. required: - name required: - path - key - description - project_id - workspace_id - created - updated - type - function title: Function Tool description: >- A custom function tool that allows the model to call predefined functions with structured parameters. - type: object properties: _id: type: string default: tool_01KRM5REGXRPH7VGRWDT8ZK7DY path: type: string description: >- 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. example: Default key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- 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: type: string description: >- 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: type: string description: The id of the user that created the tool updated_by_id: type: string description: The id of the user that last updated the tool project_id: type: string workspace_id: type: string created: type: string updated: type: string status: type: string enum: - live - draft - pending - published default: live description: >- 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: enum: - json_schema type: string json_schema: type: object properties: name: type: string minLength: 1 maxLength: 64 description: >- 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: type: string description: >- A description of what the response format is for. This will be shown to the user. schema: type: object properties: type: type: string description: The JSON Schema type properties: type: object additionalProperties: {} description: The properties of the JSON Schema object required: type: array items: type: string description: Array of required property names required: - type - properties - required additionalProperties: {} description: >- 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. strict: type: boolean description: >- 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. required: - name - description - schema required: - path - key - description - project_id - workspace_id - created - updated - type - json_schema title: JSON Schema Tool description: >- A tool that enforces structured output format using JSON Schema for consistent response formatting. - type: object properties: _id: type: string default: tool_01KRM5REGXB2DXK53B6EZVX8QD path: type: string description: >- 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. example: Default key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- 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: type: string description: >- 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: type: string description: The id of the user that created the tool updated_by_id: type: string description: The id of the user that last updated the tool project_id: type: string workspace_id: type: string created: type: string updated: type: string status: type: string enum: - live - draft - pending - published default: live description: >- 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: type: string enum: - http http: type: object properties: blueprint: type: object properties: url: type: string description: The URL to send the request to. method: type: string enum: - GET - POST - PUT - DELETE description: The HTTP method to use. headers: type: object additionalProperties: anyOf: - type: string - type: object properties: value: type: string encrypted: type: boolean default: false required: - value default: Content-Type: value: application/json encrypted: false description: >- The headers to send with the request. Can be a string value or an object with value and encrypted properties. body: type: object additionalProperties: {} description: The body to send with the request. required: - url - method description: >- The blueprint for the HTTP request. The `arguments` field will be used to replace the placeholders in the `url`, `headers`, `body`, and `arguments` fields. arguments: type: object additionalProperties: type: object properties: type: type: string enum: - string - number - boolean description: The type of the argument. description: type: string description: A description of the argument. send_to_model: type: boolean default: true description: >- Whether to send the argument to the model. If set to false, the argument will not be sent to the model and needs to be provided by the user or it will be left blank. default_value: anyOf: - type: string - type: number - type: boolean description: The default value of the argument. required: - type - description description: >- The arguments to send with the request. The keys will be used to replace the placeholders in the `blueprint` field. required: - blueprint required: - path - key - description - project_id - workspace_id - created - updated - type - http title: HTTP Tool description: >- Executes HTTP requests to interact with external APIs and web services using customizable blueprints. - type: object properties: _id: type: string default: tool_01KRM5REGY4Q0209AYW0CRG927 path: type: string description: >- 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. example: Default key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- 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: type: string description: >- 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: type: string description: The id of the user that created the tool updated_by_id: type: string description: The id of the user that last updated the tool project_id: type: string workspace_id: type: string created: type: string updated: type: string status: type: string enum: - live - draft - pending - published default: live description: >- 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: enum: - mcp type: string mcp: type: object properties: server_url: type: string format: uri description: The MCP server URL (cached for execution) headers: type: object additionalProperties: type: object properties: value: type: string encrypted: type: boolean default: false required: - value default: {} description: >- HTTP headers for MCP server requests with encryption support tools: type: array items: type: object properties: id: type: string default: 01KRM5REGYQKAKEJ31GPEHPGBP name: type: string description: type: string schema: type: object properties: type: type: string enum: - object properties: type: object additionalProperties: {} required: type: array items: type: string required: - type required: - name - schema description: Array of tools available from the MCP server connection_type: type: string enum: - http - sse description: The connection type used by the MCP server template_variables: type: - array - 'null' items: type: string description: >- Names of template variables detected in server_url and headers. Used by the FE to prompt for one-time values on sync/refresh. readOnly: true required: - server_url - tools - connection_type required: - path - key - description - project_id - workspace_id - created - updated - type - mcp title: MCP Tool description: >- A tool from a Model Context Protocol (MCP) server that provides standardized access to external capabilities. - type: object properties: _id: type: string default: tool_01KRM5REGZJMRD3YTPG8V3FQW8 path: type: string description: >- 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. example: Default key: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z]([A-Za-z0-9]*([_-][A-Za-z0-9]+)*)?$ description: >- Unique key of the tool as it will be displayed in the UI display_name: type: string description: >- 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: type: string description: >- 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: type: string description: The id of the user that created the tool updated_by_id: type: string description: The id of the user that last updated the tool project_id: type: string workspace_id: type: string created: type: string updated: type: string status: type: string enum: - live - draft - pending - published default: live description: >- 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: type: string enum: - code code_tool: type: object properties: parameters: type: object properties: type: type: string enum: - object description: The type must be "object" properties: type: object additionalProperties: {} description: The properties of the function parameters required: type: array items: type: string description: Array of required parameter names required: - type - properties - required additionalProperties: {} description: >- 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. language: type: string enum: - python code: type: string minLength: 1 description: The code to execute. required: - language - code required: - path - key - description - project_id - workspace_id - created - updated - type - code_tool title: Code Execution Tool description: >- Executes code snippets in a sandboxed environment, currently supporting Python. components: securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````