Tools

A tool is a function the model can call during a run. You describe it as a class implementing ITool: a name, a description, an optional input schema, and a handler. The agent loop exposes the tool to the model, validates the arguments the model supplies against your schema, runs your handler, and feeds the result back into the conversation.

Defining a tool

Implement ITool<P, R>, where P is the validated input and R is the handler’s return type. Register the class with decorator.tool():

import { inject } from "@talosjs/container";
import { Assert, type AssertType } from "@talosjs/validation";
import { decorator } from "@talosjs/ai";
import type { ITool } from "@talosjs/ai";

type WeatherInput = { city: string; units?: "metric" | "imperial" };

@decorator.tool()
class WeatherTool implements ITool<WeatherInput, Promise<string>> {
  public constructor(@inject(WeatherClient) private readonly client: WeatherClient) {}

  public getName = (): string => "get_weather";

  public getDescription = (): string =>
    "Get the current weather for a city. Returns a short human-readable summary.";

  public getInputSchema = (): AssertType =>
    Assert({
      city: "string > 0",
      "units?": "'metric' | 'imperial'",
    });

  public handler = async (param: WeatherInput): Promise<string> => {
    const report = await this.client.current(param.city, param.units ?? "metric");
    return `${report.summary}, ${report.temperature}°`;
  };
}

Add it to any agent’s getTools, or pass it per request:

public getTools = (): AiToolClassType[] => [WeatherTool];

// or, for a single call:
await chat.run<string>({ prompt: "Weather in Paris?", tools: [WeatherTool] });

The `ITool` contract

Member	Required	Purpose
`getName`	✅	Unique tool name the model uses to call it.
`getDescription`	✅	Plain-language description of when and how to use it; the model reads this.
`handler`	✅	Runs the tool. Receives the validated input, returns the result.
`getInputSchema`	—	ArkType assertion validating the model’s arguments before `handler` runs.
`onBeforeCall`	—	Hook that runs before the tool is invoked; can short-circuit the call.
`onAfterCall`	—	Hook that runs after the tool returns.

A clear getDescription and a precise getInputSchema are what make a tool reliable, because the model decides whether and how to call the tool entirely from those two. Describe the input fields in the schema and the tool’s purpose in the description.

Validated input

When getInputSchema is present, the agent loop validates the model’s arguments against it before your handler runs. Inside handler, the input already matches the schema, so there are no manual checks to write. The schema is an ArkType assertion built with Assert from @talosjs/validation:

public getInputSchema = (): AssertType =>
  Assert({
    query: "string > 0",
    "limit?": "number > 0",
    "tags?": "string[]",
  });

Omit getInputSchema for a tool that takes no arguments.

Call hooks

A tool can observe or gate its own invocation with two optional hooks. When any tool on a run declares either hook, the agent loop bridges them onto the run automatically.

`onBeforeCall`

Runs before the handler. Return a decision to allow, modify, or block the call, which is useful for permission checks or argument rewriting:

public onBeforeCall = (ctx, hookCtx) => {
  if (!ctx.context?.currentUser) {
    return { action: "deny", reason: "Authentication required" };
  }
  return { action: "allow" };
};

`onAfterCall`

Runs after the handler returns, for logging, metrics, or auditing:

public onAfterCall = async (ctx, info) => {
  await ctx.context.audit.write({ tool: this.getName(), result: info.result });
};

Both hooks receive the run’s ChatMiddlewareContext as their first argument, so they can read ctx.context, the runtime context passed to the call.

Built-in tools

The package ships ready-made tools for web search, Wikipedia, PubMed, and Linear. See Built-in Tools for the full catalog and the keys they need.

Getting Started

AI

Framework

Command Line

Defining a tool

The `ITool` contract

Validated input

Call hooks

`onBeforeCall`

`onAfterCall`

Built-in tools

​Defining a tool

​The ITool contract

​Validated input

​Call hooks

​onBeforeCall

​onAfterCall

​Built-in tools

Defining a tool

The `ITool` contract

Validated input

Call hooks

`onBeforeCall`

`onAfterCall`

Built-in tools