<!-- Tools · Tin · https://tin.ad/docs/learn/tools/ · generated from the built page -->

[Learn](https://tin.ad/docs/learn/) · Agents · 16 of 34

# Tools

**Goal.** Give an agent tools, and see how their schemas come from your types.

## A tool is a function

Write `tool fn` instead of `fn` and list the function in an agent's `tools`.
Now the model can call it. It's still an ordinary function, so you can call it yourself too.

*first-tool.tin · tin run first-tool.tin*

```tin
/// Add two integers.
tool fn add(a: int, b: int): int => a + b

agent Calculator {
  model: "mock"
  system: "Use the tools for every calculation."
  tools: [add]
}

fn main() {
  print(add(2, 3))                       // a tool fn is still an ordinary function
  print(Calculator("please add 19 and 23"))
}
```

<!-- output -->
```text
5
mock: 42
```

The mock calls every tool your prompt mentions by name, and fills the arguments from the numbers in the prompt,
in order. A real model reads the descriptions and decides for itself.

## The agent loop

When an agent has tools, one call runs a loop: ask the model, run the tools it asks for, send back the
results, ask again, until the model answers with text. `on toolCall` and `on toolResult`
let you watch each step:

*events.tin · tin run events.tin*

```tin
/// Add two integers.
tool fn add(a: int, b: int): int => a + b

/// Multiply two integers.
tool fn times(a: int, b: int): int => a * b

agent Calculator {
  model: "mock"
  tools: [add, times]

  // handlers run while the agent loop runs
  on toolCall(name, input) => print("  call   {name} {input}")
  on toolResult(name, output, ok) => print("  result {name}: {output}")
}

fn main() {
  print(Calculator("times 6 and 7"))
}
```

<!-- output -->
```text
  call   times {"a":6,"b":7}
  result times: 42
mock: 42
```

If the model asks for several tools in one reply, they run at the same time.

## Schemas come from your types

A model needs to know each tool's name, what it does, and the shape of its arguments as a JSON Schema. In
Tin, you never write that schema. The compiler derives it from the signature, and the `///` comments
become descriptions. `tin tools` shows what the model will see:

*schema.tin · tin tools schema.tin*

```tin
type Unit = | Celsius | Fahrenheit

/// Look up the weather for a city.
tool fn weather(
  /// City name, for example "Istanbul"
  city: string,
  unit: Unit,
  /// How many days ahead (0 = today). Optional.
  days: Option<int>,
): string => "sunny in {city}"

fn main() {}
```

<!-- output -->
```text
[
  {
    "name": "weather",
    "description": "Look up the weather for a city.",
    "schema": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "City name, for example \"Istanbul\""
        },
        "unit": {
          "type": "string",
          "enum": [
            "Celsius",
            "Fahrenheit"
          ]
        },
        "days": {
          "type": "integer",
          "description": "How many days ahead (0 = today). Optional."
        }
      },
      "required": [
        "city",
        "unit"
      ],
      "additionalProperties": false
    }
  }
]
```

Look at what came from where:

- The sum type `Unit` became a string limited to `"Celsius"` or
`"Fahrenheit"`. The model can't send anything else.

- The `Option<int>` parameter is left out of `required`, so the model may skip
it. Every other parameter is required.

- Rename a parameter or change its type and the schema changes with it, because it's generated from the
code.

Before a tool runs, its arguments are checked against the schema. If the model sends the wrong
shape, the tool doesn't run. The model gets told which argument was wrong.

## When a tool fails

Return a `Result` for failures you expect. An `Err` isn't a crash: it goes back to the
model as a failed call, and the model decides what to do next.

*failing-tool.tin · tin run failing-tool.tin*

```tin
/// Divide one integer by another.
tool fn divide(a: int, b: int): Result<int, string> {
  if b == 0 { return Err("cannot divide by zero") }
  Ok(a / b)
}

agent Calculator {
  model: "mock"
  tools: [divide]
  on toolResult(name, output, ok) => print("  {if ok { "ok" } else { "failed" }} {name}: {output}")
}

fn main() {
  print(Calculator("divide 10 by 2"))
  print(Calculator("divide 10 by 0"))      // an Err goes back to the model; the program keeps going
}
```

<!-- output -->
```text
  ok divide: 5
mock: 5
  failed divide: cannot divide by zero
mock: error: cannot divide by zero
```

A panic inside a tool, such as dividing by zero, is handled the same way: the model sees a failed call, and
your program keeps running.

## What a tool can take

Tool parameters and results must be plain data: numbers, `bool`, `string`,
`Duration`, arrays, structs, sum types and `Option`. A function can't be sent to a model:

*not-data.tin · tin check not-data.tin*

```tin
/// Run a function twice.
tool fn twice(f: (int) => int, x: int): int => f(f(x))

fn main() {}
```

<!-- compiler output -->
```text
error: a (int) => int cannot cross the agent boundary — tool parameters, tool results and typed agent replies must be plain data
 --> not-data.tin:2:15
  |
2 | tool fn twice(f: (int) => int, x: int): int => f(f(x))
  |               ^^^^^^^^^^^^^^^
```

And a tool can't be generic, because a model needs one concrete schema:

*generic.tin · tin check generic.tin*

```tin
/// The first item.
tool fn firstOf<T>(xs: T[]): T => xs[0]

fn main() {}
```

<!-- compiler output -->
```text
error: a tool fn cannot be generic: the model needs one concrete schema
 --> generic.tin:2:1
  |
2 | tool fn firstOf<T>(xs: T[]): T => xs[0]
  | ^^^^^^^^^^^^^^^
```

## Tasks

### Task 1: Another tool

Give the calculator a `subtract` tool, then ask it to "subtract 10 and 3" and print each call.

Your answer   Checking needs JavaScript; the solution below works without it.

**Solution

*task-1.solution.tin · tin run task-1.solution.tin*

```tin
/// Add two integers.
tool fn add(a: int, b: int): int => a + b

/// Subtract b from a.
tool fn subtract(a: int, b: int): int => a - b

agent Calculator {
  model: "mock"
  tools: [add, subtract]
  on toolCall(name, input) => print("  call {name} {input}")
}

fn main() {
  print(Calculator("subtract 10 and 3"))
}
```

<!-- output -->
```text
  call subtract {"a":10,"b":3}
mock: 7
```

### Task 2: Design a schema

Write a tool `addTodo` with a title, a priority (`Low`, `Normal` or
`Urgent`) and an optional due date, so that the model can't send a priority you don't support. Check
the schema with `tin tools`.

**Solution

*task-2.solution.tin · tin tools task-2.solution.tin*

```tin
type Priority = | Low | Normal | Urgent

/// Add a todo item.
tool fn addTodo(
  /// What needs doing
  title: string,
  priority: Priority,
  /// Optional due date, as YYYY-MM-DD
  due: Option<string>,
): string => "added {title}"

fn main() {}
```

<!-- output -->
```text
[
  {
    "name": "addTodo",
    "description": "Add a todo item.",
    "schema": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "description": "What needs doing"
        },
        "priority": {
          "type": "string",
          "enum": [
            "Low",
            "Normal",
            "Urgent"
          ]
        },
        "due": {
          "type": "string",
          "description": "Optional due date, as YYYY-MM-DD"
        }
      },
      "required": [
        "title",
        "priority"
      ],
      "additionalProperties": false
    }
  }
]
```

## Recap

- A `tool fn` is a function a model may call.
- Its JSON schema is generated from the signature and `///` docs.
- A failing tool sends the error back to the model, not to you.

In the reference: [Tools](https://tin.ad/docs/ref/agents/#tools) · [What the model sees back](https://tin.ad/docs/ref/agents/#tool-results) · [How types become schemas](https://tin.ad/docs/ref/agents/#schemas)
