> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
last_verified: 2026-10-09
title: Tools
description: Define tools with tool() or the Tool class, give them a schema, and let agents call them
category: TypeScript SDK
hideRightSidebar: true
---

A tool is a function an agent can call. The model sees its name, description, and input schema, and decides when to call it. For a guided introduction, see [Tools](/docs/build/tools.md).

## `tool(name, options, handler)`

```typescript
import { tool } from '@agnt5/sdk';
import type { Context } from '@agnt5/sdk';

export const lookupOrder = tool(
  'lookup_order',
  {
    description: 'Look up an order by ID',
    inputSchema: {
      type: 'object',
      properties: { orderId: { type: 'string' } },
      required: ['orderId'],
    },
  },
  async (ctx: Context, input: { orderId: string }) => ({ orderId: input.orderId, status: 'shipped' }),
);
```

`tool()` registers the tool with the worker and returns a callable function. Give it to an agent in `tools`, call it yourself with `await lookupOrder(ctx, { orderId: 'A1' })`, or run it on its own:

```bash
agnt5 run lookup_order --type tool --input '{"orderId": "A1"}'
```

### `ToolOptions`

| Option | Description |
|---|---|
| `description` | What the tool does. The model reads it to decide when to call the tool. |
| `inputSchema` | JSON Schema for the tool's input. The model fills these arguments. |

The handler receives the [`Context`](/sdk/typescript/context.md) and the arguments the model chose, and returns a JSON-serializable result that goes back to the model.

`lookupOrder._tool.getSchema()` returns the schema the model sees:

```json
{
  "name": "lookup_order",
  "description": "Look up an order by ID",
  "input_schema": {
    "type": "object",
    "properties": { "orderId": { "type": "string" } },
    "required": ["orderId"]
  },
  "requires_confirmation": false
}
```

## `new Tool(name, description, handler, options?)`

Builds a tool object to give to an agent, without registering it with the worker:

```typescript
import { Tool } from '@agnt5/sdk';

const echo = new Tool(
  'echo',
  'Echo the text back',
  async (ctx: Context, input: { text: string }) => `echo: ${input.text}`,
  { inputSchema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] } },
);

const reply = await echo.invoke(ctx, { text: 'hi' });
```

## Give tools to an agent

```typescript
import { Agent, LM } from '@agnt5/sdk';

const orders = new Agent({
  name: 'orders',
  model: LM.openai(),
  modelName: 'openai/gpt-6-luna',
  instructions: 'Answer questions about orders. Use lookup_order.',
  tools: [lookupOrder, echo],
});
```

An `Agent` in `tools` is called as a tool named after the agent. See [Agents](/sdk/typescript/agents.md).

## Tools that wait for a person

`AskUserTool` and `RequestApprovalTool` pause the run until someone answers, so an agent can ask a question or request approval mid-loop. See [Human-in-the-loop tools](/docs/build/tools.md#human-in-the-loop-tools).

## Next steps

* [Agents](/sdk/typescript/agents.md): run the loop that calls tools.
* [Tools guide](/docs/build/tools.md): sandbox tools, MCP tools, and built-in tools.