> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slng.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Attach a tool to an agent
> Attach a tool without losing the agent's existing tool or MCP configuration.
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](/guides/get-started/create-a-project/create-agent).
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.
List attachable tools and keep the `id` and `latest_version` you need.
```bash Request theme={null}
curl https://api.agents.slng.ai/v1/agents/tools \
-H "Authorization: Bearer $SLNG_API_KEY"
```
Set **Instructions shown to the model**, arguments, and tool-specific
options, then save. This instructions field maps to the API attachment
`description` field.
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`.
```bash Request theme={null}
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.
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:
```json MCP attachment theme={null}
{
"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](/api-reference/agents-resources/tools) for the upgrade
preview and accept endpoints.
Configure deterministic lifecycle invocation and event arguments.