Tools Reference

This page helps you find the exact name, risk tier, and behavior of a tool.

Every tool an agent can call, generated from the registry. Risk tiers determine what runs unattended — see Tools & approval for the mechanism and Security for the threat model.

This page is verified by a test (bun test packages/core/src/agent/tools/register-tools.docs.test.ts) that fails if the registry and this table drift apart. If you add a tool, update this page.

At a glance

Plus, registered per agent rather than globally:

How approval pairs work

Eight tools are gated: calling them does not act. They return a description of the intended action (including a preview diff for edits), and only after approval — from a human or from --approval-policy — does Jazz invoke the hidden execute_* counterpart.

flowchart LR
    M["Model calls<br/><code>write_file</code>"] --> P["Propose:<br/>resolve path, compute diff<br/><b>no mutation</b>"]
    P --> G{"Approved?"}
    G -->|yes| E["<code>execute_write_file</code><br/>actually writes"]
    G -->|no| D["Refusal returned<br/>to the agent"]

    classDef gate fill:#f9a03f,stroke:#b3541e,color:#1a1a1a
    classDef act fill:#4f9d9d,stroke:#2f6d6d,color:#ffffff
    class G gate
    class E act

You never call execute_* names yourself; they are hidden from the model’s tool list.

What each tool reveals

Risk is not the same question as disclosure. Risk asks what a tool can do to the machine; disclosure asks how freely its answer can be shared. The two do not correlate: read_file is read-only and can reveal anything, get_time is read-only and reveals nothing, write_file changes the machine and reveals nothing at all.

Every tool declares both. The field is required, with no default anywhere, so a new tool cannot be added without someone deciding.

A tool spanning two levels takes the more sensitive one — edit_file writes, but its approval message carries a diff of your file, so it is private. http_request reaches private networks including services on localhost, so it is too.

Skill tools (find_skills, load_skill, load_skill_section) are internal too, and are absent from the table for the same reason they are absent from the one below: they are registered per agent rather than globally.

There is no unknown level. MCP and custom tools are private, because a tool defined outside this codebase returns something this codebase cannot classify, and the safe reading of “unknown” is the most restrictive one.

The tools

File Management

Shell Commands

In the interactive terminal, an operator can also type ! <command>. That explicit shell escape uses the same cwd resolution, environment sanitization, denylist, timeout, interruption, and output caps as execute_command, then gives the result to the agent as context. It is not available through jazz run or remote chat surfaces.

Web Search

Web Fetch

HTTP

Todo

Memory

Opt-in per agent (like File Management) rather than always-on — see Memory.

update_work_state lives with the todo tools (always-on). It is scoped to one conversation and discarded when the task ends, unlike memory which persists across conversations — see Context management.

Workspace

Opt-in per agent (like Memory) rather than always-on. Deliberately separate from memory: memory is small, curated, one-file-per-topic notes; workspace is where large working drafts, research dumps, and intermediate artifacts live, referenced from memory rather than duplicated into it.

Reminders

Opt-in per agent. Reminders persist on disk and fire later on the same surface that scheduled them — see Reminders.

For CLI-hosted agents, add_reminder installs the same real one-shot host-scheduler job (launchd on macOS, an at job on Linux) used for wake triggers, so a reminder fires even if jazz daemon isn’t running; firing sends a native OS desktop notification instead of resuming a conversation — a reminder is “notify a person,” never “resume the agent.” jazz daemon’s in-process ticker remains a fallback for hosts with neither launchd nor at. Telegram and Discord reminders are unaffected by any of this: their bots already sweep and deliver reminders as chat messages from their own in-process interval, unchanged.

Wake Triggers

Opt-in per agent. A trigger causes the agent to actually run again with a given prompt, resuming the exact conversation it was scheduled from — unlike a reminder, which just delivers a note to a person. See Reminders for how the two compare.

register_trigger does not depend on jazz daemon running to actually fire. Registering a trigger installs a real one-shot job with the host’s own scheduler — a launchd job on macOS, an at job on Linux — that fires the trigger by invoking jazz directly at the scheduled time, even if nothing else is running. jazz daemon’s in-process ticker remains a fallback for platforms or environments with neither launchd nor the at binary available (most containers, some CI), and scheduling with the host is always best-effort: if it fails for any reason, registration still succeeds and the ticker is the safety net.

Background Jobs

Opt-in per agent. Runs several independent shell commands in the background with a concurrency cap and per-job retry/backoff, without blocking the agent’s turn. Completion (fan-in) resumes the conversation the same way a wake trigger fires, once every job in the batch reaches a final state, and the agent is told each job’s status and what it printed — a batch exists to find something out, so an exit code on its own would tell it nothing.

If that resumed turn needs an approval nobody is there to give, the run parks instead of dying: you get a desktop notification naming it, and jazz runs resume <id> finishes it. See tools and approval.

Context

Tool Search

Sub Agents

Perception Delegation

Always-on. Lets a text-only agent borrow eyes, ears, or a watch from a model that has them.

User Interaction

Web App

Opt-in per agent via tools. Used by chat bridges that can render a Mini App or a static image.

What is not a built-in tool

A common and consequential misreading. These capabilities exist, but not as built-in tools — they are skills that shell out through execute_command, which is unknown:

So a scheduled workflow set to autoApprove: low-risk cannot archive an email — every himalaya invocation is declined. The fix is usually not to raise the whole tier to high-risk (which also unlocks rm and git push), but to allowlist the specific binary:

// ~/.jazz/config.json
{ "autoApprovedCommands": ["himalaya", "khal"] }

That keeps the tier low while letting the one command through. Matching is on a parsed key (binary + first subcommand), never a raw prefix — see Tools & approval.

Notes

• find vs grep — find locates files by name, glob, or path pattern. grep searches inside file contents. Non-overlapping on purpose.
• execute_command classifier. The tool is unknown, so a harness-model classifier labels each command read-only, low-risk, or high-risk and the active tier judges that verdict: --approval-policy read-only auto-approves an inspect-only command, an interactive session skips its prompt, yolo skips the classifier entirely. The live zone shows classifying while it runs, and the verdict is printed on the settled receipt. It sees the last five user requests (800 characters) on an interactive session and the command alone everywhere else — never the assistant’s own turns. Timeouts and ambiguous replies stay high-risk. See Tools & approval.
• http_request is read-only by risk classification even though it can issue POSTs. It reaches whatever URL the agent targets; network policy belongs at the firewall, not the tier. Treat it accordingly on surfaces that accept untrusted input.
• Timeouts — 3 minutes by default per tool. ask_user_question and ask_file_picker are longRunning and never time out, because waiting for a human is not a hang.
• Concurrency — up to 10 tools execute in parallel per iteration.
• create_pdf needs a browser too — same puppeteer-core path as create_web_app’s static mode, rendering through page.pdf(). It writes to the agent’s working directory by default (an explicit path overrides), unlike create_web_app, whose output lands in Jazz’s own data directory because only a bridge ever reads it.
• create_web_app needs a browser for mode: "static" — it screenshots the page through puppeteer-core, which deliberately ships no bundled Chrome so that installing Jazz never downloads one. It uses PUPPETEER_EXECUTABLE_PATH if set, otherwise an installed Google Chrome; with neither it fails and says so. mode: "interactive" needs no browser.

Related

• Tools & approval — the execution and gating machinery
• Concepts: tools — what a tool is and how to add one
• CLI Reference — --approval-policy and friends
• Configuration — customTools, envAllowlist, autoApprovedCommands