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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.