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

# Tools

> Functions an AI voice agent can call mid-conversation — built-in tools, custom Python tools, third-party integrations like Stripe, Shopify, and Slack with encrypted credentials.

A **tool** is a function the agent can invoke during a call. It has
a name, a JSON-Schema describing its arguments, and an
implementation — either Python source we execute in the Call
Processor's tool sandbox, or an HTTP endpoint we call.

## Anatomy

```json theme={null}
{
  "id": "uuid",
  "name": "book_appointment",
  "display_name": "Book an appointment",
  "category": "calendar",
  "description": "Reserve a calendar slot for the caller.",
  "schema": {
    "type": "object",
    "properties": {
      "iso_datetime": {"type": "string", "format": "date-time"},
      "name":         {"type": "string"},
      "phone":        {"type": "string"}
    },
    "required": ["iso_datetime", "name", "phone"]
  },
  "implementation_type": "python",
  "implementation_config": {},
  "implementation_code": "def main(args, ctx):\n    return {'ok': True}",
  "tags": ["calendar", "scheduling"],
  "is_default": false
}
```

## Built-in vs custom

* **Built-in tools** (`is_default = true`) ship with the platform and
  can't be deleted. Updating one flips `modified_from_default = true`
  so the dashboard can show that the tool diverges from the default.
* **Custom tools** (`is_default = false`) are yours; you can create,
  update, and delete them freely.

## Implementation types

| `implementation_type` | What runs                                                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `python`              | The `implementation_code` body, executed in the Call Processor's sandboxed Python environment.                                              |
| `http`                | An external HTTP endpoint described in `implementation_config` (URL, method, auth). The Call Processor calls it with the tool args as JSON. |

## Operations

| Operation                                            | Endpoint                             |
| ---------------------------------------------------- | ------------------------------------ |
| List (paginated, filterable by category/type/search) | `GET /api/tools`                     |
| Get                                                  | `GET /api/tools/{id}` (UUID or name) |
| Create                                               | `POST /api/tools`                    |
| Update                                               | `PUT /api/tools/{id}`                |
| Delete (custom only — built-ins return `403`)        | `DELETE /api/tools/{id}`             |

## Enabling a tool on an agent

Defining a tool doesn't expose it to any agent. Each agent picks the
subset it can call:

```python theme={null}
client.agents.upsert_tool(
    agent_id="...",
    tool_name="book_appointment",
    config={"calendar_id": "primary"},
    enabled=True,
)
```

Behind that: `POST /api/agents/{id}/tools` with `{tool_name, config, enabled}`.

## Where tools fit vs playbooks

A **tool** is a function. A **playbook** is a knowledge bundle — a
prompt fragment plus a list of tool *names* it expects to be present.
Attach the playbook, and the agent gets both the prompt context and a
hint about which tools it should reach for.