Attach a tool to an agent

An attachment connects one tool to one agent and stores that agent’s invocation and override settings. Organization and built-in attachments pin a published version. MCP attachments pin the schema observed during discovery.

Prerequisites

An agent in shared tool mode. Agents created through the API start in shared mode; recreate an older agent to move it to shared mode.
A published organization tool, a ready-to-use built-in, or a connected MCP tool.
The current agent ID and permission to update it.

To attach tools when you first create the agent, include tool_refs in the create body. Creation applies them in one request, without the download-and-PUT step. See Create an agent.

Find the tool

Dashboard
API

Open the project, go to Tools, and choose Add Tool. Select a group, find the tool, then choose whether the model or system calls it. Some tools support only one invocation type.

The Add Tool menu with the Called by the model icon highlighted for Blank webhook — Choose the tool and its invocation type

List attachable tools and keep the id and latest_version you need.

Request

curl https://api.agents.slng.ai/v1/agents/tools \
  -H "Authorization: Bearer $SLNG_API_KEY"

Configure the attachment

Dashboard
API

Set Instructions shown to the model, arguments, and tool-specific options, then save. This instructions field maps to the API attachment description field.

An expanded webhook attachment with the Instructions shown to the model field highlighted — Configure the attachment

Attachments live in the agent’s tool_refs and mcp_refs. Change them by downloading the full config, adding the attachment, and sending the whole config back with PUT.Generate a UUID for attachment_id.

Request

curl -OJ https://api.agents.slng.ai/v1/agents/$AGENT_ID/config \
  -H "Authorization: Bearer $SLNG_API_KEY"

ATTACHMENT_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"

jq --arg attachment_id "$ATTACHMENT_ID" \
  --arg tool_id "$TOOL_ID" \
  --argjson version "$TOOL_VERSION" \
  '.tool_refs += [{
    attachment_id: $attachment_id,
    tool_id: $tool_id,
    version: $version,
    description: "Transfer to a person when the caller asks for one.",
    invocation: "model",
    argument_overrides: {},
    config_overrides: {
      type: "transfer_call",
      destination: "+15551234567"
    }
  }]' agent-$AGENT_ID.json > agent-updated.json

curl -X PUT https://api.agents.slng.ai/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $SLNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d @agent-updated.json

-OJ saves the download as agent-$AGENT_ID.json, the file the jq edit reads. Editing the downloaded config keeps every other field, including the existing tool_refs and mcp_refs, so nothing is dropped. The PUT replaces the complete configuration in one request.

Verify the attachment

Confirm that the agent response contains the new attachment and every previous entry in tool_refs and mcp_refs. Then run a test call that exercises the tool.

Change tool_refs and mcp_refs through the download-and-PUT flow; PUT replaces the complete configuration. Use PATCH for top-level fields and the models block. A PATCH that includes tool_refs or mcp_refs returns AGENT_CONFIG_PREPARATION_REQUIRED, the signal to switch to the PUT flow.

Attachment fields

Field	Purpose
`attachment_id`	A lowercase canonical UUID generated by the client
`tool_id` and `version`	The immutable organization or built-in tool version
`server_id`, `tool_name`, `observed_schema_hash`	The discovered MCP tool contract, used instead of `tool_id` and `version`
`description`	Model instructions for this agent; labeled Instructions shown to the model in the Dashboard
`invocation`	`model` or `system` for supported tools; MCP tools use `model`
`argument_overrides`	Literal values or references that replace model-supplied arguments
`config_overrides`	Tool-specific settings such as transfer destination or timezone
`execution_policy`	An optional message the agent speaks before running the tool

Value references can point to agent input or runtime memory with {{customer_id}}, or to call context with values such as {{@phone_number}}. A pre-action message can wait until the agent finishes speaking before execution starts.

Attach an MCP tool

An MCP attachment uses the server and discovered schema instead of a published version:

MCP attachment

{
  "attachment_id": "1f0a2b3c-4d5e-4f60-8a91-b2c3d4e5f607",
  "server_id": "7d91cf1e-4778-4bb8-b2a8-d891f78fb27f",
  "tool_name": "lookup_inventory",
  "description": "Check available inventory for a product code.",
  "invocation": "model",
  "argument_overrides": {},
  "observed_schema_hash": "f7d1608b1a6f09ca0a6737116ef83d033a93df67c45e733e43622f7b72668a47"
}

Append this object to the complete current mcp_refs array and preserve tool_refs in the same partial update.

Upgrade a version

Publishing a new version does not change an attachment. Preview the upgrade, review changed arguments and configuration, then accept it. The attachment ID stays the same while its pinned version changes. See Tools API reference for the upgrade preview and accept endpoints.

Run a tool on call events

Configure deterministic lifecycle invocation and event arguments.

Get started

Regions

Execution layer

Agent Builder

Models

Integrate

Prerequisites

Attachment fields

Attach an MCP tool

Upgrade a version

Run a tool on call events

​Prerequisites

​Attachment fields

​Attach an MCP tool

​Upgrade a version

Run a tool on call events

Prerequisites

Attachment fields

Attach an MCP tool

Upgrade a version