---
title: "Create Tool"
method: POST
path: "/workflows/v1/tools"
tags: ["Tools"]
---

# Create Tool

`POST /workflows/v1/tools`

Endpoint to create a new tool.

## Request body

- union
  - InlinePythonToolConfig — Configuration for an inline Python tool. The "code" field should contain a self-contained executable Python function. Example value of "code" string could be: def add( a: float, b: float, ) -> float: return float(a + b)
    - `logical_id` string, nullable — Unique identifier for the tool
    - `tool_id` string, nullable — Reference to the tool already created in the Workflow System. If not provided, the tool config is assumed to be provided inline here.
    - `name` string, nullable — Name for the tool
    - `description` string, nullable — Human friendly description for the tool (not used by AI)
    - `category` string, nullable — Category for the tool. E.g math, ehr, etc
    - `side_effect` string, nullable — Side-effect classification used by the test-tool feature to decide whether the tool can be safely executed directly, or must be dry-run / confirmation-gated first. One of 'none', 'reads', 'writes', 'sends', 'unknown'. When not set, it is inferred from the tool type.
    - `signature` string, nullable — Docstring or signature for the tool used by AI. If provided and there is a default signature already, it will override the default signature.
    - `args_schema` object, nullable — Schema for the arguments that the tool accepts. This should be a JSON schema dictionary. Information provided here will override any default arguments schema.
    - `static_messages_config` StaticMessagesConfig
      - `static_messages` string[] — List of pre-configured messages from which one will be emitted
      - `static_messages_selection_mode` 'random' | 'sequence'
    - `result_runtime_variable_name` string, nullable — Name of the runtime variable to store the result from this tool call
    - `ignore_content_received_during_llm_tool_call_specification` boolean — If true, any free-text content the LLM returns in the same response as a call to this tool is ignored: not emitted via AssistantResponseEvent, not added to chat history, and not added to the node's structured output. When a response contains multiple tool calls, the text is ignored only if every tool call targets a tool for which this flag is set.
    - `type` 'inline_python' — Type of the tool. Must be 'inline_python'
    - `code` string, nullable — Python code to be executed by the tool. It should define a function with proper signature and descriptions for its parameters.
  - InbuiltFunctionToolConfig — Configuration for an inbuilt function tool. This tool type refers to functions that are already registered in the tools registry. The "tool_id" field must match the ID (decorated with "@tool_id") of a registered tool.
    - `logical_id` string, nullable — Unique identifier for the tool
    - `tool_id` string, nullable — Reference to the tool already created in the Workflow System. If not provided, the tool config is assumed to be provided inline here.
    - `name` string, nullable — Name for the tool
    - `description` string, nullable — Human friendly description for the tool (not used by AI)
    - `category` string, nullable — Category for the tool. E.g math, ehr, etc
    - `side_effect` string, nullable — Side-effect classification used by the test-tool feature to decide whether the tool can be safely executed directly, or must be dry-run / confirmation-gated first. One of 'none', 'reads', 'writes', 'sends', 'unknown'. When not set, it is inferred from the tool type.
    - `signature` string, nullable — Docstring or signature for the tool used by AI. If provided and there is a default signature already, it will override the default signature.
    - `args_schema` object, nullable — Schema for the arguments that the tool accepts. This should be a JSON schema dictionary. Information provided here will override any default arguments schema.
    - `static_messages_config` StaticMessagesConfig
      - `static_messages` string[] — List of pre-configured messages from which one will be emitted
      - `static_messages_selection_mode` 'random' | 'sequence'
    - `result_runtime_variable_name` string, nullable — Name of the runtime variable to store the result from this tool call
    - `ignore_content_received_during_llm_tool_call_specification` boolean — If true, any free-text content the LLM returns in the same response as a call to this tool is ignored: not emitted via AssistantResponseEvent, not added to chat history, and not added to the node's structured output. When a response contains multiple tool calls, the text is ignored only if every tool call targets a tool for which this flag is set.
    - `type` 'inbuilt_function' — Type of the tool. Must be 'inbuilt_function'
    - `configurable_key` string, nullable — Stable key identifying which configurable inbuilt tool this is (e.g. 'call_forward'). None for plain static inbuilt references.
    - `extra_config` object, nullable — Tool-specific user configuration values. Schema is defined per configurable key.
  - ExternalAPIToolConfig — Configuration for an external API tool. This tool type represents an external API endpoint that the LLM can call.
    - `logical_id` string, nullable — Unique identifier for the tool
    - `tool_id` string, nullable — Reference to the tool already created in the Workflow System. If not provided, the tool config is assumed to be provided inline here.
    - `name` string, nullable — Name for the tool
    - `description` string, nullable — Human friendly description for the tool (not used by AI)
    - `category` string, nullable — Category for the tool. E.g math, ehr, etc
    - `side_effect` string, nullable — Side-effect classification used by the test-tool feature to decide whether the tool can be safely executed directly, or must be dry-run / confirmation-gated first. One of 'none', 'reads', 'writes', 'sends', 'unknown'. When not set, it is inferred from the tool type.
    - `signature` string, nullable — Docstring or signature for the tool used by AI. If provided and there is a default signature already, it will override the default signature.
    - `args_schema` object, nullable — Schema for the arguments that the tool accepts. This should be a JSON schema dictionary. Information provided here will override any default arguments schema.
    - `static_messages_config` StaticMessagesConfig
      - `static_messages` string[] — List of pre-configured messages from which one will be emitted
      - `static_messages_selection_mode` 'random' | 'sequence'
    - `result_runtime_variable_name` string, nullable — Name of the runtime variable to store the result from this tool call
    - `ignore_content_received_during_llm_tool_call_specification` boolean — If true, any free-text content the LLM returns in the same response as a call to this tool is ignored: not emitted via AssistantResponseEvent, not added to chat history, and not added to the node's structured output. When a response contains multiple tool calls, the text is ignored only if every tool call targets a tool for which this flag is set.
    - `type` 'external_api' — Type of the tool. Must be 'external_api'
    - `api_endpoint` string, nullable — The endpoint URL of the external API
    - `api_method` 'GET' | 'POST' | 'PUT' | 'DELETE' — Enumeration of HTTP methods for API calls.
    - `api_headers` object — HTTP headers to include with the API request (e.g., authorization, content-type)
    - `api_body` union — The request body payload for the API call. Usually applicable for POST/PUT methods.
      - object
      - string
  - KnowledgeBaseToolConfig — Configuration for a knowledge base tool. This tool type represents a knowledge base endpoint that the LLM can call.
    - `logical_id` string, nullable — Unique identifier for the tool
    - `tool_id` string, nullable — Reference to the tool already created in the Workflow System. If not provided, the tool config is assumed to be provided inline here.
    - `name` string, nullable — Name for the tool
    - `description` string, nullable — Human friendly description for the tool (not used by AI)
    - `category` string, nullable — Category for the tool. E.g math, ehr, etc
    - `side_effect` string, nullable — Side-effect classification used by the test-tool feature to decide whether the tool can be safely executed directly, or must be dry-run / confirmation-gated first. One of 'none', 'reads', 'writes', 'sends', 'unknown'. When not set, it is inferred from the tool type.
    - `signature` string, nullable — Docstring or signature for the tool used by AI. If provided and there is a default signature already, it will override the default signature.
    - `args_schema` object, nullable — Schema for the arguments that the tool accepts. This should be a JSON schema dictionary. Information provided here will override any default arguments schema.
    - `static_messages_config` StaticMessagesConfig
      - `static_messages` string[] — List of pre-configured messages from which one will be emitted
      - `static_messages_selection_mode` 'random' | 'sequence'
    - `result_runtime_variable_name` string, nullable — Name of the runtime variable to store the result from this tool call
    - `ignore_content_received_during_llm_tool_call_specification` boolean — If true, any free-text content the LLM returns in the same response as a call to this tool is ignored: not emitted via AssistantResponseEvent, not added to chat history, and not added to the node's structured output. When a response contains multiple tool calls, the text is ignored only if every tool call targets a tool for which this flag is set.
    - `type` 'knowledge_base' — Type of the tool. Must be 'knowledge_base'
    - `target_knowledge_base_ids` string[] — The IDs of the knowledge bases to query

## Response `200`

Successful Response

- ToolsResponse — Response model for a single tool. Contains a ToolsModel object.
  - `tool` ToolsModel, required — Stores a tool config present in the workflow system. It contains configuration fields for different types of tools (inbuilt_function, inline_python, external_api).
    - `team_id` string, nullable — ID of the team that owns this edge
    - `created_by` string, nullable — ID of the user who created this edge
    - `updated_by` string, nullable — ID of the user who last updated this edge
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `_id` string
    - `tool_config` union — Tool Configuration
      - InlinePythonToolConfig — Configuration for an inline Python tool. The "code" field should contain a self-contained executable Python function. Example value of "code" string could be: def add( a: float, b: float, ) -> float: return float(a + b)
        - `logical_id` string, nullable — Unique identifier for the tool
        - `tool_id` string, nullable — Reference to the tool already created in the Workflow System. If not provided, the tool config is assumed to be provided inline here.
        - `name` string, nullable — Name for the tool
        - `description` string, nullable — Human friendly description for the tool (not used by AI)
        - `category` string, nullable — Category for the tool. E.g math, ehr, etc
        - `side_effect` string, nullable — Side-effect classification used by the test-tool feature to decide whether the tool can be safely executed directly, or must be dry-run / confirmation-gated first. One of 'none', 'reads', 'writes', 'sends', 'unknown'. When not set, it is inferred from the tool type.
        - `signature` string, nullable — Docstring or signature for the tool used by AI. If provided and there is a default signature already, it will override the default signature.
        - `args_schema` object, nullable — Schema for the arguments that the tool accepts. This should be a JSON schema dictionary. Information provided here will override any default arguments schema.
        - `static_messages_config` StaticMessagesConfig
          - `static_messages` string[] — List of pre-configured messages from which one will be emitted
          - `static_messages_selection_mode` 'random' | 'sequence'
        - `result_runtime_variable_name` string, nullable — Name of the runtime variable to store the result from this tool call
        - `ignore_content_received_during_llm_tool_call_specification` boolean — If true, any free-text content the LLM returns in the same response as a call to this tool is ignored: not emitted via AssistantResponseEvent, not added to chat history, and not added to the node's structured output. When a response contains multiple tool calls, the text is ignored only if every tool call targets a tool for which this flag is set.
        - `type` 'inline_python' — Type of the tool. Must be 'inline_python'
        - `code` string, nullable — Python code to be executed by the tool. It should define a function with proper signature and descriptions for its parameters.
      - InbuiltFunctionToolConfig — Configuration for an inbuilt function tool. This tool type refers to functions that are already registered in the tools registry. The "tool_id" field must match the ID (decorated with "@tool_id") of a registered tool.
        - `logical_id` string, nullable — Unique identifier for the tool
        - `tool_id` string, nullable — Reference to the tool already created in the Workflow System. If not provided, the tool config is assumed to be provided inline here.
        - `name` string, nullable — Name for the tool
        - `description` string, nullable — Human friendly description for the tool (not used by AI)
        - `category` string, nullable — Category for the tool. E.g math, ehr, etc
        - `side_effect` string, nullable — Side-effect classification used by the test-tool feature to decide whether the tool can be safely executed directly, or must be dry-run / confirmation-gated first. One of 'none', 'reads', 'writes', 'sends', 'unknown'. When not set, it is inferred from the tool type.
        - `signature` string, nullable — Docstring or signature for the tool used by AI. If provided and there is a default signature already, it will override the default signature.
        - `args_schema` object, nullable — Schema for the arguments that the tool accepts. This should be a JSON schema dictionary. Information provided here will override any default arguments schema.
        - `static_messages_config` StaticMessagesConfig
          - `static_messages` string[] — List of pre-configured messages from which one will be emitted
          - `static_messages_selection_mode` 'random' | 'sequence'
        - `result_runtime_variable_name` string, nullable — Name of the runtime variable to store the result from this tool call
        - `ignore_content_received_during_llm_tool_call_specification` boolean — If true, any free-text content the LLM returns in the same response as a call to this tool is ignored: not emitted via AssistantResponseEvent, not added to chat history, and not added to the node's structured output. When a response contains multiple tool calls, the text is ignored only if every tool call targets a tool for which this flag is set.
        - `type` 'inbuilt_function' — Type of the tool. Must be 'inbuilt_function'
        - `configurable_key` string, nullable — Stable key identifying which configurable inbuilt tool this is (e.g. 'call_forward'). None for plain static inbuilt references.
        - `extra_config` object, nullable — Tool-specific user configuration values. Schema is defined per configurable key.
      - ExternalAPIToolConfig — Configuration for an external API tool. This tool type represents an external API endpoint that the LLM can call.
        - `logical_id` string, nullable — Unique identifier for the tool
        - `tool_id` string, nullable — Reference to the tool already created in the Workflow System. If not provided, the tool config is assumed to be provided inline here.
        - `name` string, nullable — Name for the tool
        - `description` string, nullable — Human friendly description for the tool (not used by AI)
        - `category` string, nullable — Category for the tool. E.g math, ehr, etc
        - `side_effect` string, nullable — Side-effect classification used by the test-tool feature to decide whether the tool can be safely executed directly, or must be dry-run / confirmation-gated first. One of 'none', 'reads', 'writes', 'sends', 'unknown'. When not set, it is inferred from the tool type.
        - `signature` string, nullable — Docstring or signature for the tool used by AI. If provided and there is a default signature already, it will override the default signature.
        - `args_schema` object, nullable — Schema for the arguments that the tool accepts. This should be a JSON schema dictionary. Information provided here will override any default arguments schema.
        - `static_messages_config` StaticMessagesConfig
          - `static_messages` string[] — List of pre-configured messages from which one will be emitted
          - `static_messages_selection_mode` 'random' | 'sequence'
        - `result_runtime_variable_name` string, nullable — Name of the runtime variable to store the result from this tool call
        - `ignore_content_received_during_llm_tool_call_specification` boolean — If true, any free-text content the LLM returns in the same response as a call to this tool is ignored: not emitted via AssistantResponseEvent, not added to chat history, and not added to the node's structured output. When a response contains multiple tool calls, the text is ignored only if every tool call targets a tool for which this flag is set.
        - `type` 'external_api' — Type of the tool. Must be 'external_api'
        - `api_endpoint` string, nullable — The endpoint URL of the external API
        - `api_method` 'GET' | 'POST' | 'PUT' | 'DELETE' — Enumeration of HTTP methods for API calls.
        - `api_headers` object — HTTP headers to include with the API request (e.g., authorization, content-type)
        - `api_body` union — The request body payload for the API call. Usually applicable for POST/PUT methods.
          - object
          - string
      - KnowledgeBaseToolConfig — Configuration for a knowledge base tool. This tool type represents a knowledge base endpoint that the LLM can call.
        - `logical_id` string, nullable — Unique identifier for the tool
        - `tool_id` string, nullable — Reference to the tool already created in the Workflow System. If not provided, the tool config is assumed to be provided inline here.
        - `name` string, nullable — Name for the tool
        - `description` string, nullable — Human friendly description for the tool (not used by AI)
        - `category` string, nullable — Category for the tool. E.g math, ehr, etc
        - `side_effect` string, nullable — Side-effect classification used by the test-tool feature to decide whether the tool can be safely executed directly, or must be dry-run / confirmation-gated first. One of 'none', 'reads', 'writes', 'sends', 'unknown'. When not set, it is inferred from the tool type.
        - `signature` string, nullable — Docstring or signature for the tool used by AI. If provided and there is a default signature already, it will override the default signature.
        - `args_schema` object, nullable — Schema for the arguments that the tool accepts. This should be a JSON schema dictionary. Information provided here will override any default arguments schema.
        - `static_messages_config` StaticMessagesConfig
          - `static_messages` string[] — List of pre-configured messages from which one will be emitted
          - `static_messages_selection_mode` 'random' | 'sequence'
        - `result_runtime_variable_name` string, nullable — Name of the runtime variable to store the result from this tool call
        - `ignore_content_received_during_llm_tool_call_specification` boolean — If true, any free-text content the LLM returns in the same response as a call to this tool is ignored: not emitted via AssistantResponseEvent, not added to chat history, and not added to the node's structured output. When a response contains multiple tool calls, the text is ignored only if every tool call targets a tool for which this flag is set.
        - `type` 'knowledge_base' — Type of the tool. Must be 'knowledge_base'
        - `target_knowledge_base_ids` string[] — The IDs of the knowledge bases to query

## Other responses

- `422` — Validation Error

## Changes

- **2026-07-21** `d276be705570` — 8 info
  - added the new optional request property `oneOf[subschema #1: Inline Python Tool]/side_effect`
  - added the new optional request property `oneOf[subschema #2: Inbuilt Function Tool]/side_effect`
  - added the new optional request property `oneOf[subschema #3: External API Tool]/side_effect`
  - added the new optional request property `oneOf[subschema #4: Knowledge Base Tool]/side_effect`
  - …4 more

[Change history](https://skmtc.dev/interactly/apis/interactly-api-3/changes/workflows/v1/tools/post.md)

---

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