Tools - Animam Documentation

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

GET /tenants//tools

List all tools configured for a tenant. Required scope: tools:read

Request

curl https://api.animam.ai/tenants/my-company/tools \
  -H "Authorization: Bearer ak_your_token"

Response

[
  {
    "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//tools

Create a new tool. Required scope: tools:write

Request

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

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.

Response

{
  "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//tools/

Retrieve a specific tool. Required scope: tools:read

curl https://api.animam.ai/tenants/my-company/tools/tool_abc123 \
  -H "Authorization: Bearer ak_your_token"

PATCH /tenants//tools/

Update a tool. Only the provided fields are modified. Required scope: tools:write

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//tools/

Delete a tool permanently. Required scope: tools:write

curl -X DELETE https://api.animam.ai/tenants/my-company/tools/tool_abc123 \
  -H "Authorization: Bearer ak_your_token"

Response

{
  "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
`PREFILL_FORM`	Pre-fills a form on the site with details collected during the conversation (widget)	Agent decision based on description
`VERIFIED_ACTION`	Server-to-server action on the tenant backend, carried by the OTP/JWT-verified visitor email — tenant-configured (URL + secret), never an LLM argument	Agent decision based on description

Synthetic Types (auto-injected by enrichment chain)

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.

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 (included from Pro; add-on €19/mo on Builder)
`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 (Builder plan and above)

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, Builder+ 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:

{
  "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

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.

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.

​GET /tenants//tools

​Request

​Response

​POST /tenants//tools

​Request

​Body

​Response

​GET /tenants//tools/

​PATCH /tenants//tools/

​DELETE /tenants//tools/

​Response

​Tool Types Reference

​Configurable Types (user-created)

​Synthetic Types (auto-injected by enrichment chain)

​Enrichment Chain

​SUBMIT_FORM Config Format

​Field definition

GET /tenants//tools

Request

Response

POST /tenants//tools

Request

Body

Response

GET /tenants//tools/

PATCH /tenants//tools/

DELETE /tenants//tools/

Response

Tool Types Reference

Configurable Types (user-created)

Synthetic Types (auto-injected by enrichment chain)

Enrichment Chain

SUBMIT_FORM Config Format

Field definition