Agent tools¶

Use an API key or REST OAuth access token. Scopes and your current workspace permissions apply together. All examples are illustrative.

Read tool types and fields¶

GET /api/external/v1/tool-catalog

Scope: tools:read

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`

application/json

FieldsExample

Object with free keys. Value type: object.

[]

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

List existing credential references¶

GET /api/external/v1/tool-catalog/credentials

Scope: tools:read

Returns existing IDs and names, never secrets. Requires permission to read credentials.

Parameters

Name	Location	Type	Required	Description
`page`	Query	`integer` (int32)	No	Page index, starting at 0. Rules: `0–100000` Default: `0`
`size`	Query	`integer` (int32)	No	Results per page. Rules: `1–100` Default: `25`

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`

application/json

FieldsExample

Field	Type	Description
`items`	List of `object`	Results on this page.
`page`	`integer` (int32)	Current page index, starting at 0.
`size`	`integer` (int32)	Number of results requested per page.
`totalElements`	`integer` (int64)	Total number of matching results.
`totalPages`	`integer` (int32)	Total number of result pages.

items — fields

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`name`	`string`	Display name.

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "name": "NuvoCar"
    }
  ],
  "page": 0,
  "size": 25,
  "totalElements": 1,
  "totalPages": 1
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

List approved external MCP tools¶

GET /api/external/v1/tool-catalog/mcp-tools

Scope: tools:read

Parameters

Name	Location	Type	Required	Description
`page`	Query	`integer` (int32)	No	Page index, starting at 0. Rules: `0–100000` Default: `0`
`size`	Query	`integer` (int32)	No	Results per page. Rules: `1–100` Default: `25`

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`

application/json

FieldsExample

Field	Type	Description
`items`	List of `object`	Results on this page.
`page`	`integer` (int32)	Current page index, starting at 0.
`size`	`integer` (int32)	Number of results requested per page.
`totalElements`	`integer` (int64)	Total number of matching results.
`totalPages`	`integer` (int32)	Total number of result pages.

items — fields

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`name`	`string`	Display name.
`description`	`string`	Description of the approved external MCP tool.
`inputSchema`	`object`	JSON Schema describing the inputs accepted by the tool. Each value: `object`

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "name": "NuvoCar",
      "description": "string",
      "inputSchema": {}
    }
  ],
  "page": 0,
  "size": 25,
  "totalElements": 1,
  "totalPages": 1
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

List existing OAuth references¶

GET /api/external/v1/tool-catalog/oauth-configurations

Scope: tools:read

Returns existing IDs and names, never secrets. Requires permission to read credentials.

Parameters

Name	Location	Type	Required	Description
`page`	Query	`integer` (int32)	No	Page index, starting at 0. Rules: `0–100000` Default: `0`
`size`	Query	`integer` (int32)	No	Results per page. Rules: `1–100` Default: `25`

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`

application/json

FieldsExample

Field	Type	Description
`items`	List of `object`	Results on this page.
`page`	`integer` (int32)	Current page index, starting at 0.
`size`	`integer` (int32)	Number of results requested per page.
`totalElements`	`integer` (int64)	Total number of matching results.
`totalPages`	`integer` (int32)	Total number of result pages.

items — fields

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`name`	`string`	Display name.

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "name": "NuvoCar"
    }
  ],
  "page": 0,
  "size": 25,
  "totalElements": 1,
  "totalPages": 1
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Create Agent tool¶

POST /api/external/v1/agents/{agentId}/tools

Scope: tools:write

Saves configuration directly; no call, tool test or message delivery is executed. Use the tool catalog to select fields for toolType. Credential references also require permission to read credentials.

Parameters

Name	Location	Type	Required	Description
`agentId`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.

Request body · application/json

FieldsExample

Use exactly one of these variants:

MCP_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `MCP_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`mcpToolId`	`string` (uuid)	Yes	ID of an approved external MCP tool from the tool catalog. Rules: up to 100000 characters
`callerMessageEnabled`	`boolean`	No	Announce the tool action to the caller.

DIRECT_FORWARDING_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `DIRECT_FORWARDING_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`displayName`	`string`	Yes	Name shown for this tool. Rules: up to 255 characters
`executionDescription`	`string`	Yes	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters
`allowDynamicRecipient`	`boolean`	No	Allow the Agent to choose a forwarding destination dynamically.
`forwardingInformation`	`object`	No	Forwarding destinations, keyed by destination name. Rules: up to 100 keys Each value: `string`; up to 4000 characters

CONFERENCE_FORWARDING_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `CONFERENCE_FORWARDING_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`displayName`	`string`	Yes	Name shown for this tool. Rules: up to 255 characters
`executionDescription`	`string`	Yes	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters
`allowDynamicRecipient`	`boolean`	No	Allow the Agent to choose a forwarding destination dynamically.
`forwardingInformation`	`object`	No	Forwarding destinations, keyed by destination name. Rules: up to 100 keys Each value: `string`; up to 4000 characters
`forwardingTimeout`	`integer`	No	Time to wait for the forwarding destination, in seconds. Rules: `5–120`
`screeningEnabled`	`boolean`	No	Enable recipient screening during conference forwarding.
`machineDetectionEnabled`	`boolean`	No	Enable answering-machine detection during conference forwarding.
`screeningSummaryPrompt`	`string`	No	Instructions for the conversation summary presented during recipient screening. Rules: up to 100000 characters
`announcementPrompt`	`string`	No	Instructions for the announcement used during forwarding. Rules: up to 100000 characters

EMAIL_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `EMAIL_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`displayName`	`string`	Yes	Name shown for this tool. Rules: up to 255 characters
`executionDescription`	`string`	Yes	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters
`email_to`	List of `string`	No	Configured email recipient addresses. Rules: up to 100 entries Each entry: up to 320 characters
`allow_ai_to_recipients`	`boolean`	No	Allow the Agent to supply email recipient addresses.
`email_cc`	List of `string`	No	CC recipient addresses. Rules: up to 100 entries Each entry: up to 320 characters
`email_prompt`	`string`	Yes	Instructions for writing the email body. Rules: up to 100000 characters
`email_subject`	`string`	Yes	Subject of the email. Rules: up to 100000 characters
`include_facts`	`boolean`	No	Include collected conversation facts when generating the email.
`include_conversation_history`	`boolean`	No	Include the conversation history when generating the email.

SMS_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `SMS_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`displayName`	`string`	Yes	Name shown for this tool. Rules: up to 255 characters
`executionDescription`	`string`	Yes	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters
`sender_id`	`string`	Yes	Sender identifier for outgoing SMS messages. Rules: up to 100000 characters
`body_mode`	`string`	Yes	How the SMS message text is created. Rules: up to 100000 characters Values: `AGENT_PROVIDED`, `STATIC`, `TEMPLATE`
`static_body`	`string`	No	Fixed SMS message text used in STATIC mode. Rules: up to 100000 characters
`body_template`	`string`	No	Template for the SMS message text. Rules: up to 100000 characters

WEB_SEARCH_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `WEB_SEARCH_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`displayName`	`string`	Yes	Name shown for this tool. Rules: up to 255 characters
`executionDescription`	`string`	Yes	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters
`searchContext`	`string`	No	Context that helps the Agent formulate the web search. Rules: up to 100000 characters
`allowedDomains`	`string`	No	Domain filter for web search. Rules: up to 100000 characters
`searchLanguage`	`string`	Yes	Language used for web search. Rules: up to 100000 characters Values: `de`, `en`, `es`, `fr`, `nl`
`country`	`string`	Yes	Country used to localize web-search results. Rules: up to 100000 characters Show all 11 allowed values `AT`, `AU`, `BE`, `CA`, `CH`, `DE`, `ES`, `FR`, `GB`, `NL`, `US`
`callerMessageEnabled`	`boolean`	No	Announce the tool action to the caller.
`maximumTokens`	`integer`	Yes	Token budget for web-search results. Rules: `0–30000`
`maximumSources`	`integer`	Yes	Maximum number of sources used for web-search results. Rules: `0–30000`
`timeoutMs`	`integer`	Yes	Time limit for the outgoing request, in milliseconds. Rules: `0–30000`

API_REQUEST_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `API_REQUEST_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`displayName`	`string`	Yes	Name shown for this tool. Rules: up to 255 characters
`executionDescription`	`string`	Yes	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters
`httpMethod`	`string`	Yes	HTTP method used by the API tool. Rules: up to 100000 characters Values: `GET`, `POST`, `PUT`, `DELETE`
`targetUrl`	`string`	Yes	Destination URL used by the API tool. Rules: up to 100000 characters
`headers`	List of `object`	No	HTTP request headers. Stored secret values are hidden.
`oauthConfigId`	`string` (uuid)	No	ID of an existing OAuth connection the current user may read. Rules: up to 100000 characters
`contentType`	`string`	No	Content-Type of the outgoing request body. Rules: up to 100000 characters Values: `application/json`, `application/x-www-form-urlencoded`, `text/plain`
`defaultBody`	`string`	No	Request body used as the tool's starting value. Rules: up to 100000 characters
`inputSchema`	`string`	No	JSON Schema for inputs supplied by the Agent, encoded as a string. Rules: up to 100000 characters
`responseProcessingMode`	`string`	No	How the API tool processes the response. Rules: up to 100000 characters Values: `ORIGINAL`, `PATHS`, `SCRIPT`
`responseScript`	`string`	No	Script for transforming the external response. Rules: up to 100000 characters
`responseMappings`	`object`	No	Map response values to named output fields. Rules: up to 100 keys Each value: `string`; up to 4000 characters
`callerMessageEnabled`	`boolean`	No	Announce the tool action to the caller.
`timeoutMs`	`integer`	No	Time limit for the outgoing request, in milliseconds. Rules: `0–30000`
`runAsync`	`boolean`	No	Run the API tool action asynchronously.

headers — fields

Field	Type	Required	Description
`name`	`string`	Yes	HTTP header name, such as Authorization. Rules: up to 200 characters
`value`	`string`	No	New header value. Omit it to keep the stored value at an unchanged target. Rules: up to 8192 characters; write-only
`configured`	`boolean`	No	A value is stored. Send true without value to keep it at an unchanged target.
`credentialId`	`string` (uuid)	No	ID of an existing credential the current user may read.
`prefix`	`string`	No	Prefix placed before a credential value, including spaces. Use Bearer followed by a space for Bearer authentication. Rules: up to 100 characters

{
  "toolType": "API_REQUEST_TOOL",
  "configuration": {
    "displayName": "Service lookup",
    "executionDescription": "Look up a service request when the caller provides its reference.",
    "httpMethod": "GET",
    "targetUrl": "https://service.example.com/status",
    "headers": [],
    "callerMessageEnabled": false,
    "timeoutMs": 5000
  }
}

Response 201

Created.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`
`Location`	`string`	Path of the created resource.
`ETag`	`string`	Current revision. Send unchanged, including quotes, as If-Match when required. Example: `"revision-from-get"`

application/json

FieldsExample

The response matches its toolType:

MCP_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `MCP_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`mcpToolId`	`string` (uuid)	ID of an approved external MCP tool from the tool catalog. Rules: up to 100000 characters; `null` allowed
`callerMessageEnabled`	`boolean`	Announce the tool action to the caller. Rules: `null` allowed

DIRECT_FORWARDING_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `DIRECT_FORWARDING_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`allowDynamicRecipient`	`boolean`	Allow the Agent to choose a forwarding destination dynamically. Rules: `null` allowed
`forwardingInformation`	`object`	Forwarding destinations, keyed by destination name. Rules: up to 100 keys; `null` allowed Each value: `string`; up to 4000 characters

CONFERENCE_FORWARDING_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `CONFERENCE_FORWARDING_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`allowDynamicRecipient`	`boolean`	Allow the Agent to choose a forwarding destination dynamically. Rules: `null` allowed
`forwardingInformation`	`object`	Forwarding destinations, keyed by destination name. Rules: up to 100 keys; `null` allowed Each value: `string`; up to 4000 characters
`forwardingTimeout`	`integer`	Time to wait for the forwarding destination, in seconds. Rules: `5–120`; `null` allowed
`screeningEnabled`	`boolean`	Enable recipient screening during conference forwarding. Rules: `null` allowed
`machineDetectionEnabled`	`boolean`	Enable answering-machine detection during conference forwarding. Rules: `null` allowed
`screeningSummaryPrompt`	`string`	Instructions for the conversation summary presented during recipient screening. Rules: up to 100000 characters; `null` allowed
`announcementPrompt`	`string`	Instructions for the announcement used during forwarding. Rules: up to 100000 characters; `null` allowed

EMAIL_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `EMAIL_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`email_to`	List of `string`	Configured email recipient addresses. Rules: up to 100 entries; `null` allowed Each entry: up to 320 characters
`allow_ai_to_recipients`	`boolean`	Allow the Agent to supply email recipient addresses. Rules: `null` allowed
`email_cc`	List of `string`	CC recipient addresses. Rules: up to 100 entries; `null` allowed Each entry: up to 320 characters
`email_prompt`	`string`	Instructions for writing the email body. Rules: up to 100000 characters; `null` allowed
`email_subject`	`string`	Subject of the email. Rules: up to 100000 characters; `null` allowed
`include_facts`	`boolean`	Include collected conversation facts when generating the email. Rules: `null` allowed
`include_conversation_history`	`boolean`	Include the conversation history when generating the email. Rules: `null` allowed

SMS_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `SMS_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`sender_id`	`string`	Sender identifier for outgoing SMS messages. Rules: up to 100000 characters; `null` allowed
`body_mode`	`string`	How the SMS message text is created. Rules: up to 100000 characters; `null` allowed Values: `AGENT_PROVIDED`, `STATIC`, `TEMPLATE`
`static_body`	`string`	Fixed SMS message text used in STATIC mode. Rules: up to 100000 characters; `null` allowed
`body_template`	`string`	Template for the SMS message text. Rules: up to 100000 characters; `null` allowed

WEB_SEARCH_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `WEB_SEARCH_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`searchContext`	`string`	Context that helps the Agent formulate the web search. Rules: up to 100000 characters; `null` allowed
`allowedDomains`	`string`	Domain filter for web search. Rules: up to 100000 characters; `null` allowed
`searchLanguage`	`string`	Language used for web search. Rules: up to 100000 characters; `null` allowed Values: `de`, `en`, `es`, `fr`, `nl`
`country`	`string`	Country used to localize web-search results. Rules: up to 100000 characters; `null` allowed Show all 11 allowed values `AT`, `AU`, `BE`, `CA`, `CH`, `DE`, `ES`, `FR`, `GB`, `NL`, `US`
`callerMessageEnabled`	`boolean`	Announce the tool action to the caller. Rules: `null` allowed
`maximumTokens`	`integer`	Token budget for web-search results. Rules: `0–30000`; `null` allowed
`maximumSources`	`integer`	Maximum number of sources used for web-search results. Rules: `0–30000`; `null` allowed
`timeoutMs`	`integer`	Time limit for the outgoing request, in milliseconds. Rules: `0–30000`; `null` allowed

API_REQUEST_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `API_REQUEST_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`httpMethod`	`string`	HTTP method used by the API tool. Rules: up to 100000 characters; `null` allowed Values: `GET`, `POST`, `PUT`, `DELETE`
`targetUrl`	`string`	Destination URL used by the API tool. Rules: up to 100000 characters
`headers`	List of `object`	HTTP request headers. Stored secret values are hidden.
`oauthConfigId`	`string` (uuid)	ID of an existing OAuth connection the current user may read. Rules: up to 100000 characters; `null` allowed
`contentType`	`string`	Content-Type of the outgoing request body. Rules: up to 100000 characters; `null` allowed Values: `application/json`, `application/x-www-form-urlencoded`, `text/plain`
`defaultBody`	`string`	Request body used as the tool's starting value. Rules: up to 100000 characters; `null` allowed
`inputSchema`	`string`	JSON Schema for inputs supplied by the Agent, encoded as a string. Rules: up to 100000 characters; `null` allowed
`responseProcessingMode`	`string`	How the API tool processes the response. Rules: up to 100000 characters; `null` allowed Values: `ORIGINAL`, `PATHS`, `SCRIPT`
`responseScript`	`string`	Script for transforming the external response. Rules: up to 100000 characters; `null` allowed
`responseMappings`	`object`	Map response values to named output fields. Rules: up to 100 keys; `null` allowed Each value: `string`; up to 4000 characters
`callerMessageEnabled`	`boolean`	Announce the tool action to the caller. Rules: `null` allowed
`timeoutMs`	`integer`	Time limit for the outgoing request, in milliseconds. Rules: `0–30000`; `null` allowed
`runAsync`	`boolean`	Run the API tool action asynchronously. Rules: `null` allowed

headers — fields

Field	Type	Description
`name`	`string`	HTTP header name, such as Authorization. Rules: up to 200 characters
`configured`	`boolean`	A value is stored. Send true without value to keep it at an unchanged target.
`credentialId`	`string` (uuid)	ID of an existing credential the current user may read.
`prefix`	`string`	Prefix placed before a credential value, including spaces. Use Bearer followed by a space for Bearer authentication. Rules: up to 100 characters

{
  "id": "00000000-0000-0000-0000-000000000001",
  "revision": "revision-from-get",
  "toolType": "MCP_TOOL",
  "configuration": {
    "mcpToolId": "00000000-0000-0000-0000-000000000001",
    "callerMessageEnabled": false
  }
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`409`	Missing/stale revision or dependency/routing conflict. Read again before retrying.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

List Agent tools¶

GET /api/external/v1/agents/{agentId}/tools

Scope: tools:read

Parameters

Name	Location	Type	Required	Description
`agentId`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`page`	Query	`integer` (int32)	No	Page index, starting at 0. Rules: `0–100000` Default: `0`
`size`	Query	`integer` (int32)	No	Results per page. Rules: `1–100` Default: `25`

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`

application/json

FieldsExample

Field	Type	Description
`items`	List of `object`	Results on this page.
`page`	`integer` (int32)	Current page index, starting at 0.
`size`	`integer` (int32)	Number of results requested per page.
`totalElements`	`integer` (int64)	Total number of matching results.
`totalPages`	`integer` (int32)	Total number of result pages.

items — fields

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Show all 7 allowed values `MCP_TOOL`, `DIRECT_FORWARDING_TOOL`, `CONFERENCE_FORWARDING_TOOL`, `EMAIL_TOOL`, `SMS_TOOL`, `WEB_SEARCH_TOOL`, `API_REQUEST_TOOL`
`name`	`string`	Display name.

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "revision": "revision-from-get",
      "toolType": "MCP_TOOL",
      "name": "NuvoCar"
    }
  ],
  "page": 0,
  "size": 25,
  "totalElements": 1,
  "totalPages": 1
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Delete Agent tool¶

DELETE /api/external/v1/agents/{agentId}/tools/{id}

Scope: tools:write

Read the resource first. Send its current ETag, including quotes, in If-Match.

Parameters

Name	Location	Type	Required	Description
`agentId`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`If-Match`	Header	`string`	Yes	ETag from the preceding read, including quotes. Example: `"revision-from-get"`

Response 204

Deleted; no response body.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`409`	Missing/stale revision or dependency/routing conflict. Read again before retrying.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Read Agent tool¶

GET /api/external/v1/agents/{agentId}/tools/{id}

Scope: tools:read

Parameters

Name	Location	Type	Required	Description
`agentId`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`
`ETag`	`string`	Current revision. Send unchanged, including quotes, as If-Match when required. Example: `"revision-from-get"`

application/json

FieldsExample

The response matches its toolType:

MCP_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `MCP_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`mcpToolId`	`string` (uuid)	ID of an approved external MCP tool from the tool catalog. Rules: up to 100000 characters; `null` allowed
`callerMessageEnabled`	`boolean`	Announce the tool action to the caller. Rules: `null` allowed

DIRECT_FORWARDING_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `DIRECT_FORWARDING_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`allowDynamicRecipient`	`boolean`	Allow the Agent to choose a forwarding destination dynamically. Rules: `null` allowed
`forwardingInformation`	`object`	Forwarding destinations, keyed by destination name. Rules: up to 100 keys; `null` allowed Each value: `string`; up to 4000 characters

CONFERENCE_FORWARDING_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `CONFERENCE_FORWARDING_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`allowDynamicRecipient`	`boolean`	Allow the Agent to choose a forwarding destination dynamically. Rules: `null` allowed
`forwardingInformation`	`object`	Forwarding destinations, keyed by destination name. Rules: up to 100 keys; `null` allowed Each value: `string`; up to 4000 characters
`forwardingTimeout`	`integer`	Time to wait for the forwarding destination, in seconds. Rules: `5–120`; `null` allowed
`screeningEnabled`	`boolean`	Enable recipient screening during conference forwarding. Rules: `null` allowed
`machineDetectionEnabled`	`boolean`	Enable answering-machine detection during conference forwarding. Rules: `null` allowed
`screeningSummaryPrompt`	`string`	Instructions for the conversation summary presented during recipient screening. Rules: up to 100000 characters; `null` allowed
`announcementPrompt`	`string`	Instructions for the announcement used during forwarding. Rules: up to 100000 characters; `null` allowed

EMAIL_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `EMAIL_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`email_to`	List of `string`	Configured email recipient addresses. Rules: up to 100 entries; `null` allowed Each entry: up to 320 characters
`allow_ai_to_recipients`	`boolean`	Allow the Agent to supply email recipient addresses. Rules: `null` allowed
`email_cc`	List of `string`	CC recipient addresses. Rules: up to 100 entries; `null` allowed Each entry: up to 320 characters
`email_prompt`	`string`	Instructions for writing the email body. Rules: up to 100000 characters; `null` allowed
`email_subject`	`string`	Subject of the email. Rules: up to 100000 characters; `null` allowed
`include_facts`	`boolean`	Include collected conversation facts when generating the email. Rules: `null` allowed
`include_conversation_history`	`boolean`	Include the conversation history when generating the email. Rules: `null` allowed

SMS_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `SMS_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`sender_id`	`string`	Sender identifier for outgoing SMS messages. Rules: up to 100000 characters; `null` allowed
`body_mode`	`string`	How the SMS message text is created. Rules: up to 100000 characters; `null` allowed Values: `AGENT_PROVIDED`, `STATIC`, `TEMPLATE`
`static_body`	`string`	Fixed SMS message text used in STATIC mode. Rules: up to 100000 characters; `null` allowed
`body_template`	`string`	Template for the SMS message text. Rules: up to 100000 characters; `null` allowed

WEB_SEARCH_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `WEB_SEARCH_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`searchContext`	`string`	Context that helps the Agent formulate the web search. Rules: up to 100000 characters; `null` allowed
`allowedDomains`	`string`	Domain filter for web search. Rules: up to 100000 characters; `null` allowed
`searchLanguage`	`string`	Language used for web search. Rules: up to 100000 characters; `null` allowed Values: `de`, `en`, `es`, `fr`, `nl`
`country`	`string`	Country used to localize web-search results. Rules: up to 100000 characters; `null` allowed Show all 11 allowed values `AT`, `AU`, `BE`, `CA`, `CH`, `DE`, `ES`, `FR`, `GB`, `NL`, `US`
`callerMessageEnabled`	`boolean`	Announce the tool action to the caller. Rules: `null` allowed
`maximumTokens`	`integer`	Token budget for web-search results. Rules: `0–30000`; `null` allowed
`maximumSources`	`integer`	Maximum number of sources used for web-search results. Rules: `0–30000`; `null` allowed
`timeoutMs`	`integer`	Time limit for the outgoing request, in milliseconds. Rules: `0–30000`; `null` allowed

API_REQUEST_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `API_REQUEST_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`httpMethod`	`string`	HTTP method used by the API tool. Rules: up to 100000 characters; `null` allowed Values: `GET`, `POST`, `PUT`, `DELETE`
`targetUrl`	`string`	Destination URL used by the API tool. Rules: up to 100000 characters
`headers`	List of `object`	HTTP request headers. Stored secret values are hidden.
`oauthConfigId`	`string` (uuid)	ID of an existing OAuth connection the current user may read. Rules: up to 100000 characters; `null` allowed
`contentType`	`string`	Content-Type of the outgoing request body. Rules: up to 100000 characters; `null` allowed Values: `application/json`, `application/x-www-form-urlencoded`, `text/plain`
`defaultBody`	`string`	Request body used as the tool's starting value. Rules: up to 100000 characters; `null` allowed
`inputSchema`	`string`	JSON Schema for inputs supplied by the Agent, encoded as a string. Rules: up to 100000 characters; `null` allowed
`responseProcessingMode`	`string`	How the API tool processes the response. Rules: up to 100000 characters; `null` allowed Values: `ORIGINAL`, `PATHS`, `SCRIPT`
`responseScript`	`string`	Script for transforming the external response. Rules: up to 100000 characters; `null` allowed
`responseMappings`	`object`	Map response values to named output fields. Rules: up to 100 keys; `null` allowed Each value: `string`; up to 4000 characters
`callerMessageEnabled`	`boolean`	Announce the tool action to the caller. Rules: `null` allowed
`timeoutMs`	`integer`	Time limit for the outgoing request, in milliseconds. Rules: `0–30000`; `null` allowed
`runAsync`	`boolean`	Run the API tool action asynchronously. Rules: `null` allowed

headers — fields

Field	Type	Description
`name`	`string`	HTTP header name, such as Authorization. Rules: up to 200 characters
`configured`	`boolean`	A value is stored. Send true without value to keep it at an unchanged target.
`credentialId`	`string` (uuid)	ID of an existing credential the current user may read.
`prefix`	`string`	Prefix placed before a credential value, including spaces. Use Bearer followed by a space for Bearer authentication. Rules: up to 100 characters

{
  "id": "00000000-0000-0000-0000-000000000001",
  "revision": "revision-from-get",
  "toolType": "MCP_TOOL",
  "configuration": {
    "mcpToolId": "00000000-0000-0000-0000-000000000001",
    "callerMessageEnabled": false
  }
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Update Agent tool¶

PUT /api/external/v1/agents/{agentId}/tools/{id}

Scope: tools:write

Saves configuration directly; no call, tool test or message delivery is executed. Read the resource first. Send its current ETag, including quotes, in If-Match. Send the full editable configuration. Omitted settings can be reset. Use the tool catalog to select fields for toolType. Credential references also require permission to read credentials.

Parameters

Name	Location	Type	Required	Description
`agentId`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`If-Match`	Header	`string`	Yes	ETag from the preceding read, including quotes. Example: `"revision-from-get"`

Request body · application/json

FieldsExample

Use exactly one of these variants:

MCP_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `MCP_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`mcpToolId`	`string` (uuid)	Yes	ID of an approved external MCP tool from the tool catalog. Rules: up to 100000 characters
`callerMessageEnabled`	`boolean`	No	Announce the tool action to the caller.

DIRECT_FORWARDING_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `DIRECT_FORWARDING_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`displayName`	`string`	Yes	Name shown for this tool. Rules: up to 255 characters
`executionDescription`	`string`	Yes	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters
`allowDynamicRecipient`	`boolean`	No	Allow the Agent to choose a forwarding destination dynamically.
`forwardingInformation`	`object`	No	Forwarding destinations, keyed by destination name. Rules: up to 100 keys Each value: `string`; up to 4000 characters

CONFERENCE_FORWARDING_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `CONFERENCE_FORWARDING_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`displayName`	`string`	Yes	Name shown for this tool. Rules: up to 255 characters
`executionDescription`	`string`	Yes	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters
`allowDynamicRecipient`	`boolean`	No	Allow the Agent to choose a forwarding destination dynamically.
`forwardingInformation`	`object`	No	Forwarding destinations, keyed by destination name. Rules: up to 100 keys Each value: `string`; up to 4000 characters
`forwardingTimeout`	`integer`	No	Time to wait for the forwarding destination, in seconds. Rules: `5–120`
`screeningEnabled`	`boolean`	No	Enable recipient screening during conference forwarding.
`machineDetectionEnabled`	`boolean`	No	Enable answering-machine detection during conference forwarding.
`screeningSummaryPrompt`	`string`	No	Instructions for the conversation summary presented during recipient screening. Rules: up to 100000 characters
`announcementPrompt`	`string`	No	Instructions for the announcement used during forwarding. Rules: up to 100000 characters

EMAIL_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `EMAIL_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`displayName`	`string`	Yes	Name shown for this tool. Rules: up to 255 characters
`executionDescription`	`string`	Yes	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters
`email_to`	List of `string`	No	Configured email recipient addresses. Rules: up to 100 entries Each entry: up to 320 characters
`allow_ai_to_recipients`	`boolean`	No	Allow the Agent to supply email recipient addresses.
`email_cc`	List of `string`	No	CC recipient addresses. Rules: up to 100 entries Each entry: up to 320 characters
`email_prompt`	`string`	Yes	Instructions for writing the email body. Rules: up to 100000 characters
`email_subject`	`string`	Yes	Subject of the email. Rules: up to 100000 characters
`include_facts`	`boolean`	No	Include collected conversation facts when generating the email.
`include_conversation_history`	`boolean`	No	Include the conversation history when generating the email.

SMS_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `SMS_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`displayName`	`string`	Yes	Name shown for this tool. Rules: up to 255 characters
`executionDescription`	`string`	Yes	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters
`sender_id`	`string`	Yes	Sender identifier for outgoing SMS messages. Rules: up to 100000 characters
`body_mode`	`string`	Yes	How the SMS message text is created. Rules: up to 100000 characters Values: `AGENT_PROVIDED`, `STATIC`, `TEMPLATE`
`static_body`	`string`	No	Fixed SMS message text used in STATIC mode. Rules: up to 100000 characters
`body_template`	`string`	No	Template for the SMS message text. Rules: up to 100000 characters

WEB_SEARCH_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `WEB_SEARCH_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`displayName`	`string`	Yes	Name shown for this tool. Rules: up to 255 characters
`executionDescription`	`string`	Yes	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters
`searchContext`	`string`	No	Context that helps the Agent formulate the web search. Rules: up to 100000 characters
`allowedDomains`	`string`	No	Domain filter for web search. Rules: up to 100000 characters
`searchLanguage`	`string`	Yes	Language used for web search. Rules: up to 100000 characters Values: `de`, `en`, `es`, `fr`, `nl`
`country`	`string`	Yes	Country used to localize web-search results. Rules: up to 100000 characters Show all 11 allowed values `AT`, `AU`, `BE`, `CA`, `CH`, `DE`, `ES`, `FR`, `GB`, `NL`, `US`
`callerMessageEnabled`	`boolean`	No	Announce the tool action to the caller.
`maximumTokens`	`integer`	Yes	Token budget for web-search results. Rules: `0–30000`
`maximumSources`	`integer`	Yes	Maximum number of sources used for web-search results. Rules: `0–30000`
`timeoutMs`	`integer`	Yes	Time limit for the outgoing request, in milliseconds. Rules: `0–30000`

API_REQUEST_TOOL

Field	Type	Required	Description
`toolType`	`string`	Yes	Tool type from the tool catalog. It cannot change after creation. Values: `API_REQUEST_TOOL`
`configuration`	`object`	Yes	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Required	Description
`displayName`	`string`	Yes	Name shown for this tool. Rules: up to 255 characters
`executionDescription`	`string`	Yes	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters
`httpMethod`	`string`	Yes	HTTP method used by the API tool. Rules: up to 100000 characters Values: `GET`, `POST`, `PUT`, `DELETE`
`targetUrl`	`string`	Yes	Destination URL used by the API tool. Rules: up to 100000 characters
`headers`	List of `object`	No	HTTP request headers. Stored secret values are hidden.
`oauthConfigId`	`string` (uuid)	No	ID of an existing OAuth connection the current user may read. Rules: up to 100000 characters
`contentType`	`string`	No	Content-Type of the outgoing request body. Rules: up to 100000 characters Values: `application/json`, `application/x-www-form-urlencoded`, `text/plain`
`defaultBody`	`string`	No	Request body used as the tool's starting value. Rules: up to 100000 characters
`inputSchema`	`string`	No	JSON Schema for inputs supplied by the Agent, encoded as a string. Rules: up to 100000 characters
`responseProcessingMode`	`string`	No	How the API tool processes the response. Rules: up to 100000 characters Values: `ORIGINAL`, `PATHS`, `SCRIPT`
`responseScript`	`string`	No	Script for transforming the external response. Rules: up to 100000 characters
`responseMappings`	`object`	No	Map response values to named output fields. Rules: up to 100 keys Each value: `string`; up to 4000 characters
`callerMessageEnabled`	`boolean`	No	Announce the tool action to the caller.
`timeoutMs`	`integer`	No	Time limit for the outgoing request, in milliseconds. Rules: `0–30000`
`runAsync`	`boolean`	No	Run the API tool action asynchronously.

headers — fields

Field	Type	Required	Description
`name`	`string`	Yes	HTTP header name, such as Authorization. Rules: up to 200 characters
`value`	`string`	No	New header value. Omit it to keep the stored value at an unchanged target. Rules: up to 8192 characters; write-only
`configured`	`boolean`	No	A value is stored. Send true without value to keep it at an unchanged target.
`credentialId`	`string` (uuid)	No	ID of an existing credential the current user may read.
`prefix`	`string`	No	Prefix placed before a credential value, including spaces. Use Bearer followed by a space for Bearer authentication. Rules: up to 100 characters

{
  "toolType": "API_REQUEST_TOOL",
  "configuration": {
    "displayName": "Service lookup",
    "executionDescription": "Look up a service request when the caller provides its reference.",
    "httpMethod": "GET",
    "targetUrl": "https://service.example.com/status",
    "headers": [],
    "callerMessageEnabled": false,
    "timeoutMs": 5000
  }
}

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`
`ETag`	`string`	Current revision. Send unchanged, including quotes, as If-Match when required. Example: `"revision-from-get"`

application/json

FieldsExample

The response matches its toolType:

MCP_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `MCP_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`mcpToolId`	`string` (uuid)	ID of an approved external MCP tool from the tool catalog. Rules: up to 100000 characters; `null` allowed
`callerMessageEnabled`	`boolean`	Announce the tool action to the caller. Rules: `null` allowed

DIRECT_FORWARDING_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `DIRECT_FORWARDING_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`allowDynamicRecipient`	`boolean`	Allow the Agent to choose a forwarding destination dynamically. Rules: `null` allowed
`forwardingInformation`	`object`	Forwarding destinations, keyed by destination name. Rules: up to 100 keys; `null` allowed Each value: `string`; up to 4000 characters

CONFERENCE_FORWARDING_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `CONFERENCE_FORWARDING_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`allowDynamicRecipient`	`boolean`	Allow the Agent to choose a forwarding destination dynamically. Rules: `null` allowed
`forwardingInformation`	`object`	Forwarding destinations, keyed by destination name. Rules: up to 100 keys; `null` allowed Each value: `string`; up to 4000 characters
`forwardingTimeout`	`integer`	Time to wait for the forwarding destination, in seconds. Rules: `5–120`; `null` allowed
`screeningEnabled`	`boolean`	Enable recipient screening during conference forwarding. Rules: `null` allowed
`machineDetectionEnabled`	`boolean`	Enable answering-machine detection during conference forwarding. Rules: `null` allowed
`screeningSummaryPrompt`	`string`	Instructions for the conversation summary presented during recipient screening. Rules: up to 100000 characters; `null` allowed
`announcementPrompt`	`string`	Instructions for the announcement used during forwarding. Rules: up to 100000 characters; `null` allowed

EMAIL_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `EMAIL_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`email_to`	List of `string`	Configured email recipient addresses. Rules: up to 100 entries; `null` allowed Each entry: up to 320 characters
`allow_ai_to_recipients`	`boolean`	Allow the Agent to supply email recipient addresses. Rules: `null` allowed
`email_cc`	List of `string`	CC recipient addresses. Rules: up to 100 entries; `null` allowed Each entry: up to 320 characters
`email_prompt`	`string`	Instructions for writing the email body. Rules: up to 100000 characters; `null` allowed
`email_subject`	`string`	Subject of the email. Rules: up to 100000 characters; `null` allowed
`include_facts`	`boolean`	Include collected conversation facts when generating the email. Rules: `null` allowed
`include_conversation_history`	`boolean`	Include the conversation history when generating the email. Rules: `null` allowed

SMS_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `SMS_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`sender_id`	`string`	Sender identifier for outgoing SMS messages. Rules: up to 100000 characters; `null` allowed
`body_mode`	`string`	How the SMS message text is created. Rules: up to 100000 characters; `null` allowed Values: `AGENT_PROVIDED`, `STATIC`, `TEMPLATE`
`static_body`	`string`	Fixed SMS message text used in STATIC mode. Rules: up to 100000 characters; `null` allowed
`body_template`	`string`	Template for the SMS message text. Rules: up to 100000 characters; `null` allowed

WEB_SEARCH_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `WEB_SEARCH_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`searchContext`	`string`	Context that helps the Agent formulate the web search. Rules: up to 100000 characters; `null` allowed
`allowedDomains`	`string`	Domain filter for web search. Rules: up to 100000 characters; `null` allowed
`searchLanguage`	`string`	Language used for web search. Rules: up to 100000 characters; `null` allowed Values: `de`, `en`, `es`, `fr`, `nl`
`country`	`string`	Country used to localize web-search results. Rules: up to 100000 characters; `null` allowed Show all 11 allowed values `AT`, `AU`, `BE`, `CA`, `CH`, `DE`, `ES`, `FR`, `GB`, `NL`, `US`
`callerMessageEnabled`	`boolean`	Announce the tool action to the caller. Rules: `null` allowed
`maximumTokens`	`integer`	Token budget for web-search results. Rules: `0–30000`; `null` allowed
`maximumSources`	`integer`	Maximum number of sources used for web-search results. Rules: `0–30000`; `null` allowed
`timeoutMs`	`integer`	Time limit for the outgoing request, in milliseconds. Rules: `0–30000`; `null` allowed

API_REQUEST_TOOL

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.
`toolType`	`string`	Tool type from the tool catalog. It cannot change after creation. Values: `API_REQUEST_TOOL`
`configuration`	`object`	Settings for this resource. Send the complete editable configuration when updating.

configuration — fields

Field	Type	Description
`displayName`	`string`	Name shown for this tool. Rules: up to 255 characters; `null` allowed
`executionDescription`	`string`	Tell the Agent when to use this tool and which inputs it needs. Rules: up to 100000 characters; `null` allowed
`httpMethod`	`string`	HTTP method used by the API tool. Rules: up to 100000 characters; `null` allowed Values: `GET`, `POST`, `PUT`, `DELETE`
`targetUrl`	`string`	Destination URL used by the API tool. Rules: up to 100000 characters
`headers`	List of `object`	HTTP request headers. Stored secret values are hidden.
`oauthConfigId`	`string` (uuid)	ID of an existing OAuth connection the current user may read. Rules: up to 100000 characters; `null` allowed
`contentType`	`string`	Content-Type of the outgoing request body. Rules: up to 100000 characters; `null` allowed Values: `application/json`, `application/x-www-form-urlencoded`, `text/plain`
`defaultBody`	`string`	Request body used as the tool's starting value. Rules: up to 100000 characters; `null` allowed
`inputSchema`	`string`	JSON Schema for inputs supplied by the Agent, encoded as a string. Rules: up to 100000 characters; `null` allowed
`responseProcessingMode`	`string`	How the API tool processes the response. Rules: up to 100000 characters; `null` allowed Values: `ORIGINAL`, `PATHS`, `SCRIPT`
`responseScript`	`string`	Script for transforming the external response. Rules: up to 100000 characters; `null` allowed
`responseMappings`	`object`	Map response values to named output fields. Rules: up to 100 keys; `null` allowed Each value: `string`; up to 4000 characters
`callerMessageEnabled`	`boolean`	Announce the tool action to the caller. Rules: `null` allowed
`timeoutMs`	`integer`	Time limit for the outgoing request, in milliseconds. Rules: `0–30000`; `null` allowed
`runAsync`	`boolean`	Run the API tool action asynchronously. Rules: `null` allowed

headers — fields

Field	Type	Description
`name`	`string`	HTTP header name, such as Authorization. Rules: up to 200 characters
`configured`	`boolean`	A value is stored. Send true without value to keep it at an unchanged target.
`credentialId`	`string` (uuid)	ID of an existing credential the current user may read.
`prefix`	`string`	Prefix placed before a credential value, including spaces. Use Bearer followed by a space for Bearer authentication. Rules: up to 100 characters

{
  "id": "00000000-0000-0000-0000-000000000001",
  "revision": "revision-from-get",
  "toolType": "MCP_TOOL",
  "configuration": {
    "mcpToolId": "00000000-0000-0000-0000-000000000001",
    "callerMessageEnabled": false
  }
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`409`	Missing/stale revision or dependency/routing conflict. Read again before retrying.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.