Skip to content

Create a tool

DuckTapeKiller edited this page Sep 13, 2026 · 1 revision

A tool lets the model do something: look something up, run a program, change a file. Dive has three ways to add one, and Pi mode has a fourth. This page helps you choose.

If what you want is a way of working, such as a checklist, a house style or a procedure, you don't need a tool. Write a skill instead.

The options side by side

Custom tool External tool MCP server pi extension
What it is A shell command or a JavaScript snippet typed into Settings A Node.js module in ~/dive/plugins A separate program that speaks the Model Context Protocol An extension for pi
Where you set it up Settings > TOOLS > MANAGE CUSTOM TOOLS A folder or .js file in ~/dive/plugins Settings > TOOLS > MCP SERVERS ~/.pi/agent/extensions or a pi package
Modes Only the mode you create it in llama.cpp, LM Studio, Ollama and Cloud, with a switch in each llama.cpp, LM Studio and Ollama; the section isn't shown in Cloud Pi
Inputs the model is shown None: the model only has your description The JSON Schema you write The server's own schema The schema you give pi
Asks for permission Shell: every time. JavaScript: never Only if it sets requiresConfirmation Never Up to the extension
Time limit Shell: 5 seconds. JavaScript: 10 seconds 60 seconds by default, from 1 second to 60 minutes Dive sets none Up to pi
Slash command No Yes No Yes, as a pi command
Usable in other apps No No Yes, in any MCP client No
What it can reach Shell: anything, once you allow it. JavaScript: Node.js built-in modules Everything, because it runs inside Dive's server Whatever the program does Everything pi can reach

Which one to use

  • A custom tool is the quickest: wrap a command-line program, or a few lines of JavaScript, for one mode. The model isn't shown any declared inputs, so describe the inputs in the tool's description and keep them simple. See Create a custom tool.
  • An external tool is a proper tool: typed inputs, a slash command, an optional permission prompt, a longer time limit, and a switch in every mode. You write it in JavaScript for Node.js. See Create an external tool.
  • An MCP server makes sense when the tool you want already exists as one, or when you want the same tool in Claude Code and other MCP clients. See Connect an MCP server.
  • A pi extension is the only way to add a tool to Pi mode, because Dive's own tools don't reach pi. pi's extension documentation covers pi.registerTool(), and Pi mode explains where pi loads extensions from.

When two tools have the same name

Dive looks for a native tool first, then an external tool, then a custom tool, and runs the first it finds. MCP tools can't clash with these, because their names always start with mcp__.

Read next

Clone this wiki locally