In plain terms
A tool is a function the agent is allowed to call. You write: “here isgetWeather. It needs a city.”
The model decides when to call it. Agentium runs your function and shows the result back to the model.
description is the most important field. The model reads it to decide. Write it like a hint to a smart intern.
Every defineTool() field
The first four are required. The rest are optional safety/quality knobs.
string
required
Unique within this agent. Use
snake_case or camelCase — the model sees this string. Don’t reuse names.string
required
When to call this tool. Write it like a hint to a smart intern: what it does and when not to use it. This is the most important field.
z.ZodObject
required
Zod object of arguments. Put
.describe("...") on every field — those descriptions go to the model.(args, ctx) => Promise<string | ToolResult>
required
Your code.
args is already parsed and typed from the Zod schema. ctx is RunContext. Return a string (the model reads it) or { content, artifacts? }. Throw to mark the tool as failed — the model sees the error text and can retry.{ ttl: number }
Remember the result for
ttl milliseconds. Same args within the window skip execute. See Tool Caching.boolean | SandboxConfig
Run
execute in a subprocess. true uses defaults (timeout: 30000, maxMemoryMB: 256, no network, no FS). Object fields: enabled, timeout, maxMemoryMB, allowNetwork, allowFS, env. See Sandbox.boolean | (args) => boolean
true = always ask a human. A function lets you approve only dangerous args (args.amount > 1000). See Approval.boolean
default:"false"
OpenAI Structured Outputs for this tool’s arguments. The model must return JSON matching the schema. Use when bad JSON would break
execute.Array<z.infer<T>>
N-shot examples rendered into the tool schema so the model copies the shape.
(result, ctx) => Promise<string | ToolResult>
Transform the result after
execute and before it is appended to the prompt. Use to redact, compress, or summarize giant outputs.Record<string, unknown>
Skip Zod→JSON conversion and send this schema to the model. MCP tools set this. You almost never need it for hand-written tools.
execute also gets ctx (RunContext): ctx.userId, ctx.sessionId, ctx.tenantId, ctx.metadata, ctx.dependencies, ctx.signal, ctx.eventBus, ctx.getState / setState.
Calculator
Ready-made packs
Don’t want to write tools? Use a toolkit (FileSystemToolkit, HttpToolkit, …) or MCP.
workspace: { path: "./data", mode: "read" } enables read-only filesystem tools for that folder; choose write mode explicitly when needed. See Harness.
Safety knobs (optional)
Agent-wide:
maxToolRoundtrips— stop after N tool loops (default 10)toolResultLimit: { maxChars: 20000 }— trim giant tool outputtoolRouter— pick a few tools when you have dozens
Tool result limits
Dynamic tools
Need different tools per user?toolResolver: async (ctx) => [...].
Need to change tools while running?