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

# Import Tool

`POST /workflows/v1/tools/import`

Create a new tool from an exported bundle (see GET /tools/{tool_id}/export).

Re-injects redacted secrets from ``secret_overrides``, resolves non-portable
references, assigns a fresh identity to the importing team, and persists through
the same validation path as create_tool.

## Request body

- ToolBundleImportRequest
  - `bundle` ToolBundleExportResponse, required — Self-describing envelope for an exported custom tool. ``tool_config`` is a plain dict (not the ``ToolConfig`` model) so the ``<REDACTED>`` sentinels survive serialization instead of being coerced away by the discriminated union.
    - `export_format` string — Export format identifier
    - `source_tool_id` string, nullable — Original tool _id
    - `source_tool_name` string, nullable — Original tool name
    - `tool_type` string, nullable — ToolType of the exported tool (discriminator)
    - `tool_config` object, required — Sanitized ToolConfig as a dict (identity fields stripped, secrets redacted)
    - `redactions` ToolRedaction[] — Fields whose values were replaced with the '<REDACTED>' sentinel
      - `path` string, required — Dotted path to the redacted field, e.g. 'api_headers.Authorization'
      - `reason` string, required — Why it was redacted, e.g. 'sensitive header'
    - `exported_at` string, date-time — Timestamp of export
    - `warnings` string[] — Non-fatal notes (team-scoped refs cleared, env-specific endpoint, raw api_body, etc.)
  - `name_override` string, nullable — Override for the imported tool's name
  - `secret_overrides` object — Dotted-path -> value for each redacted field being re-supplied, e.g. {'api_headers.Authorization': 'Bearer ...'}
  - `clear_unresolved_refs` boolean — Clear team-scoped refs (KB ids) that cannot resolve in the importing team
  - `confirm_executable` boolean — Required True to import an inline_python tool (executable code)

## 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.
        - `timeout_seconds` integer, nullable — Wall-clock ceiling in seconds for one invocation of this tool. Leave empty to use the platform default. Raise it for a tool that is legitimately slow (a large EHR sync, say) rather than letting it be cut off. Note: an inline-Python body that is CPU-bound with no await points cannot be interrupted - the timeout frees the conversation to continue, but the work carries on in the background.
        - `variable_arguments` ToolVariableArgument[] — Arguments supplied to this tool from the workflow's runtime/dynamic variables, resolved at invocation time and passed as native Python values. Use this instead of embedding [[variables]] in an inline tool's source code: the value keeps its type, and it is passed as an argument rather than spliced into the code.
          - `argument_name` string, required — The keyword argument name passed to the tool function.
          - `source` 'auto' | 'runtime' | 'dynamic' | 'literal' — Which namespace a variable-bound tool argument is read from.
          - `variable_path` string, nullable — Path to the value, e.g. 'patient_record', 'patient_record.dob', 'items[0].id', or a node-qualified key such as 'Collect Insurance.dob'. Required unless source is 'literal'.
          - `literal_value` unknown
          - `default` unknown
          - `required` boolean — When true, a missing variable fails the tool call with a named error instead of passing the default. Use for arguments the tool genuinely cannot run without.
          - `expose_to_llm` boolean — When false (the default) this argument is stripped from the args_schema the model sees, so the model is never asked for it and cannot supply it. Set true only when the model should be able to override the bound value.
          - `override_provided_value` boolean — When true the bound value replaces anything the caller (the model, or the node's tool_arguments) supplied under the same name. When false the bound value acts as a fallback used only if the caller omitted the argument.
        - `result_variable_mappings` ToolResultVariableMapping[] — Assigns parts of this tool's return value to named runtime variables, so a tool that returns a dict can populate several variables at once.
          - `target_variable_name` string, required — Runtime variable to write. Readable downstream as [[<name>]]. Must be a plain name: letters, digits and underscores, not starting with a digit or an underscore.
          - `result_path` string, nullable — Path into the returned value, e.g. 'score', 'patient.dob' or 'rows[0].id'. Leave empty to assign the whole return value.
          - `scope` 'thread' | 'workflow' — Which variable store a mapped tool result is written to.
          - `default` unknown
          - `required` boolean — When true, a missing result_path marks the tool call as failed and records the reason in <result_runtime_variable_name>_error, instead of writing the default.
        - `expand_result_into_runtime_variables` boolean — When true and the tool returns a dict, every top-level key is also written as a runtime variable of the same name. A convenience alternative to listing every mapping explicitly; explicit result_variable_mappings win on a name collision.
        - `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.
        - `timeout_seconds` integer, nullable — Wall-clock ceiling in seconds for one invocation of this tool. Leave empty to use the platform default. Raise it for a tool that is legitimately slow (a large EHR sync, say) rather than letting it be cut off. Note: an inline-Python body that is CPU-bound with no await points cannot be interrupted - the timeout frees the conversation to continue, but the work carries on in the background.
        - `variable_arguments` ToolVariableArgument[] — Arguments supplied to this tool from the workflow's runtime/dynamic variables, resolved at invocation time and passed as native Python values. Use this instead of embedding [[variables]] in an inline tool's source code: the value keeps its type, and it is passed as an argument rather than spliced into the code.
          - `argument_name` string, required — The keyword argument name passed to the tool function.
          - `source` 'auto' | 'runtime' | 'dynamic' | 'literal' — Which namespace a variable-bound tool argument is read from.
          - `variable_path` string, nullable — Path to the value, e.g. 'patient_record', 'patient_record.dob', 'items[0].id', or a node-qualified key such as 'Collect Insurance.dob'. Required unless source is 'literal'.
          - `literal_value` unknown
          - `default` unknown
          - `required` boolean — When true, a missing variable fails the tool call with a named error instead of passing the default. Use for arguments the tool genuinely cannot run without.
          - `expose_to_llm` boolean — When false (the default) this argument is stripped from the args_schema the model sees, so the model is never asked for it and cannot supply it. Set true only when the model should be able to override the bound value.
          - `override_provided_value` boolean — When true the bound value replaces anything the caller (the model, or the node's tool_arguments) supplied under the same name. When false the bound value acts as a fallback used only if the caller omitted the argument.
        - `result_variable_mappings` ToolResultVariableMapping[] — Assigns parts of this tool's return value to named runtime variables, so a tool that returns a dict can populate several variables at once.
          - `target_variable_name` string, required — Runtime variable to write. Readable downstream as [[<name>]]. Must be a plain name: letters, digits and underscores, not starting with a digit or an underscore.
          - `result_path` string, nullable — Path into the returned value, e.g. 'score', 'patient.dob' or 'rows[0].id'. Leave empty to assign the whole return value.
          - `scope` 'thread' | 'workflow' — Which variable store a mapped tool result is written to.
          - `default` unknown
          - `required` boolean — When true, a missing result_path marks the tool call as failed and records the reason in <result_runtime_variable_name>_error, instead of writing the default.
        - `expand_result_into_runtime_variables` boolean — When true and the tool returns a dict, every top-level key is also written as a runtime variable of the same name. A convenience alternative to listing every mapping explicitly; explicit result_variable_mappings win on a name collision.
        - `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.
        - `timeout_seconds` integer, nullable — Wall-clock ceiling in seconds for one invocation of this tool. Leave empty to use the platform default. Raise it for a tool that is legitimately slow (a large EHR sync, say) rather than letting it be cut off. Note: an inline-Python body that is CPU-bound with no await points cannot be interrupted - the timeout frees the conversation to continue, but the work carries on in the background.
        - `variable_arguments` ToolVariableArgument[] — Arguments supplied to this tool from the workflow's runtime/dynamic variables, resolved at invocation time and passed as native Python values. Use this instead of embedding [[variables]] in an inline tool's source code: the value keeps its type, and it is passed as an argument rather than spliced into the code.
          - `argument_name` string, required — The keyword argument name passed to the tool function.
          - `source` 'auto' | 'runtime' | 'dynamic' | 'literal' — Which namespace a variable-bound tool argument is read from.
          - `variable_path` string, nullable — Path to the value, e.g. 'patient_record', 'patient_record.dob', 'items[0].id', or a node-qualified key such as 'Collect Insurance.dob'. Required unless source is 'literal'.
          - `literal_value` unknown
          - `default` unknown
          - `required` boolean — When true, a missing variable fails the tool call with a named error instead of passing the default. Use for arguments the tool genuinely cannot run without.
          - `expose_to_llm` boolean — When false (the default) this argument is stripped from the args_schema the model sees, so the model is never asked for it and cannot supply it. Set true only when the model should be able to override the bound value.
          - `override_provided_value` boolean — When true the bound value replaces anything the caller (the model, or the node's tool_arguments) supplied under the same name. When false the bound value acts as a fallback used only if the caller omitted the argument.
        - `result_variable_mappings` ToolResultVariableMapping[] — Assigns parts of this tool's return value to named runtime variables, so a tool that returns a dict can populate several variables at once.
          - `target_variable_name` string, required — Runtime variable to write. Readable downstream as [[<name>]]. Must be a plain name: letters, digits and underscores, not starting with a digit or an underscore.
          - `result_path` string, nullable — Path into the returned value, e.g. 'score', 'patient.dob' or 'rows[0].id'. Leave empty to assign the whole return value.
          - `scope` 'thread' | 'workflow' — Which variable store a mapped tool result is written to.
          - `default` unknown
          - `required` boolean — When true, a missing result_path marks the tool call as failed and records the reason in <result_runtime_variable_name>_error, instead of writing the default.
        - `expand_result_into_runtime_variables` boolean — When true and the tool returns a dict, every top-level key is also written as a runtime variable of the same name. A convenience alternative to listing every mapping explicitly; explicit result_variable_mappings win on a name collision.
        - `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
        - `integration_auth` IntegrationAuthConfig — Configuration for integration-backed bearer-token authentication. Provider-agnostic: any integration that exposes an OAuth2 client-credentials token endpoint (Okta, Athena, ECW, ...) can be referenced here. The runtime only needs the integration ID – the integrations service resolves the provider and returns the bearer token.
          - `integration_id` string, nullable — ID of an integration to use for bearer-token authentication. When set, the runtime fetches a cached OAuth token from this integration and injects it as the Authorization header. Ignored when api_key or an Authorization default_header is already provided.
      - 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.
        - `timeout_seconds` integer, nullable — Wall-clock ceiling in seconds for one invocation of this tool. Leave empty to use the platform default. Raise it for a tool that is legitimately slow (a large EHR sync, say) rather than letting it be cut off. Note: an inline-Python body that is CPU-bound with no await points cannot be interrupted - the timeout frees the conversation to continue, but the work carries on in the background.
        - `variable_arguments` ToolVariableArgument[] — Arguments supplied to this tool from the workflow's runtime/dynamic variables, resolved at invocation time and passed as native Python values. Use this instead of embedding [[variables]] in an inline tool's source code: the value keeps its type, and it is passed as an argument rather than spliced into the code.
          - `argument_name` string, required — The keyword argument name passed to the tool function.
          - `source` 'auto' | 'runtime' | 'dynamic' | 'literal' — Which namespace a variable-bound tool argument is read from.
          - `variable_path` string, nullable — Path to the value, e.g. 'patient_record', 'patient_record.dob', 'items[0].id', or a node-qualified key such as 'Collect Insurance.dob'. Required unless source is 'literal'.
          - `literal_value` unknown
          - `default` unknown
          - `required` boolean — When true, a missing variable fails the tool call with a named error instead of passing the default. Use for arguments the tool genuinely cannot run without.
          - `expose_to_llm` boolean — When false (the default) this argument is stripped from the args_schema the model sees, so the model is never asked for it and cannot supply it. Set true only when the model should be able to override the bound value.
          - `override_provided_value` boolean — When true the bound value replaces anything the caller (the model, or the node's tool_arguments) supplied under the same name. When false the bound value acts as a fallback used only if the caller omitted the argument.
        - `result_variable_mappings` ToolResultVariableMapping[] — Assigns parts of this tool's return value to named runtime variables, so a tool that returns a dict can populate several variables at once.
          - `target_variable_name` string, required — Runtime variable to write. Readable downstream as [[<name>]]. Must be a plain name: letters, digits and underscores, not starting with a digit or an underscore.
          - `result_path` string, nullable — Path into the returned value, e.g. 'score', 'patient.dob' or 'rows[0].id'. Leave empty to assign the whole return value.
          - `scope` 'thread' | 'workflow' — Which variable store a mapped tool result is written to.
          - `default` unknown
          - `required` boolean — When true, a missing result_path marks the tool call as failed and records the reason in <result_runtime_variable_name>_error, instead of writing the default.
        - `expand_result_into_runtime_variables` boolean — When true and the tool returns a dict, every top-level key is also written as a runtime variable of the same name. A convenience alternative to listing every mapping explicitly; explicit result_variable_mappings win on a name collision.
        - `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-08-19** `68e88496bf11` — 17 info
  - added the optional property `tool/tool_config/anyOf[subschema #1]/oneOf[subschema #1: Inline Python Tool]/expand_result_into_runtime_variables` to the response with the `200` status
  - added the optional property `tool/tool_config/anyOf[subschema #1]/oneOf[subschema #1: Inline Python Tool]/result_variable_mappings` to the response with the `200` status
  - added the optional property `tool/tool_config/anyOf[subschema #1]/oneOf[subschema #1: Inline Python Tool]/timeout_seconds` to the response with the `200` status
  - added the optional property `tool/tool_config/anyOf[subschema #1]/oneOf[subschema #1: Inline Python Tool]/variable_arguments` to the response with the `200` status
  - …13 more
- **2026-07-21** `d276be705570` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/interactly/apis/interactly-api-3/changes/workflows/v1/tools/import/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/68e88496bf11/schema)