# Agent toolbox

> The tools the virtual agent can call: external API calls, system actions and human handoff.

The tools the virtual agent can call: external API calls, system actions and human handoff.

## `tool_get`

**Get a tool** · Read only · Listed to the agent from the start

Gets the full config of ONE tool by `tool_id` + `name`. Includes `type` and `config` (urlTemplate, method, headers, bodyTemplate, parameters, outputMappings, etc., depending on the type). Call it before `tool_update` so no field is lost.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes |  |
| `tool_id` | string | Yes |  |

## `tool_secrets_list`

**List tool variables and secrets** · Read only · Listed to the agent from the start

Lists the organization's tool variables and secrets, to reuse in a tool as `{{secret:name}}` or `{{env:name}}`. For a secret it returns `name`, `kind` and `allowedOrigins` (the only destinations it is sent to); for a variable, `name`, `kind` and `value`. A secret's value is never returned. Read-only: creating, replacing or deleting one, and changing its origins, is done by a person in the admin.

No arguments.

## `tool_test`

**Test an HTTP tool** · Changes data · can overwrite or remove · Listed to the agent from the start

Tests an HTTP tool (type external/webhook) end to end: substitutes `test_inputs` into url, headers and body, makes the real call to the configured API and returns the variables extracted by outputMappings and the shape of the response (status, types and fields), without its content: that content belongs to the customer and is not delivered through this channel. It is a real outgoing call to an external service and can have effects. Only for external/webhook tools.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `test_inputs` | object | Yes |  |
| `tool_id` | string | Yes |  |
| `tool_name` | string | Yes |  |
| `descripcion` | string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |

## `tools_list`

**List tools** · Read only · Listed to the agent from the start

Lists the tools of the Organization Toolbox. Returns each with its `toolId`, `name`, `type` and `description`. Optional `agent_id` filters legacy tools assigned to an agent. The `name` is needed by `tool_get`, `tool_update` and `tool_delete` (it is part of the key).

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_id` | string | No |  |

## `tools_summary`

**Summarize tools** · Read only · Listed to the agent from the start

Summary of the toolbox grouped by agent and type (how many tools and of which types).

No arguments.

## `tool_create_api_call`

**Create an API call tool** · Changes data · can overwrite or remove · Reached with `dakso_explore`

Creates an API Call tool (type=external): the virtual agent calls an external HTTP API. `name` in snake_case, unique; `description` says when to use it. `parameters` = `{name: {type, required, description}}`. `url_template`, `headers` values and `body_template` accept `${var}`. `output_mappings` `{jsonPath: variable}` saves response fields. Never write credentials as text: use `{{secret:name}}` only in `headers` and `{{env:name}}` for non-secret values (see `tool_secrets_list`). A tool created with a secret stays pending (`pendingApproval: true`) until a person confirms it in the admin. To use it, add its `name` to `enabledTools` of the agent node.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string | Yes |  |
| `name` | string | Yes |  |
| `url_template` | string | Yes |  |
| `body_template` | string | No | Default: `""`. |
| `descripcion` | string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
| `headers` | object | No |  |
| `method` | string | No | Default: `"POST"`. |
| `output_mappings` | object | No |  |
| `parameters` | object | No |  |

## `tool_create_human_handoff`

**Create a human handoff tool** · Changes data · can overwrite or remove · Reached with `dakso_explore`

Creates a Human Handoff tool (type=handoff): it routes the conversation to a queue of human agents. `queue_name` is the destination queue; `priority` is low/normal/high/urgent; `skills` is an optional list of skills required for routing. `description` says when to escalate to a human.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string | Yes |  |
| `name` | string | Yes |  |
| `descripcion` | string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
| `priority` | string | No | Default: `"normal"`. |
| `queue_name` | string | No | Default: `"default"`. |
| `skills` | array | No |  |

## `tool_create_system_action`

**Create a system action tool** · Changes data · can overwrite or remove · Reached with `dakso_explore`

Creates a System Action tool (type=action): it triggers an internal flow event. `trigger_intent` must be 'end_conversation' (end the conversation) or 'request_human_agent' (ask for a human agent). Optional `parameters` (input schema), for example `{"reason": {"type":"string","required":true,"description":"..."}}`. Agent nodes already include end_call and request_human through `agentCapabilities`; a custom action is useful when another name or other parameters are needed.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string | Yes |  |
| `name` | string | Yes |  |
| `trigger_intent` | string | Yes |  |
| `descripcion` | string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
| `parameters` | object | No |  |

## `tool_delete`

**Delete a tool** · Changes data · can overwrite or remove · Reached with `dakso_explore`

Deletes a tool from the toolbox. Destructive: it removes the tool from every agent that references it in `enabledTools`, which can break flows in production. For safety the agent does not run this action: the tool returns a link to the Dakso admin screen where a person confirms it. Give the user that link.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes |  |
| `tool_id` | string | Yes |  |
| `descripcion` | string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |

## `tool_update`

**Edit a tool** · Changes data · can overwrite or remove · Reached with `dakso_explore`

Updates an existing tool (description and/or config). `name` is required (part of the key) and cannot be changed: renaming is deleting and creating again. `config` replaces the tool's config, so send it complete for the type (not a partial merge); `tool_get` returns the current one. Credentials go as references: `{{secret:name}}` only in `headers` and `{{env:name}}` for non-secret values (`tool_secrets_list` returns the existing ones). On a tool that uses secrets, changing the URL, method, headers or body leaves it pending: it stops running, in production too, until a person confirms it in the admin, so that change needs the prior agreement of the user.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes |  |
| `tool_id` | string | Yes |  |
| `config` | object | No |  |
| `descripcion` | string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
| `description` | string | No |  |
