Agent Tools Overview

What are agent tools?

Tools are functions the LLM can call during a conversation. When the agent decides it needs external information or needs to take an action, it invokes a tool, the worker executes it, and the result is fed back into the LLM’s context.

Tools are defined per-character in the dashboard or via the Characters API. Each character can have any number of tools; the LLM sees their descriptions and schemas and decides when to use them.

Tool kinds

Kind	Use case
`http`	Call any REST API — look up records, send data, trigger webhooks
`kb`	Semantic search over documents you’ve uploaded to the Knowledge Base
`mcp`	Connect an MCP server and call one of its tools
`client_event`	Publish a LiveKit data-channel message to the browser widget

Shared fields

Every tool definition shares these fields regardless of kind:

Field	Type	Required	Description
`name`	string	✓	Alphanumeric + underscores, max 64 chars (e.g. `ticket_lookup`). Used as the function name the LLM calls.
`kind`	`"http"` \| `"kb"` \| `"mcp"` \| `"client_event"`	✓	Determines how the worker executes the tool.
`description`	string	✓	Natural-language description shown to the LLM. Be specific — the LLM uses this to decide when to call the tool.
`input_schema`	object	✓	OpenAI function-calling JSON Schema . Defines the arguments the LLM must pass.
`config`	object	✓	Kind-specific configuration (see each tool page).
`is_active`	boolean		`false` = tool is hidden from the LLM. Default `true`.
`ordering`	number		Display order (tools are shown to the LLM in ascending order).

Tool limits (per session)

Limit	Default	Configurable
Max tool calls per turn	6	Yes (per-character)
Max tool output size	16 000 chars	Yes (per-character)
Max turn duration	35 s	Yes (per-character)

Output longer than max_tool_output_chars is truncated before being returned to the LLM.

Example: full tool definition


{
  "name": "ticket_lookup",
  "kind": "http",
  "description": "Look up a support ticket by ID. Use this when the user mentions a ticket number.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticket_id": {
        "type": "string",
        "description": "The ticket ID, e.g. TICKET-123"
      }
    },
    "required": ["ticket_id"]
  },
  "config": {
    "url": "https://api.yoursite.com/tickets/lookup",
    "method": "POST",
    "timeout_seconds": 10,
    "headers": {
      "Authorization": "Bearer your-service-token"
    }
  }
}

Writing good descriptions

The LLM picks tools based solely on their description and the conversation context. A vague description leads to tools being called at the wrong time or not at all.

Poor: "Gets ticket info"

Good: "Look up a support ticket by ID. Returns the ticket's status, priority, assigned agent, and last update. Use this when the user mentions a ticket number like TICKET-123."

Guidelines:

State what the tool returns, not just what it does
Mention the conditions under which it should be called
Give examples of trigger phrases if relevant
Keep it under 200 words