> ## Documentation Index
> Fetch the complete documentation index at: https://docs.animam.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Endpoints to manage agent tools and actions

Endpoints to manage tools — the actions your AI agent can perform during a conversation.

## GET /tenants/{slug}/tools

List all tools configured for a tenant.

**Required scope:** `tools:read`

### Request

```bash theme={null}
curl https://api.animam.ai/tenants/my-company/tools \
  -H "Authorization: Bearer ak_your_token"
```

### Response

```json theme={null}
[
  {
    "id": "tool_abc123",
    "name": "Contact Form",
    "description": "Collect visitor contact details",
    "type": "SUBMIT_FORM",
    "config": {
      "fields": [
        { "name": "name", "label": "Full Name", "type": "text", "required": true },
        { "name": "email", "label": "Email", "type": "email", "required": true }
      ]
    },
    "position": 1,
    "isActive": true,
    "segment": "contact",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:00:00Z"
  }
]
```

## POST /tenants/{slug}/tools

Create a new tool.

**Required scope:** `tools:write`

### Request

```bash theme={null}
curl -X POST https://api.animam.ai/tenants/my-company/tools \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Form",
    "description": "Collect visitor contact details",
    "type": "SUBMIT_FORM",
    "config": {
      "fields": [
        { "name": "name", "label": "Full Name", "type": "text", "required": true },
        { "name": "email", "label": "Email", "type": "email", "required": true },
        { "name": "message", "label": "Message", "type": "textarea", "required": false }
      ]
    },
    "segmentId": "seg_xyz789",
    "isActive": true,
    "position": 1
  }'
```

### Body

| Field           | Type    | Required | Description                                                   |
| --------------- | ------- | -------- | ------------------------------------------------------------- |
| `name`          | string  | Yes      | Display name of the tool                                      |
| `description`   | string  | Yes      | Description shown to the agent to decide when to use the tool |
| `type`          | string  | Yes      | Tool type (see valid types below)                             |
| `config`        | object  | No       | Type-specific configuration (see SUBMIT\_FORM config format)  |
| `segmentId`     | string  | No       | Associate with a specific segment                             |
| `isActive`      | boolean | No       | Whether the tool is enabled (default: `true`)                 |
| `position`      | number  | No       | Display order (lower = higher priority)                       |
| `webhookUrl`    | string  | No       | Webhook endpoint for `ESCALATE_TO_HUMAN`                      |
| `webhookSecret` | string  | No       | HMAC secret for webhook signature verification                |

<Note>
  Only user-configurable types can be created via API: `SUBMIT_FORM`, `GENERATE_QUOTE`, `BOOK_MEETING`, `ESCALATE_TO_HUMAN`, `REMEMBER_FACT`, `RECOMMEND_PRODUCT`. Synthetic types (injected automatically by connectors) cannot be created manually.
</Note>

### Response

```json theme={null}
{
  "id": "tool_xyz789",
  "name": "Contact Form",
  "description": "Collect visitor contact details",
  "type": "SUBMIT_FORM",
  "config": { "fields": [...] },
  "position": 1,
  "isActive": true,
  "segment": null,
  "createdAt": "2024-01-25T10:30:00Z",
  "updatedAt": "2024-01-25T10:30:00Z"
}
```

## GET /tenants/{slug}/tools/{id}

Retrieve a specific tool.

**Required scope:** `tools:read`

```bash theme={null}
curl https://api.animam.ai/tenants/my-company/tools/tool_abc123 \
  -H "Authorization: Bearer ak_your_token"
```

## PATCH /tenants/{slug}/tools/{id}

Update a tool. Only the provided fields are modified.

**Required scope:** `tools:write`

```bash theme={null}
curl -X PATCH https://api.animam.ai/tenants/my-company/tools/tool_abc123 \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false,
    "description": "Updated description"
  }'
```

## DELETE /tenants/{slug}/tools/{id}

Delete a tool permanently.

**Required scope:** `tools:write`

```bash theme={null}
curl -X DELETE https://api.animam.ai/tenants/my-company/tools/tool_abc123 \
  -H "Authorization: Bearer ak_your_token"
```

### Response

```json theme={null}
{
  "deleted": true,
  "id": "tool_abc123"
}
```

***

## Tool Types Reference

### Configurable Types (user-created)

| Type                | Description                                                               | Triggered by                                       |
| ------------------- | ------------------------------------------------------------------------- | -------------------------------------------------- |
| `SUBMIT_FORM`       | Collects structured data from the visitor via a form                      | Agent decision based on description                |
| `GENERATE_QUOTE`    | Generates a price estimate based on visitor inputs                        | Agent decision based on description                |
| `BOOK_MEETING`      | Books a meeting on the agent's calendar                                   | Agent decision; requires Google Calendar connector |
| `ESCALATE_TO_HUMAN` | Hands off the conversation to a human agent via webhook                   | Agent decision or visitor request                  |
| `REMEMBER_FACT`     | Stores a key-value fact on the visitor's profile for future conversations | Agent decision based on conversation context       |
| `RECOMMEND_PRODUCT` | Recommends one or more products from the catalog to the visitor           | Agent decision based on description                |

### Synthetic Types (auto-injected by enrichment chain)

<Note>
  Synthetic tools are automatically injected at chat time by the enrichment chain when the relevant connector or configuration is active. They cannot be created, updated, or deleted via API.
</Note>

| Type                        | Description                                                  | Auto-injected when                               |
| --------------------------- | ------------------------------------------------------------ | ------------------------------------------------ |
| `CHECK_AVAILABILITY`        | Checks calendar availability for booking                     | Google Calendar connector is active              |
| `COLLECT_PAYMENT`           | Initiates a Stripe payment session                           | Stripe connector is active                       |
| `EXPLORE_CORPUS`            | Performs an on-demand full-text search of the knowledge base | Corpus summary mode is enabled (two-tier corpus) |
| `SEND_VERIFICATION_CODE`    | Sends an OTP code to the visitor's email                     | `visitorAuthMode` is `otp` or `all`              |
| `VERIFY_VISITOR_CODE`       | Verifies the OTP code entered by the visitor                 | `visitorAuthMode` is `otp` or `all`              |
| `VERIFY_EXTERNAL_CHALLENGE` | Delegates verification to an external HMAC webhook           | Context webhook auth is configured               |
| `MCP_PROXY`                 | Proxies a tool call to an external MCP server                | MCP connector is configured (Pro+ plan)          |

***

## Enrichment Chain

At chat time, before each agent response, Animam runs an enrichment chain that assembles the final tool list available to the agent:

```
dbTools → enrichCalendar → enrichStripe → enrichMCP → enrichProducts → enrichCorpus → enrichOTP
```

| Step             | What it does                                                                              |
| ---------------- | ----------------------------------------------------------------------------------------- |
| `dbTools`        | Loads all active user-configured tools for the tenant and segment                         |
| `enrichCalendar` | Injects `CHECK_AVAILABILITY` and activates `BOOK_MEETING` if Google Calendar is connected |
| `enrichStripe`   | Injects `COLLECT_PAYMENT` if Stripe connector is active                                   |
| `enrichMCP`      | Discovers and injects tools from an external MCP server (cached 5 min, Pro+ only)         |
| `enrichProducts` | Activates `RECOMMEND_PRODUCT` and loads the product catalog if products exist             |
| `enrichCorpus`   | Injects `EXPLORE_CORPUS` if corpus summary mode is enabled                                |
| `enrichOTP`      | Injects `SEND_VERIFICATION_CODE` / `VERIFY_VISITOR_CODE` based on visitor auth mode       |

Synthetic tools are injected transparently — no manual configuration required. The agent receives the full assembled tool list and decides which tools to call based on their descriptions.

***

## SUBMIT\_FORM Config Format

The `SUBMIT_FORM` type uses a `config.fields` array to define the form structure:

```json theme={null}
{
  "config": {
    "fields": [
      { "name": "name",    "label": "Full Name",     "type": "text",     "required": true  },
      { "name": "email",   "label": "Email Address",  "type": "email",    "required": true  },
      { "name": "phone",   "label": "Phone Number",   "type": "phone",    "required": false },
      { "name": "message", "label": "Your Message",   "type": "textarea", "required": false }
    ]
  }
}
```

### Field definition

| Field      | Type    | Required | Description                                            |
| ---------- | ------- | -------- | ------------------------------------------------------ |
| `name`     | string  | Yes      | Internal field identifier (used as key in submissions) |
| `label`    | string  | Yes      | Label displayed to the visitor in the form widget      |
| `type`     | string  | Yes      | Field type: `text`, `email`, `phone`, or `textarea`    |
| `required` | boolean | Yes      | Whether the visitor must fill in this field            |

<Warning>
  Field `name` values must be unique within a form and should use snake\_case. Changing field names after a tool has received submissions may break downstream integrations.
</Warning>

Submitted form data is stored as `ToolSubmission` records and transitions through statuses: `NEW` → `CONTACTED` → `RESOLVED`. Submissions can be retrieved via the conversations API or viewed in the dashboard.