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

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

# Capabilities

**Goal.** Read the report of what each agent can reach before you run it.

Before you let a model loose, you want to know what it can actually do. In most languages you read every tool
and guess. In Tin the compiler already knows, because it has followed every call. `tin caps` prints
it.

## What each agent can reach

*shop.tin · tin caps shop.tin*

```tin
/// Look up a price, in cents.
tool fn price(item: string): int => 300

/// Today's date, for the receipt.
tool fn today(): string => "{now()}"

/// Charge a card. A person approves every charge.
guarded tool fn charge(card: string, cents: int): string => "charged {cents}"

/// Answers questions about the menu. Read-only.
agent Menu { model: "mock", tools: [price] }

/// Takes orders and charges for them.
agent Till { model: "mock", tools: [Menu, today, charge] }

fn main() {
  print(Till("charge 'visa' 300"))
}
```

<!-- output -->
```text
agent Menu
  tools:           price
  can call freely: price
  needs approval:  nothing
  capabilities:    model

agent Till
  tools:           Menu (agent), today, charge (guarded)
  can call freely: price, today
  needs approval:  charge
  capabilities:    model, clock

tools
  price   free     pure
  today   free     clock
  charge  guarded  pure

main
  capabilities:    clock, model, output
```

Read it from the bottom up:

- **tools**: each tool is `free` or `guarded`, plus what it does to the
outside world. `today` reads the clock, while `price` and `charge` are pure
(here they're stand-ins).

- **agent Till** was given `Menu`, `today` and `charge`. It can
also call `price` freely, through `Menu`. The report counts what's reachable, not just
what's listed.

- `charge` appears under *needs approval*, because it's guarded. Chapter 18 showed that the
compiler makes sure nothing gets around that.

## Touching the outside world

The capabilities come from the built-in functions a tool can end up calling: `fetch` means
`net`, `env` means `env`, `print` means `output`,
`now` and `sleep` mean `clock`, and calling an agent means `model`.

*fetch.tin · tin caps fetch.tin*

```tin
/// Read a web page.
tool fn readPage(url: string): string => fetch(url).or("")

/// Read an environment variable.
tool fn setting(name: string): string => env(name)

agent Browser { model: "mock", tools: [readPage] }
agent Ops { model: "mock", tools: [setting] }

fn main() {}
```

<!-- output -->
```text
agent Browser
  tools:           readPage
  can call freely: readPage
  needs approval:  nothing
  capabilities:    model, net

agent Ops
  tools:           setting
  can call freely: setting
  needs approval:  nothing
  capabilities:    model, env

tools
  readPage  free     net
  setting   free     env
```

Because Tin has no global variables and tool arguments are plain data, a tool can only run code its body
names. That's why this report is exact rather than a best guess.

## Who can reach a function?

Turn the question around with `tin caps file.tin --reach charge`. For this program:

*reach.tin · tin caps reach.tin --reach charge*

```tin
/// Look up a price, in cents.
tool fn price(item: string): int => 300

/// Charge a card. A person approves every charge.
guarded tool fn charge(card: string, cents: int): string => "charged {cents} to {card}"

agent Menu { model: "mock", tools: [price] }
agent Till {
  model: "mock"
  tools: [Menu, charge]
  on toolCall(name, input) => print("  {name} {input}")
}

fn main() {
  print(Menu("price of 'tea'"))
  print(Till("charge 'visa' 300"))
}
```

<!-- output -->
```text
agents that can reach charge:    Till
functions that can reach charge: main
```

Only `Till` can, and `main` reaches it through `Till`. `Menu`
can't, whatever its model decides.

Not yet: capabilities are worked out and reported, but you can't yet write "this agent may not
use the network" and have the compiler enforce it. Today you read the report, or put it in a test.

## Tasks

### Task 1: Predict the report

An agent `Forecaster` has a tool that calls `fetch`, and an agent `Notes`
has a tool that calls `print`. Which capabilities does `tin caps` list for each? Write it
and check.

**Solution

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

```tin
/// Read the weather for a city.
tool fn weather(city: string): string => fetch("https://example.com/weather?city={city}").or("unknown")

/// Remember a note.
tool fn note(text: string): string {
  print("note: {text}")
  "saved"
}

agent Forecaster { model: "mock", tools: [weather] }
agent Notes { model: "mock", tools: [note] }

fn main() {}
```

<!-- output -->
```text
agent Forecaster
  tools:           weather
  can call freely: weather
  needs approval:  nothing
  capabilities:    model, net

agent Notes
  tools:           note
  can call freely: note
  needs approval:  nothing
  capabilities:    model, output

tools
  weather  free     net
  note     free     output
```

### Task 2: Split the power

Change the shop so that `Till` can only reach `charge` through a separate
`Cashier` agent. Does that change what `Till` needs approval for?

**Solution

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

```tin
/// Look up a price, in cents.
tool fn price(item: string): int => 300

/// Charge a card. A person approves every charge.
guarded tool fn charge(card: string, cents: int): string => "charged {cents}"

/// Takes orders. It can no longer charge on its own: the Cashier does that.
agent Till { model: "mock", tools: [price, Cashier] }

/// Charges cards, after a person approves.
agent Cashier { model: "mock", tools: [charge] }

fn main() {}
```

<!-- output -->
```text
agent Till
  tools:           price, Cashier (agent)
  can call freely: price
  needs approval:  charge
  capabilities:    model

agent Cashier
  tools:           charge (guarded)
  can call freely: nothing
  needs approval:  charge
  capabilities:    model

tools
  price   free     pure
  charge  guarded  pure
```

No. `Till` can still reach `charge` through `Cashier`, so it
still appears under *needs approval*. Moving a tool behind a sub-agent changes who asks, not what can
happen.

## Recap

- `tin caps` lists every tool, sub-agent and outside effect per agent.
- Network, files and JavaScript are capabilities the report names.
- You can ask who can reach any function.

In the reference: [Capabilities](https://tin.ad/docs/ref/agents/#capabilities) · [The compiler checks the approval path](https://tin.ad/docs/ref/agents/#proof)
