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
Controls what the client sees about tool execution. The default is description.
| Mode | Behavior |
|---|---|
hidden | No UI events emitted. The tool executes silently and the user has no awareness it was called. Use for internal plumbing tools (title setting, context management). |
name | Shows the raw tool name while executing. Arguments and result are not displayed. |
description | Shows the tool's description while executing (default). Arguments are visible during live streaming but the result is not preserved after page refresh. |
stream | Full visibility. Arguments stream progressively as the LLM generates them, and the result is shown after execution. The result is preserved after page refresh. |
When to use stream:
- Client tools where the user benefits from seeing arguments or results
- Interactive client tools (user provides input via the tool card)
- Tools whose result is rendered via
renderToolCallResult - Any tool where transparency into what was sent/received matters
When to use hidden:
- Internal lifecycle tools (e.g., session title setting)
- Context-setting tools that would clutter the UI
- Tools that are implementation details of the agent's protocol
Refresh and restore behavior:
stream is the only mode that preserves the tool result after a page refresh. For all other modes, the result is available during the live session but stripped on refresh. On session restore (when the session expires and is rebuilt from stored UIMessage[]), stream tools retain their original result while other modes receive a placeholder.
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: