Tools

Tools are how an agent acts in Mod: read_document, patch_document, create_task, comment, set_view and the rest. Mod builds one tool set for each session and serves it to every harness, whichever agent and model you use. Packages can add tools of their own.

How it works

A session's tool set is built when the session runs, from Mod's tools plus the tools of the packages installed for it. Every harness gets the same set in the form it expects: Claude Code over MCP, Codex natively, Cursor through an MCP server it starts, and Pi through an extension.

Every tool call goes through the session's log. The call is written first. A worker claims it by writing the start of its result, runs it, and writes the result back. A call that already has a result is never run again. See workers.

A tool that changes a document writes to that document's history, so the change syncs, names who made it, and can be undone. A tool that writes, such as patch_document, create_task or publish_branch, is held back when nobody is there to approve it. Instead the agent asks, and the person can answer from any surface, including the phone.

Package tools come in two kinds today.

App tools. An app can declare commands that change its own records, so an agent can use the app without its view on screen. They run outside Mod's own process, one short-lived process per call, and can reach only the records of the app's data type. Their names start with that data type, such as review_go_to_stop, so two apps can both have a search. To keep each session's tool list short, an app's tools appear by name only when the app is in play for that session. Every other installed app is reached through run_app_tool, which lists an app's tools and runs one.

Connectors. A connector is a package that holds your sign-in to an outside service, such as Slack. You connect it once, and every session in the World can use its tools, such as slack_read_channel and slack_send_message. The credential stays on your machine. It is never in a document, a release or the log. The connector's code runs in its own process and can reach only the hosts it declared, and the token is added to its requests on the way out, so the code never sees it. An installed connector you have not connected still shows its tools, and they tell the agent to connect it first.

Using it as you build

The tools an agent has fall into a few groups:

• Documents and files: read_document, create_document, patch_document, update_document, list_documents, search, save_file.
• Work: create_task, update_task, complete_task, comment, create_reminder.
• Sessions: start_session, send_message, read_session, list_sessions, answer_question.
• The window: set_view, read_view, and the browser tools such as browser_open, browser_read and browser_click.
• Packages and history: install_package, publish_package, save_version, restore_version, read_history.
• From a VM to your Mac: run_recipe, publish_branch, merge_pr, forward_mac_port. See VMs.

To give an agent new tools, declare them in your app's package as package tools, under the manifest's worker field. Each tool says whether it reads or writes, and the declaration is what a person sees before installing. Mod reads it from the manifest, never by running your code:

"mod": {
  "name": "Review",
  "dataType": "review",
  "worker": {
    "entry": "dist/worker.js",
    "tools": [
      {
        "name": "go_to_stop",
        "description": "Move the review to one stop",
        "input": { "type": "object", "properties": { "stop": { "type": "number" } } },
        "effects": "write"
      }
    ]
  }
}

The module at entry exports tools, keyed by the same names. The field is called worker for historical reasons; it has nothing to do with the workers that run sessions. mod-next app push builds it and publishes it with the app, and a release published to the registry carries it too. See packages for the rest of the manifest.

Limits

• Connectors call outside services over their APIs. A connector built from a remote MCP server, or from a command-line tool that holds its own sign-in, is not built. soon
• A connector's sign-in is kept on the machine that connected it, so each machine connects once.
• Macros: a flow your agent keeps repeating, written by the agent and saved as one tool call. soon