Built-in Tools

Every tool the stella agent can call in every session. Covers the shell, file create/read/update/delete, code search, sub-agent delegation, the task board, scratch state, and the environment probe, and notes which ones are read-only.

stella ships a small built-in surface: 18 tools. They cover the shell, file create/read/update/delete, code search, sub-agent delegation, the session task board, scratch session state, and the session environment. The surface stays small on purpose. It's the set of actions the agent needs to do work in a repository, and nothing more. Everything else the agent can do comes from custom script tools you define, and from tools merged in from MCP servers. Every tool, built-in or merged, follows a per-tool permission model.

Listing tools

To see everything available to the agent in the current session, built-ins, your own custom tools, and manifest diagnostics, run:

stella tools

This reflects the live session. It includes custom tools found in .stella/tools/ and ~/.stella/tools/, and any tools merged in from configured MCP servers.

Built-in catalog

Each tool is either read-only (it only looks, at the workspace, session state, or the environment) or mutating (it writes a file, runs a command, changes the task board, writes scratch state, or hands work to a sub-agent). The read-only marker is the schema's read_only: true flag. Anything without it is treated as capable of side effects. The engine runs tools in parallel based on that flag, so a mutating tool marked read-only by mistake would cause writes to race each other.

A subset of the read-only tools is also speculation-safe (the schema's speculation_safe: true flag). For these, the engine runs a step's first batch of speculation-safe calls at the same time, while the model is still streaming its response, and collects the results when it's ready to use them. This means those lookups cost almost no extra time. Speculation is a narrower claim than read-only: a retried stream can run a speculated call twice, so only calls that are free to repeat can opt in. A mutating tool is never speculated, and tools from MCP servers never opt in either.

The speculation-safe tools are exactly: read_file, task_list, get_state, list_state, and get_environment.

search is a useful exception. It's read-only about the workspace — it never edits a file — but it isn't speculation-safe, because its semantic ranking step writes embeddings into codegraph.db as it works. Running it twice isn't free, so it stays read-only without opting into speculation.

Tool names are their exact identifiers. The agent calls them by name, and these are the same names stella tools prints.

This page is written by hand. It isn't checked against crates/stella-tools/src/catalog.rs. The generated, gate-enforced version of the same facts lives in docs/tools/*.toml, one file per tool, rebuilt with make tool-docs-update and checked with make tool-docs. If the two disagree, trust docs/tools/, and treat this page as needing an update.

All 18 tools register in every session, with no setup and no prerequisites. Here they are, grouped by what they touch.

Shell

bashMutating

Run a shell command in the workspace root. Returns stdout and stderr, with a timeout backstop. This is the only built-in that runs something with no other bound, which is why it carries a high risk grade. Turning it off with a permission ceiling still leaves the rest of the tools working.

Files

read_fileRead-only

Read a file, or several files and ranges, in one call. Returns content with 1-based line numbers. Use offset and limit to pull one range out of a big file. Use files to ask for several at once.

write_fileMutating

Create or overwrite a file, creating parent folders as needed. Overwriting an existing file is refused unless the session has already been shown all of it. The argument is the whole file, so a model working from a partial view would silently cut off the rest. Use edit_file instead to change part of a file you haven't read in full.

edit_fileMutating

Replace an exact piece of text in a file. The text you're replacing must appear exactly once, unless replace_all is set. An ambiguous match is refused instead of guessed at.

delete_fileMutating

Delete a file in the workspace. Prefer this over bash rm: a symlink is removed as the link itself, leaving its target alone. This is the one destructive grade in the catalog, because deleting a file is the one thing here the agent can't undo from inside the same turn.

searchRead-only

Find code by meaning, not just by text. Describe what you're looking for, and get back the files that answer it, with their symbols, callers, imports, and source attached. One call usually replaces a run of separate grep, glob, and read calls. The answer always states which strategies ran and whether the result was cut short.

Task board and sub-agents

task_createMutating

Add a task to the session task board, one per concrete deliverable, created before multi-step work starts.

task_listRead-only

Show the board: every task as [status] #id subject (owner).

task_startMutating

Mark a board task in progress, one at a time.

task_completeMutating

Mark a board task complete the moment its work is done and checked.

task_cancelMutating

Cancel a task that's no longer worth doing, with a reason. The row stays as a record.

task_assignMutating

Hand a board task to a parallel sub-agent. The briefing is passed along exactly as written, so write it so it stands on its own.

delegateMutating

Hand a self-contained research question to a read-only sub-agent that investigates and reports back only its findings. Its intermediate work never enters the conversation, so the parent never has to re-send it on later steps.

Session state

save_stateMutating

Save session state under a key, so later steps can reference it instead of working it out again — parse results, extracted lists, computed digests. Capped at 1 MiB for content the model writes directly; files written into $STELLA_SCRATCH have no cap.

get_stateRead-only

Read a saved scratch entry by key, shown 30 KB at a time with clear markers for what's left. Prefer this over recomputing something expensive.

list_stateRead-only

List saved scratch entries, with key and size in bytes, including files written into $STELLA_SCRATCH.

delete_stateMutating

Delete one scratch entry by key. Use this when saved state is stale or replaced, so later steps can't read an outdated value.

Environment

get_environmentRead-only

Report this session's environment in one call: workspace root, whether it's a git repository (and whether it's a linked worktree), platform and architecture, OS release, login shell, and the scratch directory path. It reads the same facts already stated in the system prompt's "Session environment" block, minus the model name, which only the CLI prompt layer reports.

The read-only tools are exactly: read_file, search, task_list, get_state, list_state, and get_environment. The other twelve are mutating.

Switching tools off

Every tool ships turned on. The only way to turn one off is a "tools" entry in settings.json, and it works the same whether the name is a built-in, an MCP server's tool, or one you registered yourself:

settings.json
{
  "tools": {
    "task_assign": "off",
    "mcp__github__create_issue": "off"
  }
}

A key can be a tool name, a group name (the family headings above — shell, file, search, task, scratch, environment — plus mcp and custom for tools the built-in catalog doesn't know about), or "*" for everything. The most specific setting wins: a name beats a group, and a group beats "*". Anything not mentioned stays on.

Two examples that follow from that rule:

A board reader that cannot change the board
{
  "tools": {
    "task": "off",
    "task_list": "on"
  }
}
No sub-agent delegation, everything else untouched
{
  "tools": {
    "task_assign": "off",
    "delegate": "off"
  }
}

A switched-off tool is left out of the schema and refused if called anyway. The refusal looks the same as an unknown-tool error, so a disabled tool is indistinguishable from one that was never built. This is enforced at the tool boundary, not by asking the model nicely.

Settings merge per key, project beats user, with one exception: an org-managed settings.json that turns a tool off acts as a ceiling. A user or project scope can narrow it further, but can never turn it back on. See settings.

Where to go next

  • Agent Skills — reusable SKILL.md capabilities, versioned and installable from the registry.
  • Custom Commands — add your own prompt templates to the slash menu.
  • Custom Agents — reusable personas with an optional restricted toolbelt, imported from .claude/ and .agents/.
  • Permissions — how read-only and mutating tools are gated, and how hooks can block tool calls.
  • Custom Tools — add your own script tools with a TOML manifest.
  • MCP Servers — merge in tools from Model Context Protocol servers.
  • Hooks — run shell commands on agent lifecycle events.

Model guide

The full model catalog — context windows, list prices per million tokens, release timing, and which model fits which seat.

Agent Skills

Reusable capabilities in SKILL.md files. Covers project and user scopes, versioning, the public registry, and how skills reach the model through recall.