> ## 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.

# Tools

> Endpoints and fields for authoring, testing, publishing, and upgrading shared tools.

Use the Tools API to manage organization tool drafts and published versions.
All requests use `https://api.agents.slng.ai` and a bearer API key.

```bash Authorization theme={null}
Authorization: Bearer $SLNG_API_KEY
```

## Endpoints

| Method   | Path                                                                                          | Purpose                                           |
| -------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `GET`    | `/v1/agents/tools`                                                                            | List attachable organization and global tools     |
| `POST`   | `/v1/agents/tools`                                                                            | Create an organization tool draft                 |
| `GET`    | `/v1/agents/tools/{tool_id}`                                                                  | Get a draft and its current gate status           |
| `PATCH`  | `/v1/agents/tools/{tool_id}`                                                                  | Update an organization tool draft                 |
| `DELETE` | `/v1/agents/tools/{tool_id}`                                                                  | Delete an organization tool                       |
| `POST`   | `/v1/agents/tools/{tool_id}/introspect`                                                       | Prepare Custom Code and derive its schema         |
| `POST`   | `/v1/agents/tools/{tool_id}/run`                                                              | Run a prepared draft with sample input            |
| `POST`   | `/v1/agents/tools/{tool_id}/publish`                                                          | Publish the current draft as an immutable version |
| `POST`   | `/v1/agents/tools/{tool_id}/duplicate`                                                        | Copy a visible tool into the organization         |
| `GET`    | `/v1/agents/tools/{tool_id}/versions`                                                         | List published versions                           |
| `GET`    | `/v1/agents/tools/{tool_id}/versions/{version}`                                               | Get one published version                         |
| `POST`   | `/v1/agents/tools/agents/{agent_id}/attachments/{attachment_id}/upgrade-preview/{to_version}` | Preview an attachment upgrade                     |
| `POST`   | `/v1/agents/tools/agents/{agent_id}/attachments/{attachment_id}/upgrade-accept`               | Accept a previewed upgrade                        |

`GET /v1/agents/tools` accepts `limit` from 1 to 200, `offset` up to 10,000,
and repeatable exact `name` filters.

## Tool types

| `tool_type`                                                                                 | Draft contract                                                                                         |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `api_request`                                                                               | `config` contains the HTTPS request, authentication, headers, parameters, timeout, and response policy |
| `code`                                                                                      | `code_src`, exact `dependencies`, `declared_secrets`, and optional scalar `argument_defaults`          |
| `send_sms`                                                                                  | Organization singleton configured with Twilio Vault secrets and attachment values                      |
| `end_call`, `voicemail_detection`, `transfer_call`, `current_datetime`, `user_phone_number` | Global capabilities returned by the list endpoint; they cannot be created by an organization           |

Names are 1 to 200 characters and can contain letters, numbers, underscores,
and dashes. Descriptions are limited to 2,000 characters.

## API Request config

| Field                   | Contract                                                       |
| ----------------------- | -------------------------------------------------------------- |
| `url`                   | Literal HTTPS URL with a host; no user information or fragment |
| `http_method`           | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`                     |
| `auth.type`             | `none`, `bearer`, or `hmac`                                    |
| `auth.secret_name`      | Required Vault name for bearer or HMAC authentication          |
| `headers`               | Up to 64 unique literal or Vault-backed headers                |
| `parameters`            | Strict JSON Schema object for the request body                 |
| `timeout_seconds`       | 1 to 60 seconds; default 10                                    |
| `wait_for_response`     | Wait for the endpoint before completing the tool execution     |
| `response.show_to_llm`  | Include the result in model context                            |
| `response.instructions` | Tell the model how to interpret the result                     |

The executor manages authentication, signatures, and hop-by-hop headers.

## Test request

```json RunRequest theme={null}
{
  "sample_input": {
    "order_id": "WE-1042"
  },
  "confirm_side_effects": true
}
```

The response reports `status` as `succeeded`, `failed`, or `timed_out` and
includes `latency_ms`, `output_json`, `logs`, `validation`, `error`, and the
current `gate_status`.

## Publish response

Publishing returns `published`, `version_number`, and `checks`. If one or more
checks fail, the endpoint returns HTTP `409` with `published: false` and the
failed gate details.

Published versions are immutable. Updating the draft does not modify a version
or an existing agent attachment.

## Upgrade an attachment

The preview endpoint returns the current and target version hashes, any added,
removed, renamed, or type-changed parameters, a reconciled attachment, blocking
issues, and `can_accept`. A code dependency preparation can return HTTP `202`;
use its `Retry-After` header before requesting the preview again.

To accept the preview, send its version and proof fields unchanged:

```json Upgrade request theme={null}
{
  "to_version": 2,
  "current_config_hash": "3eb65a78fd40c6d10b8de0a7e39fd4706712ab2f0d86a78d2c08fb451ba6a7f8",
  "current_tool_version_hash": "f2ea7f5c07fbc6820f9ba73dfd858bd3eb098c7007185fb84ac2a7d406793b03",
  "target_tool_version_hash": "83c91e80a0b48dbb4843a90af8a2d476928957d20a768b7467b311cf50c88d13",
  "dependency_proof_hash": null,
  "acceptance_hash": "95d374b5df35f1e5b5e0da8ef86452bd57cf20fce325a59f5f813969b6551609"
}
```

If the agent, attachment, or target version changes after the preview, request a
new preview instead of reusing the old proof.

## Attachment contract

Organization and global tools use `tool_refs`; MCP tools use `mcp_refs`. Both
arrays belong to the agent update contract. A `PATCH` that includes an array
replaces that entire array. `PUT /v1/agents/{agent_id}` replaces the complete
agent configuration.

See [Attach a tool to an agent](/guides/agents/tools-and-mcp/attach-to-an-agent)
for a safe read, edit, and partial-update example.