Built-in Tools

The complete catalog of tools the Stella agent can call in every session, including which are read-only and which mutate your workspace.

Stella ships with a set of built-in tools that are always available to the agent. On top of these, you can add your own custom script tools and merge in tools from MCP servers. Every tool is subject to a per-tool permission model.

Listing tools

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

stella tools

This reflects the live session: it accounts for custom tools discovered in .stella/tools/ and ~/.config/stella/tools/, and for any tools merged in from configured MCP servers.

The built-in catalog

Each tool is either read-only (it only observes your workspace and environment) or mutating (it changes files, runs commands, or performs side effects). The read-only marker is the schema's read_only: true flag; anything else is treated as capable of side effects.

Read-only also means speculative-eligible: the engine executes an all-read-only prefix of a step's tool calls concurrently — while the model is still streaming — and harvests the results at dispatch, so read-only lookups cost almost no wall-clock. A mutating tool is never speculated.

Tool names are their exact identifiers — the agent dispatches by name, and these are the names stella tools prints.

Always available

These 35 tools register in every session — no configuration, no prerequisites. Grouped by what they touch:

Files

Tool	Description	Access
`read_file`	Read a file, returned with 1-based line numbers; `offset`/`limit` read a range.	Read-only
`write_file`	Create a file or overwrite an existing one — parent directories are created as needed.	Mutating
`edit_file`	Replace an exact substring in a file — exactly-once by default, every occurrence with `replace_all`.	Mutating
`delete_file`	Delete a file — preferred over shelling out to `rm`, so the deletion lands in the file-touch audit log.	Mutating

Search

Tool	Description	Access
`grep`	Search file contents with a regex (ripgrep-backed when available); once the code-graph index exists, matches carry a code-map footer.	Read-only
`glob`	Find files by glob pattern, returned as workspace-relative paths.	Read-only

Context & memory

Tool	Description	Access
`gather_context`	Run one deterministic context sweep — grep patterns + file globs + code-graph symbol lookups + bounded excerpts — in a single call, saved as a reusable context pack.	Read-only
`explorations`	List saved codebase explorations, or read one back by slice.	Read-only
`save_exploration`	Persist an end-to-end map of a codebase slice for other agents to reuse.	Mutating
`save_memory`	Save a durable workspace lesson (gotcha, convention, failed approach) to `.stella/memories/` — loaded into every future session's prompt.	Mutating
`cite_memory`	Cite a recalled memory that informed the turn (feeds the citation loop).	Mutating

Verify & build

Tool	Description	Access
`verify_done`	Prove a change is done: the test command must pass on the new code and fail on `git HEAD`. Runs in a shadow worktree and never edits your working tree.	Mutating
`build_project`	Build the workspace with its own toolchain (cargo/npm/go/make), or a custom command.	Mutating
`run_tests`	Run the project's tests with its own runner — `kind` picks unit/e2e/all, `filter` is runner-native.	Mutating
`run_lint`	Run the project's own linter (cargo clippy, or the `lint` script); `fix` applies automatic fixes.	Mutating
`format_code`	Run the project's own formatter (cargo fmt, or the `format` script); `check` verifies without rewriting.	Mutating
`run_script`	Run a verb the project itself declares — a Makefile target, a package.json script, or a cargo alias — argv-style, never through a shell.	Mutating

Process control

Tool	Description	Access
`start_process`	Start a long-running process (dev server, REPL, watcher) from an argv vector — no shell — and get a handle for the other three.	Mutating
`read_output`	Read a started process's buffered stdout+stderr since the last read, plus its running/exited state.	Mutating
`send_stdin`	Write text to a started process's stdin (e.g. a REPL command).	Mutating
`stop_process`	Stop a started process: SIGTERM to its process group, then SIGKILL; remaining output stays readable.	Mutating

Git

Tool	Description	Access
`repo_status`	Current branch, commits ahead/behind upstream, and the changed files as structured rows.	Read-only
`repo_commit`	Commit exactly the named paths — there is no stage-everything mode.	Mutating
`repo_push`	Push the current (or named) branch; structurally refuses the default branch, and force-push does not exist here.	Mutating
`repo_pull`	Update the current branch from upstream, fast-forward only — never merges or rewrites.	Mutating
`repo_rollback`	Restore exactly the named paths to their last committed state; history itself is never rewritten.	Mutating

CI & media

Tool	Description	Access
`ci_status`	Inspect CI runs and failure-log tails for a branch, PR, or commit via `gh`; `wait` blocks until the latest run finishes.	Read-only
`screenshot`	Capture the screen to a PNG in `.stella/screenshots/` as verification evidence.	Mutating
`generate_svg`	Validate, sanitize, and save an SVG the agent authored into `.stella/artifacts/` — scripts, event handlers, and external references are stripped.	Mutating

Task board

Tool	Description	Access
`task_create`	Add a task to the session task board — one per concrete deliverable, created before multi-step work starts.	Mutating
`task_list`	Show the board: every task as `[status] #id subject (owner)`.	Read-only
`task_start`	Mark a board task in-progress — exactly one at a time.	Mutating
`task_complete`	Mark a board task completed the moment its work is done and verified.	Mutating
`task_cancel`	Cancel a task that is no longer worth doing, with a reason; the row stays as an audit trail.	Mutating
`task_assign`	Delegate a board task to a parallel sub-agent — the briefing is passed verbatim, so write it self-contained.	Mutating

verify_done and screenshot are mutating in the permission model (read_only: false) even though verify_done never edits your working tree and screenshot only writes into .stella/. The read-only partition is exactly: read_file, grep, glob, gather_context, explorations, ci_status, repo_status, task_list, and (when present) graph_query, search_issues, get_issue, list_labels, list_members, web_search, web_fetch, web_extract_assets — plus search_skills, tool_search, skill_search, and mcp_search at the session layer. (web_download writes a file, so it is mutating.)

Conditionally registered

These appear only when their prerequisite is met:

Tool	Description	Access	Appears when
`bash`	Run a shell command in the workspace root, with a timeout backstop.	Mutating	Your settings opt in with `"tools": {"bash": "on"}` (any scope). Off by default everywhere, including interactive sessions — see below.
`web_fetch`	Fetch a URL and read it as markdown, plain text, or raw HTML — links absolutized so the agent can follow them.	Read-only	Your settings opt in with `"tools": {"web": "on"}` (any scope). Off by default — see Web tools.
`web_extract_assets`	Fetch a page and mine its design assets — stylesheets, scripts, images, fonts, plus design tokens (colors, font families, custom properties, `@font-face`) distilled from the CSS.	Read-only	The `web` opt-in (as above).
`web_download`	Download a URL to a file inside the workspace (images, fonts, stylesheets, archives).	Mutating	The `web` opt-in (as above).
`web_search`	Search the web and get ranked results (title, URL, snippet).	Read-only	The `web` opt-in and a BYOK search key (`BRAVE_API_KEY` or `TAVILY_API_KEY`) — the other three web tools need no key.
`graph_query`	Query the indexed code graph instead of grepping: definitions, references, imports, importers, or a file's full graph neighborhood.	Read-only	`stella init` has built `.stella/codegraph.db` (also picked up mid-session once the graph exists).
`generate_image`	Generate an image from a text prompt into `.stella/artifacts/`.	Mutating	An image-capable BYOK provider key is configured.
`generate_video`	Submit an asynchronous text-to-video job. Video costs real money: any job with a positive estimated cost is denied unless `confirm_spend` is true.	Mutating	The configured media provider has a video adapter — an image-only key registers `generate_image` without the video pair.
`poll_video`	Poll a video job, reconciling its state live against the provider.	Mutating	Same video-adapter condition as `generate_video`.
`create_issue`	Create an issue (title, body, labels, assignee, Linear team). Labels and assignees must exist — search them first.	Mutating	An issue backend is configured (see below).
`update_issue`	Update title/body, comment, change status, add labels, set the assignee — any combination.	Mutating	An issue backend is configured.
`close_issue`	Close an issue, optionally with a closing comment.	Mutating	An issue backend is configured.
`search_issues`	Search or list issues, with state/assignee/label filters.	Read-only	An issue backend is configured.
`get_issue`	Read one issue in full, including its comment thread.	Read-only	An issue backend is configured.
`list_labels`	Search labels by substring — no guessing exact names.	Read-only	An issue backend is configured.
`list_members`	Search assignable people by login, name, or email substring.	Read-only	An issue backend is configured.
`start_work_on_issue`	Move an issue to in-progress and create or check out its branch.	Mutating	An issue backend is configured.

There is no shell by default. bash is opt-in via "tools": {"bash": "on"} in settings.json — in any scope, in every kind of session. When it's off, the model never sees the schema, and calling bash anyway returns the standard unknown-tool error: the policy is enforced at the tool boundary, not by prompt discipline. The structured tools above (run_script, build_project, the process group, the repo_* family) cover most of what a shell would do, with an auditable surface.

The issue backend resolves in precedence order: LINEAR_API_KEY env → a stored Linear connection (stella connect linear) → a stored GitHub connection (stella connect github, runs over REST with no gh CLI needed) → ambient gh CLI auth. If none is available, no issue tools are registered at all. See stella connect.

Web (opt-in)

The web family gives the agent the open internet: search, fetch-and-read, asset extraction, and download. It powers things like "build me a design system based on this site" or "read this article and summarize it." Like bash, it is off by default in every scope — a fetched page is both untrusted input and an uncontrolled egress channel, so you turn it on deliberately:

settings.json

{
  "tools": {
    "web": "on"
  }
}

With the opt-in, three tools register with no key required:

Tool	What it does	Access
`web_fetch`	Fetch a URL and read it. HTML renders as markdown (default), plain `text`, or raw `html`; links and images come back absolute so the agent can follow them. Binary responses are reported, not dumped — use `web_download` for those.	Read-only
`web_extract_assets`	Fetch a page and mine its design assets: external + inline stylesheets, scripts, images, preloaded fonts, and design tokens distilled from the CSS — colors and font families ranked by frequency, CSS custom properties, and `@font-face` families with their source files. The starting point for reconstructing a site's design system.	Read-only
`web_download`	Download a URL to a workspace-relative path (confined to the workspace root, audited in the file-touch ledger like `write_file`). Assets belong under `.stella/artifacts/web/`.	Mutating

web_search registers additionally when a BYOK search key is present — BRAVE_API_KEY (a dedicated web-search API) or TAVILY_API_KEY. Without a key the other three still work; you just fetch URLs you already know.

Logging in to sites (`web_auth.toml`)

To fetch pages behind a login — your subscriptions, a paywalled news site, an internal tool — give Stella your own session in ~/.config/stella/web_auth.toml (override the path with STELLA_WEB_AUTH_FILE). Cookies and headers are injected per domain at request time and never appear in tool output, so the secrets stay out of the model's context.

~/.config/stella/web_auth.toml

# Optional: override the default `stella/<version>` User-Agent for all requests.
[defaults]
user_agent = "Mozilla/5.0 (compatible; my-research-bot)"

# One block per domain. A domain also matches its subdomains; the longest
# configured suffix wins (api.example.com beats example.com).
[domains."news.example.com"]
cookie = "session=…; csrftoken=…"   # paste from your logged-in browser session

[domains."internal.corp"]
authorization = "Bearer …"
[domains."internal.corp".headers]
X-Tenant = "acme"

web_auth.toml holds live session secrets — treat it like credentials.toml. Stella redacts the values from its own logs and never echoes them into a tool result, but the file itself is plaintext: restrict it to owner-only (chmod 600). Unknown keys are a hard parse error, and a broken file makes every web tool fail loudly rather than silently fetching unauthenticated. cookie and authorization are dropped on a cross-host redirect; a secret in a custom headers entry is not — it would follow the redirect, so only put secrets in custom headers for hosts you trust to redirect.

No network allowlist. With the opt-in on, the agent can fetch any http(s) URL the host can reach — including localhost, private ranges, and cloud metadata endpoints. This is deliberate: it matches the bash opt-in and is what makes "read my internal tool" or "scrape my localhost dev server" work. The gate is the settings opt-in itself, not a per-URL filter — so enable web where you'd be comfortable enabling bash, and be aware that a page the agent fetches could try to steer it toward an internal URL (prompt injection). Combine with PreToolUse hooks or guard-tool rules if you need to constrain destinations.

Session tools

The CLI layers six more tools on top of the native registry. Three belong to interactive sessions:

Tool	Description	Access
`ask_user`	Ask the user a multiple-choice question when a decision is genuinely theirs to make — 2–6 short options, and the UI always adds a free-text option. In a headless run it returns a named error instead of hanging on stdin.	Mutating
`search_skills`	Search the public skills registry for reusable agent skills matching a topic.	Read-only
`install_skill`	Install a skill from the registry into the project's `.stella/skills/` — always asks for confirmation first.	Mutating

Discovery tools

The other three session tools are read-only discovery tools layered over the whole catalog. They exist so the agent never needs the entire tool, skill, and MCP surface frontloaded: a workspace can carry hundreds of tools and thousands of installed skills, and the agent finds the best fit on demand instead of carrying all of it in every prompt.

Tool	Description	Access
`tool_search`	Search every tool available this session — built-ins, `mcp__<server>__<tool>` MCP tools, custom tools — ranked by fit. Queries are keywords (`issue tracking`), `+required` terms (`+github pr`), or `select:name1,name2` for exact lookup.	Read-only
`skill_search`	Search the skills installed in this workspace (`.stella/skills/` plus the user-global directory), ranked by fit. `include_body: true` also returns the best match's full instructions. Complements `search_skills`, which queries the public registry for skills you'd still have to install.	Read-only
`mcp_search`	Find MCP servers and their tools: the workspace's configured servers (default scope), or the public MCP registry (`scope: "registry"`) for servers worth installing with `stella mcp install <name>`.	Read-only

Lean frontloading (experimental)

Set STELLA_LEAN_TOOLS=1 to advertise only a lean core toolset (file CRUD, search, build/test/verify, ask_user, and bash when the opt-in has enabled it) plus the discovery tools; everything else stays out of the prompt until a tool_search surfaces it. Matched tools are activated — advertised for the rest of the session. Set the variable to a comma-separated list of tool names to choose your own core. A hidden tool called by name still executes, so lean mode trims prompt weight without ever gating a capability.

All told: 35 always-on tools, up to 52 native tools with the bash and web opt-ins, the code graph, media keys, a search key, and an issue backend, plus the six session tools — before any custom script tools or MCP servers merge in.

Where to go next

Agent Skills — reusable SKILL.md capabilities, versioned and registry-installable.
Custom Commands — extend the slash menu with your own prompt templates.
Custom Agents — reusable personas with an optional restricted toolbelt, adopted 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 tools from Model Context Protocol servers.
Hooks — run shell commands on agent lifecycle events.

On this page