Give your agent tools

Tools are extra powers, like running a command or calling a website. Here is how to add them.

On its own, an agent can only think and talk. Tools give it powers: reading a file, running a command, or calling a website. This guide shows the built-in tools and how to make your own.

Tools can also come from explicitly selected, trusted MCP servers. See MCP guide for namespacing and approval policies.

Built-in tools

Some tools come ready to use. Just list them under tools:

agent writer
  model: anthropic/claude-sonnet-5
  tools:
    - fs_read
    - fs_write
  instructions: |
    Read notes.md, improve it, and save it back.

Tool	What it does
`fs_read`	Read a file.
`fs_write`	Write a file.
`fs_list`	List the files in a folder.
`bash`	Run a command in the terminal.

These all work inside the agent's sandbox, which keeps them safe.

Make your own tool

You can add your own tools with a tool block. There are two kinds: one that runs a command, and one that calls a website.

A command tool

Use type: shell to run a command. This one returns the current year:

tools.nt

tool current_year
  description: Returns the current four-digit year.
  type: shell
  command: date +%Y

Then let an agent use it by name:

agent age
  tools:
    - current_year

A website tool

Use type: http to call a web address:

tool lookup
  description: Looks up a record by its id.
  type: http
  url: https://api.example.com/records/{id}

Filling in the blanks

The {id} and {term} parts in curly braces are placeholders. The agent fills them in when it uses the tool. For example:

tool search_notes
  description: Searches the notes file for a word.
  type: shell
  command: grep -n "{term}" notes.md

When the agent runs this tool with the word "iPhone", NT replaces {term} with iPhone before running the command.

What a tool needs

Setting	What it does
`description`	Tells the agent when to use the tool. Defaults to its name.
`type`	`shell` (default) to run a command, or `http` to call a website.
`input`	Declares and validates the values available to `{placeholders}`.
`command`	Command template for a `shell` tool. Model values are inserted as shell literals.
`url`	URL template for an `http` tool. Model values are percent-encoded.
`method`	HTTP method. Defaults to `GET`; non-GET/HEAD calls send the input object as JSON.
`headers`	Extra HTTP headers. They are withheld if model input changes the URL origin.
`allow_internal`	Permit private or loopback HTTP destinations. Defaults to `false`.
`confirm`	`true` to ask in the terminal before every call. Defaults to `false`.

The description matters

The agent decides when to use a tool by reading its description. A clear description like "Returns the current year" helps it pick the right tool at the right time.

HTTP tools accept only http or https, refuse redirects, cap response bodies, and block private, loopback, link-local, multicast, and unsafe DNS results by default. Set allow_internal: true only for a reviewed internal service.

Ask before running

Some tools deserve a human in the loop — a shell command, or an http call that changes something. Add confirm: true and the run stops and asks before every call:

tool deploy
  description: Deploy the current build to production.
  type: shell
  command: ./deploy.sh
  confirm: true

⚠ age wants to run deploy({})
❯ Yes, run this tool
  No, deny it (esc)

Move with the arrow keys and press Enter, or answer directly with y or n; Esc denies. A denied tool is refused — the agent is told the call was denied and carries on without it. Pass --yes (or -y) to pre-approve every gated tool for that run. When there is no one to ask — say, output piped to a file — gated tools are always refused, never silently run.

Set up a sandbox

Control where tools can read and write.

Add a skill

Give your agent a reusable checklist.