Tools
Tools extend what agents can do. Octavus supports multiple types:
- External Tools — Defined in the protocol, implemented in your backend (this page)
- MCP Tools — Auto-discovered from MCP servers (see MCP Servers)
- Built-in Tools — Provider-agnostic tools managed by Octavus (web search, image generation)
- Provider Tools — Provider-specific tools executed by the provider (e.g., Anthropic's code execution)
- Skills — Code execution and knowledge packages (see Skills)
This page covers external tools. For MCP-based tools from services like Figma, Sentry, or device capabilities like browser and filesystem, see MCP Servers. Built-in tools are enabled via agent config — see Web Search and Image Generation. For provider-specific tools, see Provider Options. For code execution, see Skills.
External Tools
External tools are defined in the tools: section and implemented in your backend.
Defining Tools
Tool Fields
| Field | Required | Description |
|---|---|---|
description | Yes | What the tool does (shown to LLM and optionally user) |
display | No | How to show in UI: hidden, name, description, stream |
parameters | No | Input parameters the tool accepts |
Display Modes
| Mode | Behavior |
|---|---|
hidden | Tool runs silently, user doesn't see it |
name | Shows tool name while executing |
description | Shows description while executing (default) |
stream | Streams tool progress if available |
Parameters
Tool calls are always objects where each parameter name maps to a value. The LLM generates: { param1: value1, param2: value2, ... }
Parameter Fields
| Field | Required | Description |
|---|---|---|
type | Yes | Data type: string, number, integer, boolean, unknown, or a custom type |
description | No | Describes what this parameter is for |
optional | No | If true, parameter is not required (default: false) |
Tip: You can use custom types for complex parameters like type: ProductFilter or type: SearchOptions.
Array Parameters
For array parameters, define a top-level array type and use it:
The tool receives: { items: [{ productId: "...", quantity: 1 }, ...] }
Optional Parameters
Parameters are required by default. Use optional: true to make a parameter optional:
Making Tools Available
Tools defined in tools: are available. To make them usable by the LLM, add them to agent.tools:
Tool Invocation Modes
LLM-Decided (Agentic)
The LLM decides when to call tools based on the conversation:
Deterministic (Block-Based)
Force tool calls at specific points in the handler:
Tool Results
In Prompts
Tool results are stored in variables. Reference the variable in prompts:
When the TICKET variable contains an object, it's automatically serialized as JSON in the prompt:
Note: Variables use {{VARIABLE_NAME}} syntax with UPPERCASE_SNAKE_CASE. Dot notation (like {{TICKET.ticketId}}) is not supported. Objects are automatically JSON-serialized.
In Variables
Store tool results for later use:
Implementing Tools
Tools are implemented in your backend: