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

> Configure what your AI agent can do — from contact forms to payments

Tools are configurable actions that your AI agent can trigger during a conversation. When the agent determines that a tool is relevant — based on context and user intent — it calls it automatically and presents the result inline.

## Two Categories

### Configurable Tools

Created by you (via the dashboard or API). You define their name, description, parameters, and behavior. The agent uses these tools exactly when you've described it should.

### Synthetic Tools

Auto-injected by the platform based on connectors and enrichment rules. You don't create them — they appear automatically when the right configuration is in place.

## All Tool Types

| Type                        | Category     | Description                                                                   | When available                                       |
| --------------------------- | ------------ | ----------------------------------------------------------------------------- | ---------------------------------------------------- |
| `SUBMIT_FORM`               | Configurable | Collect visitor info and send by email to tenant                              | Created by tenant                                    |
| `GENERATE_QUOTE`            | Configurable | Request a quote, or compute a real one ([Quote Engine](/guides/quote-engine)) | Created by tenant                                    |
| `BOOK_MEETING`              | Configurable | Book a calendar meeting                                                       | Created by tenant                                    |
| `ESCALATE_TO_HUMAN`         | Configurable | Transfer the conversation to a human agent                                    | Created by tenant                                    |
| `REMEMBER_FACT`             | Configurable | Store a key-value fact about the visitor                                      | Created by tenant                                    |
| `RECOMMEND_PRODUCT`         | Configurable | Search the product catalog and recommend items                                | Created when products exist                          |
| `CHECK_AVAILABILITY`        | Synthetic    | Query free calendar slots                                                     | Auto when Google Calendar connector + `BOOK_MEETING` |
| `COLLECT_PAYMENT`           | Synthetic    | Generate a Stripe Checkout link                                               | Auto when Stripe connector is active                 |
| `EXPLORE_CORPUS`            | Synthetic    | Fetch the full content of a corpus entry on demand                            | Auto when corpus entries have summaries              |
| `SEND_VERIFICATION_CODE`    | Synthetic    | Send an OTP code by email to the visitor                                      | Auto when `visitorAuthMode` is `otp` or `all`        |
| `VERIFY_VISITOR_CODE`       | Synthetic    | Verify the OTP code entered by the visitor                                    | Auto with `SEND_VERIFICATION_CODE`                   |
| `VERIFY_EXTERNAL_CHALLENGE` | Synthetic    | Delegated 2FA via external webhook                                            | Auto when external challenge is configured           |
| `MCP_PROXY`                 | Synthetic    | Proxy tool calls to an external MCP server                                    | Auto when tenant has `mcpToolsUrl`                   |

## Enrichment Chain

At the start of each conversation turn, the platform builds the active tool list through a sequential enrichment chain:

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

1. **dbTools** — Load all configurable tools from the database for this tenant
2. **enrichCalendar** — If Google Calendar connected + `BOOK_MEETING` exists, inject `CHECK_AVAILABILITY`
3. **enrichStripe** — If Stripe connected, inject `COLLECT_PAYMENT`
4. **enrichMCP** — If `mcpToolsUrl` configured, discover and inject `MCP_PROXY` tools (cached 5 min)
5. **enrichProducts** — If product catalog exists, inject `RECOMMEND_PRODUCT`
6. **enrichCorpus** — If corpus has summaries, inject `EXPLORE_CORPUS`
7. **enrichOTP** — If visitor auth requires OTP, inject `SEND_VERIFICATION_CODE` + `VERIFY_VISITOR_CODE`

The final list is what the LLM sees in its system prompt.

## Creating a Configurable Tool

```bash theme={null}
curl -X POST https://api.animam.ai/tenants/your-slug/tools \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SUBMIT_FORM",
    "name": "contact-form",
    "description": "Collect visitor name, email, and message",
    "parameters": {
      "fields": ["name", "email", "message"]
    }
  }'
```

## ToolSubmission Lifecycle

Every time a tool executes during a conversation, a **ToolSubmission** record is created and persisted.

### Statuses

```
NEW → CONTACTED → RESOLVED
```

| Status      | Meaning                                              |
| ----------- | ---------------------------------------------------- |
| `NEW`       | Tool was triggered, data collected, not yet actioned |
| `CONTACTED` | A human has followed up with the visitor             |
| `RESOLVED`  | The submission is closed                             |

### Channels

Submissions are tagged with the channel where the tool was triggered:

| Channel | Description              |
| ------- | ------------------------ |
| `web`   | Chat widget on a website |
| `voice` | Voice call via Vapi      |
| `form`  | Standalone form widget   |
| `api`   | Direct API call          |

### Viewing Submissions

```bash theme={null}
curl https://api.animam.ai/tenants/your-slug/submissions \
  -H "Authorization: Bearer ak_your_token"
```

Filter by status or tool type:

```bash theme={null}
curl "https://api.animam.ai/tenants/your-slug/submissions?status=NEW&type=SUBMIT_FORM" \
  -H "Authorization: Bearer ak_your_token"
```

## Booking CTA

When both `BOOK_MEETING` and a Google Calendar connector are active, the chat widget can display a **FOMO welcome screen** before the conversation starts.

This screen shows:

* Real-time calendar availability (next available slots)
* A countdown to the next free slot
* A direct booking CTA

This is the "iClosed-style" urgency pattern — showing scarcity based on real data, not fake timers. It increases booking conversion significantly without any additional configuration.

Enable it in **Dashboard > Widget > Welcome Screen** or via the tenant settings API.

## MCP Tools

The `MCP_PROXY` synthetic tool lets your agent proxy calls to any external MCP server. Configure a `mcpToolsUrl` on your tenant, and the platform will:

1. Discover available tools via `tools/list` at startup (cached 5 minutes)
2. Inject them into the agent's tool list
3. Proxy `tools/call` requests transparently during conversations

<Note>
  MCP Tools are available on **Pro** plan and above.
</Note>