Skip to main content
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_typeWhat runs
pythonThe implementation_code body, executed in the Call Processor’s sandboxed Python environment.
httpAn external HTTP endpoint described in implementation_config (URL, method, auth). The Call Processor calls it with the tool args as JSON.

​
Operations

OperationEndpoint
List (paginated, filterable by category/type/search)GET /api/tools
GetGET /api/tools/{id} (UUID or name)
CreatePOST /api/tools
UpdatePUT /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.