Agent tools
The tools the Rolit agent can call in the CLI, how they load, and how each is approved.
When you chat or run a goal, the agent works by calling tools. Some read and edit files in your workspace, others search the web, drive a browser, or run marketing jobs. You don't call tools directly. You can control which are available, and what needs your approval.
Tool families
| Family | What it does | Page |
|---|---|---|
local.* | Read, search, write, and edit files; run commands; ask you questions; keep a checklist | Workspace tools |
web.* | Search the web and fetch public pages | Workspace tools |
media.* | Understand and generate images, audio, music, sound, video | Workspace tools |
deploy | Publish a file or site to a public URL | Workspace tools |
local.memory | Save and recall long-term notes | Workspace tools |
browser.*, computer.* | Drive your Chrome browser or your desktop | Browser and desktop |
seo.*, aeo.*, link.*, rank.* | Audit sites for search and AI-answer visibility | Marketing tools |
research.*, content.*, creative.*, social.*, email.*, analytics.* | Research, drafting, media, and email lint | Marketing tools |
crm.*, outreach.*, meeting.*, sales.* | Sales work against a CRM | Marketing tools |
ads.*, google.* | Paid ads and Google Workspace | Marketing tools |
lsp.*, duckdb.*, setup.*, agent.*, <server>.<tool> | Code intelligence, data, installs, subagents, MCP servers | Extensions |
How tools load
Core tools (reading, writing, editing, commands, asking you a question) are sent to the model at the start of every turn. Most other tools are deferred: the model sees their names and loads the full definition on demand with a built-in tool_search tool.
| Availability | Tools |
|---|---|
| Always on | local.*, web.*, tool_search |
| On by default | local.todo (turn off with --no-todo or /todo off) and media.extract_text |
| On when enabled | media.* generation (/media), deploy (/deploy), browser.* (/browser), computer.* (/computer) |
| On when configured | lsp.*, MCP server tools, duckdb.* after /setup duckdb |
| Needs a tool pack | seo.*, research.*, crm.*, and other marketing tools |
| Chat only | agent.* and duckdb.* exist only in interactive chat |
Tool packs
Marketing tools are enabled by packs listed in tools.gtm.packs in .rolit/config.json:
| Pack | Adds |
|---|---|
marketer | SEO and AEO, content, email, social, ads, analytics |
blogger | SEO and AEO, content |
creator | Content, creative, social, sponsor tracking |
sales | CRM, outreach, meetings, sales documents |
gtm-team | The families above, combined |
/seo on adds the marketer pack. A tool from a pack that is off fails as unknown_tool. Tools that can publish, send, or spend are not offered in plain REPL, piped, or --json runs.
How tools are approved
Every tool call is assigned a risk tier before it runs. The model doesn't choose the tier.
| Tier | Meaning | Default behavior |
|---|---|---|
| Metadata | Session bookkeeping, asking you a question | Never asks |
| Read | Reads workspace or public content | Follows the approval mode |
| Protected read | Reads credential files or VCS internals | Asks outside auto |
| Write | Changes files or an external session | Asks in cautious; allowed in auto and edits |
| Command | Runs or inspects a process | Asks in cautious and edits; allowed in auto |
| Generate | Uses a metered provider (images, video, music) | Asks in cautious and edits; allowed in auto |
| Metered | A costly data call with a price shown first | Always asks, even in auto |
| Browser navigation | Opens a URL in the browser | Allowed in auto; asks otherwise |
| Browser control | Input on an authenticated browser | Allowed in auto interactively; asks in cautious and edits |
| Desktop control | Reads or controls any visible app | Same as browser control |
| External MCP | A connected MCP server with unknown risk | Asks unless session Auto is on |
| Publish | Makes something publicly reachable | Always asks. Pending in scripts |
| Send | Delivers a message to someone else | Always asks. Pending in scripts |
| Spend | Commits money outside Rolit credits | Always asks. Pending in scripts |
| Explicit consent | Installs software, starts background work, or replaces data | Always asks |
| Bulk write | Changes more than 25 CRM records | Always asks |
| High risk, outside workspace | Destructive or escaping the workspace | Always denied |
plan-only denies every tier that has a side effect. The session Auto switch (Shift+Tab) never promotes Publish, Send, Spend, Metered, or Bulk write, and never overrides a denial. Subagents can never hold a Send or Spend tool. See Approval modes.
Results and errors
Tool results are JSON. Failures share one shape: a code, a message, and whether retrying can help.
{ "error": { "code": "stale_hash", "message": "...", "retryable": false } }Common codes:
| Code | Meaning |
|---|---|
approval_denied | Policy denied the call, no prompt was possible, or you declined. |
path_protected | The target is a protected path. |
stale_hash | The file changed on disk since the agent last read or wrote it. |
read_required | An edit targeted a file that hasn't been read in this session. |
ambiguous_match | The text to replace occurs more than once. |
no_match | The text to replace wasn't found. |
already_exists | A create write targeted an existing path. |
binary_file | The file isn't UTF-8 text or a supported image. |
not_found | The path or resource doesn't exist. |
invalid_args | The arguments don't match the tool's schema. |
upstream | A provider or server error. Retryable only when retryable is true. |
A non-interactive run that reaches a publish, send, or spend call gets this instead of running it, and exits with code 21:
{ "status": "approval_pending", "pending_action_id": "pa_xxxxxxxxxxxx" }