Skip to main content

Tools

The agent acts through tools. Each tool has a default decision: allow runs it, ask waits for a person. A Rule changes the default, and Permissions explains how. This page lists the tool names, so you can write a Rule without looking them up first.

wisp permissions get shows the tools you are likely to write a Rule for, with the decision that applies now. It leaves out the agent's own mechanics: memory_*, preference_*, diagnostics_read, skill_*, spawn_agent, and a connector's list_resources, read_resource, list_prompts and get_prompt. A Rule for any of them still works.

Files​

The file tools work in the Session's folder: its Project, or, for a Session without a Project, a folder of its own under ~/Wisp.

ToolWhat it doesDefault
fs_readreads a text file; a PDF, .docx, .xlsx or .pptx is turned into textallow
fs_read_mediashows the agent an image: PNG, JPEG, GIF or WebPallow
fs_listlists files and foldersallow
fs_globfinds files by name patternallow
fs_grepsearches file contentsallow
fs_writecreates or overwrites a fileask
fs_editreplaces exact text in a fileask
deliver_filesends you a file from the folder, attached after the answer; see Voice and filesallow
generate_imagemakes a picture from a description and saves it in the folder as a JPEG; see Pictures the agent makesallow

How far they reach follows the sandbox switch:

  • Sandbox on: a path outside the folder is refused.
  • Sandbox off, the default: a path outside the folder is allowed, but every such call asks, on a card that names where it lands, whatever the Rules say. Under wisp run it is refused.

generate_image is the exception: its path must stay inside the folder whatever the switch, and a path outside it is refused, never asked.

Either way some paths are always refused: Wisp's data directory (~/.wisp), the Project's own .wisp/ (except .wisp/mcp.json, which can be read), .env files (.env.example, .env.sample and .env.template excepted), /etc, and the secrets in your home folder, such as ~/.ssh, ~/.aws, ~/.gnupg, ~/.npmrc, ~/.gitconfig, shell history and the macOS Keychain.

Shell​

ToolWhat it doesDefault
bash_runruns a shell command, in a sandboxask

Read bash_run before you allow it: the sandbox is off by default, and once on it keeps a command inside its folder, but its network is on. By default a command stops after 30 seconds (bashTimeout) and its output is cut at 100,000 characters (bashMaxOutput); the agent can set either for one command.

Schedules​

The agent can make a scheduled job from a chat: "every weekday at nine, summarise my inbox".

ToolWhat it doesDefault
schedule_createcreates a jobask
schedule_updatechanges a jobask
schedule_deletedeletes a jobask
schedule_listlists the jobsallow
schedule_pausepauses a joballow

These tools differ from the rest in two ways:

  • They are offered only to a Run a person can answer. A Run in the policy mode, which is the default for wisp run and /v1, and every Run a job fires, does not see them at all, whatever the Rules say.
  • Creating, changing or deleting a job asks every time. A Rule or a Project bypass that says allow is still an ask for these three. A deny is still a deny.

A Run from a chat sees only that chat's jobs.

Skills​

ToolWhat it doesDefault
skill_invokeruns a Skill by nameallow
skill_fs_readreads a file of a Skillallow
skill_fs_listlists Skills, or the files of oneallow
skill_fs_writecreates or changes a file of a Skillallow
skill_fs_deletedeletes a file of a Skill, or the whole Skillask
The agent writes Skills without asking

skill_fs_write defaults to allow. The agent can create or change a Skill in ~/.wisp/skills/<name>/, which every Project sees, or in the Project's .settings/skills/<name>/, and no one is asked. A Skill it writes there is offered to later Runs too. Built-in Skills cannot be changed. To be asked first:

wisp permissions set skill_fs_write ask

Memory and other agent tools​

ToolWhat it doesDefault
memory_storesaves a memory, tied to this Session or kept for goodallow
memory_recallfinds memories by text, tag or typeallow
memory_updatechanges a memoryallow
memory_deletedeletes a memoryallow
memory_get_allreads every memory, with no filterask
preference_getreads a stored preference of the userallow
preference_setstores a preference of the userallow
spawn_agentstarts a subagent for part of the taskallow
diagnostics_readreads the Runtime's recent errors and warningsallow
recording_listlists meeting recordingsallow
recording_readreads a recording's transcriptallow
recording_searchsearches recordings for a topicallow
recording_deletedeletes a recording and its transcriptask

The agent also remembers on its own. After each turn in which it stored nothing itself, the Runtime asks the model what in the turn is worth keeping and saves that. Before each turn it adds the memories and preferences that look relevant, from every Session and Project, and points the agent at recordings that do. A memory the agent marks project is not limited to the Project: it is offered everywhere, and it is deleted with the Session that stored it. A global one stays until it is deleted.

A subagent can use every tool the agent has, writing files included, unless the agent narrows it to the read tools and bash_run. Its tool calls go through the same Rules as the agent's own. It has no step or time limit by default; subagentTimeoutMs in the configuration sets a time limit.

Connector tools​

Each connector adds its own tools, named mcp__<connector>__<tool>. Every one of them defaults to ask, whatever the server says about it.

A connector whose server offers resources or prompts also gets four tools that default to allow:

  • mcp__<connector>__list_resources
  • mcp__<connector>__read_resource
  • mcp__<connector>__list_prompts
  • mcp__<connector>__get_prompt

wisp permissions get --connector <name> lists one connector's tools.

How the agent reaches them​

Connector tools are not in the agent's own tool list, so that dozens of them do not crowd its context. The agent gets a short catalog of them and two tools to use it:

  • mcp_search finds connector tools by what they do and returns each one's arguments.
  • mcp_call runs one connector tool by its name.

So in Wisp Desktop and in the audit log you may see the agent search before it acts. The first call of a tool whose arguments the agent has not read yet is not run: it gets the tool's arguments back and calls again. That refused call is expected and changes nothing.

Rules, approval cards and the audit log still use the connector tool's own name, mcp__<connector>__<tool>, never mcp_call. The web tools of wisp_proxy are the exception: they are in the agent's own list and called directly.

A subagent or a fork Skill that is given a list of tools reaches connectors only when the list names mcp_call or mcp_search; then it can use every connector tool its Project enables. With no list, it gets them as the agent does.

Web search and fetch​

The agent reaches the web through the Wisp proxy's own connector, wisp_proxy. It needs no wisp connectors add and no enable, and wisp connectors list does not show it. Its tools:

ToolWhat it doesDefault
mcp__wisp_proxy__brave_searchsearches the webask
mcp__wisp_proxy__fetch_urlfetches a page as textask
mcp__wisp_proxy__curlsends any HTTP request, POST and DELETE among themask

Like every connector tool they ask, so under wisp run the agent cannot search the web until a Rule allows it. Allow the two that read:

wisp permissions set mcp__wisp_proxy__brave_search allow
wisp permissions set mcp__wisp_proxy__fetch_url allow
warning

wisp permissions allow-connector wisp_proxy allows mcp__wisp_proxy__curl as well, and that lets the agent send data to any address. Allow the tools one by one unless you mean it.

mcp__wisp_proxy__brave_search is there only when the proxy has search set up. wisp permissions get --connector wisp_proxy shows what your proxy offers.