---
title: "create tool"
method: POST
path: "/v1/tools"
tags: ["Tools"]
---

# create tool

`POST /v1/tools`

Create a new tool for function calling in persona sessions

## Request body

- object
  - `name` string, required — Unique name for the tool. Must match pattern [a-zA-Z0-9_.-]+
  - `description` string, required — Description of what the tool does. Used by the LLM to decide when to call it.
  - `type` 'CLIENT' | 'SERVER_RAG' | 'SERVER_WEBHOOK' | 'SYSTEM', required — Type of tool: - CLIENT: Triggers events on the client SDK - SERVER_RAG: Searches knowledge base documents - SERVER_WEBHOOK: Calls an external webhook URL - SYSTEM: Internal system actions (end_call, interrupt)
  - `disableInterruptions` boolean — When true, interruptions are disabled while this tool is executing. Defaults to false.
  - `config` union — Type-specific configuration for the tool
    - object
      - `parameters` object — JSON schema for parameters the LLM will provide
      - `awaitResult` boolean — If true, engine pauses until client sends a result back. Default is fire-and-forget.
      - `toolTimeoutSeconds` number — Per-tool timeout in seconds when awaitResult is true. Default 10s.
    - object
      - `documentFolderIds` string[], required — IDs of knowledge folders to search
    - object
      - `url` string, uri, required — Webhook URL to call
      - `method` 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', required — HTTP method to use
      - `headers` object — Custom headers to send with the request
      - `bodyTemplate` string — Template for the request body
    - object
      - `action` 'end_call' | 'interrupt', required — System action to perform

## Response `201`

Successfully created tool

- Tool
  - `id` string, uuid — Unique identifier for the tool
  - `name` string — Name of the tool
  - `description` string — Description of what the tool does
  - `type` 'CLIENT' | 'SERVER_RAG' | 'SERVER_WEBHOOK' | 'SYSTEM' — Type of tool
  - `config` object — Type-specific configuration
  - `disableInterruptions` boolean — When true, interruptions are disabled while this tool is executing
  - `createdAt` string, date-time — When the tool was created
  - `updatedAt` string, date-time, nullable — When the tool was last updated
  - `usageCount` integer — Number of personas using this tool

## Other responses

- `400` — Bad request - Invalid tool data
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - API key lacks the required permission
- `500` — Server error

---

[API](https://skmtc.net/anam/apis/anam-ai-api.md) · [All operations](https://skmtc.net/anam/apis/anam-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/anam/anam-ai-api/revisions/dae97e8eb063/schema)