Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tools

Tools the on-device model can call. Each page gives the model-facing contract (name, description, arguments, result format) and the limits that protect the context window. wisp tools prints the live list.

ToolPurpose
current_dateThe date and time; the model has no clock.
run_commandRun a shell command in the sandbox, with a timeout and bounded output; with outsideSandbox, one command the sandbox refuses, run without it once the person approves that run.
read_fileRead a text file one page at a time.
edit_fileWrite, append to, or replace text in a file, inside the sandbox’s writable set.
inspectwisp’s own config, status, approvals, recent audit events (by turn too), and a turn’s tool calls one line each; read-only.
notifyShow the user a macOS notification; bounded, rate-limited, audited, no approval.
custom toolsYour own tools: command templates with typed arguments, declared in ~/.wisp/config.json.
system_infoPorts, free space, folder sizes, busy processes, memory, one process, battery, macOS, network; read-only.
memoryThe conversation’s memory (not RAM): recall an earlier entry, turn, the task, the summary, a fact’s history, or a stored output the model saw only in part (filtered by pattern, range, head, or tail), for one turn; summarise a stored output by exact readers; condense it with a question the model answers over all of it; note a fact, or propose the task, as the model. Off by default: context.memory turns it on.
modelsThe models wisp can run: list and show at once; pull (in the background), enable, disable, and check only once the person approves; trust and switch are the person’s. Off by default: tools.models turns it on.
askOne question to the person mid-turn: free text, or a choice of two to six options; never a permission, never a secret. Waits until answered in chat and wisp-tui; under wisp mcp the turn parks after 60 s and the answer reaches the next turn. Off by default: tools.ask turns it on.

Select tools per session with --tool <name> on the CLI or the tools argument of MCP respond. Every registered tool’s schema is in the prompt on every turn, so enable only what a task needs. All the tools, the default, are every registered tool but memory, models, and ask, which join them when context.memory, tools.models, and tools.ask are on; a named list has any of them only when it names it (memory.md, models.md, ask.md), and tools.disabled can leave any out everywhere.

MCP clients discover these tools through the wisp://tools resource, generated from the registry; the limits and example prompt for each come from the tool itself (WispTool.limits, rendered from its live options, and WispTool.examplePrompt). See ../mcp.md.

Adding a tool

To give the model a command you use often, declare a custom tool in your config; no build is needed (custom.md). To add a built-in tool to wisp itself:

  1. Add a struct conforming to WispTool under harness/Sources/WispCore/Tools/, with an @Generable Arguments type, @Guide descriptions on each property, limits rendered from its options, and an examplePrompt that names the tool.
  2. Keep the work in a pure helper (like CurrentDateTool.format or FileReader) and test that.
  3. Bound the result to the tool-output budget: page it, or pass it through ToolOutput.fitted with the registry’s ToolBudget and OutputStore, so what does not fit is kept and marked rather than dropped (ADR 0050). See ../context-management.md.
  4. Append it to ToolRegistry.init; it is wrapped by AuditedTool there.
  5. Add a page here and a row above. The description is prompt text; write it for the model.