Tools

When you type a message to an AI, it generates text. That’s it: on its own, it can only produce words. But words aren’t always enough. Sometimes you need the AI to actually do something: read a file, run a command, or look up live data.

That’s what tools are for. A tool is a function the AI can call when it decides one is needed. It recognizes the situation, picks the right tool, runs it, and uses the result to give you a better answer. This is sometimes called “function calling” or “tool use.”

Pi’s built-in tools

Four tools are on by default:

Three more ship with Pi but are off by default, since bash can already do the same jobs:

On Windows there’s also an optional powershell tool.

Choose which tools Pi can use

The defaultTools setting in ~/.pi/agent/settings.json (or a project’s .pi/settings.json) controls which tools are on when Pi starts. Entries starting with + or - adjust the defaults instead of replacing them:

{
  "defaultTools": ["+grep", "+find"]
}

That keeps read, bash, edit, and write, and adds grep and find. Run /reload to pick up the change.

For a single run, use command-line flags:

A read-only run is a handy pattern when you want Pi to look at something without being able to change it:

pi --tools read,grep,find,ls -p "Summarize what this folder contains"

Two more: codemode and tool_search

Pi’s built-in extensions add two more tools, both off by default:

• codemode lets the model write a short JavaScript program that calls other tools, for example several reads in parallel, and only sends the program’s output back to the model.
• tool_search finds tools the model hasn’t been shown yet and loads the ones it needs.

Pi turns these on automatically when an MCP server needs them. The next two lessons cover both: first MCP, then Code mode.