Tools - Kataven

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

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

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.