Tools

The assistant can call 175 tools, grouped below by the question each one answers. Every one of them is checked against the permission gate before it runs. See Permissions for what AUTO, ASK and DENY mean and who decides, and Reaching a tool for which of these are described to it before it answers, and which it has to look up first.

These are the shipped defaults. What you can change lives in a config file you own once TESSERACT is installed, so your copy may differ, and should, once you tune it.

Remembering

Tool	What it does	Use it when	Not for
atlas_query	Ask how records connect, with a citation for every hop.	Use when the question is about the relationship rather than the text: what two records share, what a subject gathers, what a decision came out of. A connection in the recalled-memories block carries its id in brackets; pass it in start_at to walk on from it. Every hop says what was read, where, and who asserted it.	to find a record by what it SAYS, use memory_search or vault_search: this reads only the connections between records.
diary_append	Append a first-person reflection to the assistant’s private diary.	Use for self-observations about a session: what landed, what felt off, what you’d do differently. Read DIARY.md before first use.	use memory_save for facts about the operator or the project. Not retrieved by memory_search; it’s walled off from routine recall.
handoff_history	List or read this conversation’s own consolidation handoffs.	Use to see where a past boundary said the work stood: the objective, what was done, what is left, what to do next. Call with no arguments for a newest-first list of this conversation’s own handoffs, then read one in full by its index or id. Pass chat_id to read another conversation’s instead.	for what was actually said in a transcript, use recall_history: that searches the words, this reads the handoff a boundary wrote about them, which is a judgement, not a quote. For how full THIS conversation is right now, or what it has cost, use context_read.
memory_forget	Permanently delete a memory: its file, index entry, and embedding.	Use sparingly and only on operator request to remove a memory by id. Deletion is irreversible. The file is removed from disk.	use memory_promote action=archive to retire a memory while keeping it for forensics.
memory_get	Read a line-range slice of one known memory-store markdown file.	Use when you already have the path, usually because the recalled-memories block or a search result gave it to you, and you want the whole record rather than the one line those show.	use memory_search when you do not already have the path: this reads one file and finds nothing. Refuses MEMORY.md.
memory_promote	Run an operator-approved memory lifecycle action: archive, merge, or bump.	Use to execute one action the feedback consolidator proposed and the operator approved: archive a record, merge one into another, bump importance, or propose a soul-growth bullet.	use memory_update for a routine content edit; use memory_forget for permanent deletion.
memory_save	Write a new durable memory to the persistent store.	Use to capture a fact, decision, or preference that will still be true next session rather than only now. One memory per fact, and tag it: tags are how it is found and how the map joins it to everything else on the subject.	use memory_update when revising something already saved; use diary_append for self-reflection about the assistant itself.
memory_search	Search the persistent memory store by query, ranked by relevance.	Use before answering anything that turns on what the operator has decided, preferred or told you: names, projects, past choices. Every turn already arrives with a few recalled memories, so reach for this when they are thin or the question is broader.	a subject the library holds RESEARCH on: vault_query is faster. How two records RELATE: atlas_query. A path you already have: memory_get. What was said in a past session: recall_history, which is recall rather than settled fact.
memory_update	Revise an existing memory’s content, title, importance, or tags.	Use to amend a memory once a fact changes. Pass the memory id. memory_search results carry it.	use memory_save to create a new fact; use memory_promote for lifecycle actions like archive/merge/bump.
recall_history	Search past session transcripts and workshop artifacts by free text.	Use to recall what was said or done in a prior session or workshop file. Returns ranked hits with a path to file_read for the whole thing.	for what the operator has settled on, use memory_search: a hit here is what was said once, not what was decided, so never quote it back as a decision. For research the library keeps, use vault_query. For what a past boundary itself wrote down, where the work stood at that point rather than what was said along the way, use handoff_history.
soul_growth_propose	Queue a distilled SOUL.md Growth bullet for operator approval.	Use sparingly for a stable, distilled pattern about you-with-this-operator. Queues a workspace-inbox proposal; SOUL.md updates only on operator approve.	use diary_append for a single session’s observation; use memory_save for facts about the operator or project.
workspace_read	Read one of your own workspace documents, or a playbook’s SKILL.md.	Use when the prompt points at a workspace document and you want it: WORKSHOP.md before writing a task artifact, DELEGATION.md before handing work to a seat or a subagent, DIARY.md when reviewing your own patterns, or a playbook’s SKILL.md before running it. Also use it to read the rest of a document the prompt only shows the start of.	use file_read for anything in the code tree, and memory_get for the memory store. This reads the workspace only: its markdown, and skills/carried.txt.

Research library

Tool	What it does	Use it when	Not for
vault_ingest	Files a local document or URL into the immutable vault and indexes it.	Use to add a new source to the vault. Call once without confirmed_path for a suggested filing location, then again with confirmed_path to execute.	reading what the vault already holds. That is vault_query or vault_search.
vault_lint	Runs lint passes over the compiled vault wiki and flags issues found.	Use to check wiki health after ingesting or compiling sources. Writes lint_flags for the operator to resolve. Pass dry_run=true to inspect without writing.	reading vault content. That is vault_query or vault_search.
vault_query	Synthesizes an answer from the vault’s compiled wiki of topic-grouped summaries.	Use for “what do we have on X” about a subject the library holds research on: documents, articles, PDFs, snapshots. It answers from the compiled wiki, so it is the fastest way in. Reach for it BEFORE answering from your own knowledge, because the vault is the authoritative surface and your prior is not.	for what the OPERATOR decided or prefers, use memory_search: that is their record and this is their library. Use vault_search when you need the exact passage rather than a summary, or when the page was compiled before the document you are being asked about. The vault is the operator’s own library and is not the web.
vault_search	Hybrid BM25 + vector search over raw vault source chunks.	Use to find the exact passage where something was said, and to quote it. Returns matching chunks with the file each came from, across PDFs, articles, data files and web snapshots. Also the way to reach a document ingested since the wiki was last compiled, which vault_query cannot see.	start with vault_query when the question is “what do we have on X”: raw chunks are the wrong shape for a question that wants an answer. Use memory_search for what the operator decided rather than what a document says.

Searching the web

Tool	What it does	Use it when	Not for
context7_lookup	Fetches current library or framework API docs from Context7 by name or ID.	Use for any library or framework API question instead of guessing from training knowledge. Resolves a name to a Context7 ID and fetches docs scoped by topic.	Use web_search or tavily_search for anything outside library documentation, such as news or general topics.
tavily_extract	Extracts clean markdown from one or more specific URLs via Tavily.	Use once you already know the URL(s) and want their readable content, typically after tavily_search or web_search surfaces a promising link.	Use tavily_search or web_search first when you don’t yet have a specific URL.
tavily_search	Web search via Tavily. Snippets shaped for a model, plus an optional answer.	Use for research questions where you need to answer something from the web, not just survey what exists.	Use web_search for breadth over niche/news queries. Use tavily_extract once you already have specific URLs and need their full readable content.
web_search	Web search via Brave. A ranked list of title, URL and short snippet.	Use for breadth on current events, recent docs, or niche queries. Wide results, not one synthesized answer. The web is not the vault; it holds outside sources.	Use tavily_search when you need denser per-result content or a synthesized answer instead of short snippets.

Files on disk

Tool	What it does	Use it when	Not for
file_copy	Copy a single file to a new path, leaving the source in place.	Duplicating a file. Creates parent directories; refuses to overwrite an existing dest_path unless overwrite=true.	Use file_move when the source should not remain at its old path.
file_delete	Delete a file, or a folder and everything inside it.	Removing something for good, anywhere the write boundary allows: your writable areas under the home tree, or a folder the operator granted. A relative path anchors at the state root; locked runtime and source trees are refused. Deleting a whole folder asks the operator first; a single file follows its own path’s rules.	Use file_move when the content should still exist somewhere else afterward, or file_read when it should remain where it is.
file_move	Move or rename a single file to a new path.	Relocating or renaming a file. Creates parent directories; refuses to overwrite an existing dest_path unless overwrite=true.	Use file_copy when the source should still exist at its old path afterward.
file_read	Read a file’s contents as numbered lines.	You know the path and want its contents, or a specific line range of them.	Use grep when you want the matching lines rather than the whole file, glob when you don’t know the path yet, and pdf_read for a PDF.
file_write	Write content to a file, creating parent directories as needed.	Creating a new file or overwriting one wholesale. A relative path anchors at the state root; writes into locked runtime/source trees are refused.	Use file_copy or file_move to relocate an existing file instead of reading and rewriting it.
glob	Find files by path/name pattern, newest first.	You know a filename or path shape but not the contents. ’*’, ’**’, ’?’, ‘[seq]’ and brace alternation ‘{a,b}’ are supported.	Use grep when the question is about file contents rather than paths.
grep	Search file contents for a regex pattern via ripgrep.	You want the matching lines, with file and line number, rather than a whole file. The header reports the true match and file totals even when truncated.	Use file_read once you know which file and want its full contents, or glob when you want paths rather than contents.
log_triage	Summarise a log file’s shape: counts, span, levels, and repeated messages.	The question is ‘what is wrong in this log’ rather than ‘does this exact string appear’. Reads the whole file and groups repeats so one failing request does not read as many distinct problems.	Use grep when you already know the exact string to find.
pdf_read	Extract text from a PDF by page range.	The file is a PDF. Pass pages (e.g. ‘1-5’) for a long document. A call is capped, so page ranges pull the rest.	Use file_read for any non-PDF text file.

Showing the operator something

Tool	What it does	Use it when	Not for
cockpit_show	Open a panel, change the text size, or scroll, in the operator’s window.	The operator asks to be shown something in the app, or asks where a setting lives: open it rather than describing the path. Also when they ask you to make the text bigger or smaller, which is the whole app at once and works from across the room.	surface_focus raises one card on the canvas; this moves the window around it. open puts a NEW thing on screen, where this only navigates what is already built. browser_scroll scrolls a web page the assistant opened, not the operator’s own app.
image_generate	Generate an image from a text prompt, or edit a source image (image-to-image).	The operator asks you to draw, illustrate, render, edit, or restyle a visual. Pass image_attachment_id for image-to-image. Saves the result under downloads and returns its URL.	open to show an image that already exists. This tool MAKES one, it doesn’t display one.
open	Show the operator anything that exists: a URL, a file, a folder, an app, or a search.	One argument, and the runtime picks the surface: it renders in the cockpit where it can and hands off to the owning application where it cannot. The result says which way it went. Relay that, and never claim a card appeared without reading it.	You are authoring the content yourself. That is surface_create; this shows a thing that exists, that one brings a thing into existence. And browser_navigate is not this verb however much its description sounds like it: it renders a screenshot, a still image, not a live page. “Show me this” is always open.
os_launch	Internal primitive: open a local file, folder, or app in the program that owns it.	Called by open after it resolves a target to a local path or configured app. Not for direct use.	Model callers use open, which resolves the target and dispatches here itself.
os_open_url	Internal primitive: open an http(s) URL in the operator’s default browser.	Called by open after it resolves a target to a URL destination. Not for direct use.	Model callers use open, which resolves the target and dispatches here itself.
speak	Say a short version of your answer aloud.	Use only while the Voice block of this turn says voice is on, after writing an answer that is long or holds paths, code, tables or lists. Put a short version of the whole reply in the line, the main points in plain speech, so that is what the operator hears while the answer stays on screen. Call it once and end your turn.	voice is off, because nobody hears the line; the answer is short enough to be read out as it is; to show the operator a file, a page or a link, which is open; to send something to the operator’s phone, which is channel_notify.
surface_bind_session	Attach a lane or channel session to a surface so its card streams live updates.	A surface should reflect a running session’s activity as it happens, rather than a static snapshot.	surface_update for a one-off content change; this is for ongoing live streaming from a session.
surface_close	Destroy a surface and remove its card from the canvas.	The operator is done with a card, or it’s stale and needs clearing.	surface_update to change a card’s content without destroying it.
surface_control	Operate a card on the canvas: play, pause, volume, or press its controls.	Something is on the operator’s canvas and they want it operated rather than replaced: pause the video, turn the song down, deal the next round of a game you built. Returns what the card then reads, so you know it worked without asking for a screenshot.	surface_update changes what a card SHOWS, which restarts whatever was running in it. browser_media operates a page in your own headless browser, which the operator cannot see or hear, so it is never the answer for something already on their canvas.
surface_create	Author a card from content you generated: html, markdown, code, or a chart.	An html surface renders in a sandboxed iframe with an opaque origin, so keep it self-contained; storage resets on every mount. Name every control, since any card you author obeys surface_control. Add props.live: true when you need to know what the operator pressed, as a game or a form does. Returns surface_id.	Anything that already exists (a url, file, folder or app) is open’s job. Never hand-write an <iframe> for a video or another third-party page: the opaque origin makes the player throw and the card renders black.
surface_focus	Bring a surface to the front and scroll it into view.	The operator’s card is buried under others or off-screen and needs to be visible again.	surface_highlight for pulse/glow emphasis without changing z-order; surface_update changes what the card shows, not its position.
surface_highlight	Pulse or glow a surface briefly to draw the eye to it.	Something changed on a card and the operator’s attention should land there without sending a message. Auto-fades unless persistent=true.	surface_focus to actually raise the card and scroll it into view. A highlight alone does not move it.
surface_list	List surfaces on a canvas view: id, type, title, mode, and whether each one rendered.	Before spawning to avoid duplicates, to find a surface_id, to check whether a card drew, or to see what it can be asked before asking it. Render and control are the only columns that are not your own instruction read back. Anything but mounted, say so in the reason’s own words: a card that did not draw is not a card they have.	screen_look for what a card actually LOOKS like. This only confirms it was registered, not a look at the pixels.
surface_update	Mutate an existing surface’s props or title (shallow merge).	You need to change what an existing card shows without recreating it: swap html, text, props or the title. Props merge shallowly into the existing payload.	A new card is surface_create (with replaces to hand off cleanly). Raising an existing card to the front is surface_focus, not this.

Driving a web page

Tool	What it does	Use it when	Not for
browser_click	Click the element matching a selector on an open browser page.	You are driving a page and need to press something. Selectors are Playwright: CSS, text=, role=.	browser_navigate first, which returns the context_id this takes.
browser_close	Close a browser context and remove its card from the canvas.	You are finished with a page and the operator does not need its card. A context holds a browser engine open.	Switching pages does not need it, because browser_navigate reuses this session’s card.
browser_fill_form	Type values into form fields on an open browser page.	A login, a search box, a multi-field form. One call fills every field.	browser_click presses controls; this types into them.
browser_hover	Move the pointer over an element on an open browser page.	Something only appears when the pointer is over it: a drop-down menu, a chart tooltip, controls that fade in over a player.	browser_click presses it. Hovering to reveal a menu is a step before clicking, not instead of it.
browser_key	Press a key on an open browser page.	A page is driven by the keyboard rather than by controls you can click: player shortcuts, a search box that wants Enter, a shortcut that opens a menu. repeat presses it several times, which is how volume and seek steps work.	browser_media for play, pause, mute and volume, which reads the media element directly instead of hoping the site binds the key you guessed. browser_fill_form types a value into a field.
browser_media	Play, pause, mute or set the volume of a video or audio on a page.	The operator asks you to control something playing: pause it, mute it, turn it down, skip to a time. Returns what the player now reads, so you know it worked without taking a screenshot. read reports without changing anything.	browser_key for anything the media element itself does not do, such as fullscreen, captions or the next video.
browser_navigate	Drive a headless browser and show a screenshot of the page on the canvas.	You need to interact with a site: click, fill a form, log in, read the DOM. Or you need to capture how a page looks, including sites that refuse to be framed. Reuses this session’s browser card by default, so a browsing flow is repeated calls rather than a pile of cards; new_card=true opens a second one on purpose. Returns context_id.	The operator wants to SEE a link. Use open, which gives a live card with working controls where this gives a still image of one, and it costs a browser engine to do it. “Show me this” is always open.
browser_scroll	Scroll an open browser page, by an amount or to an element.	What you need is below the fold: a button off screen, the rest of an article, a page that loads more as you go down.	browser_snapshot already reads the whole document, scrolled or not, so scrolling to READ something is wasted.
browser_select	Choose an option in a drop-down on an open browser page.	A <select> needs a value. Clicking one does not work reliably, because the browser draws the open list itself and it is not in the page.	browser_click for a menu built out of ordinary elements, which most styled drop-downs are. Check browser_snapshot if you are unsure which this is.
browser_wait_for	Wait for an element to appear on an open browser page.	The page has not caught up: you clicked something and the next thing is still loading. This is what stops the following call acting on a page that has not painted yet.	browser_snapshot when you want to know what IS there. This only waits, and tells you whether the wait ended in time.

Looking for yourself

Tool	What it does	Use it when	Not for
browser_network_requests	Read the network-request log of an open browser page.	A page misbehaves and you need what it actually asked for: a failed call, a redirect, an asset that never arrived.	browser_snapshot reads the rendered result; this reads the traffic behind it.
browser_screenshot	Capture an open browser page and refresh its card.	The page changed after a click or a fill and you need to see the result.	The operator’s own screen is screen_look. This only sees a page nobody is watching.
browser_snapshot	Read the accessibility tree of an open browser page.	You need the page’s structure: what elements exist and what they are for. to pick a selector or confirm something rendered.	browser_screenshot for how it LOOKS; a tree cannot show you a blank pane.
screen_look	Look at the operator’s own screen and answer one question about it.	The question is about what something LOOKS like: a card that rendered blank, text cut off, a control that isn’t there, an error the operator can see and you cannot. No other tool can: the rest report structure, not pixels. Ask one specific thing; you get words back, not the image.	The page is one you opened headlessly. That is browser_screenshot. This photographs the operator’s real display, and it prompts them every time, and it sees whatever else they have open on it.
transcribe_audio	Hear an audio attachment the operator uploaded earlier in this session.	You need the words in an older audio attachment: the operator asks what was said in a file already discussed.	audio on the operator’s most recent message, which is transcribed before you ever see it, so calling this for that attachment does the same work twice.

Handing work to someone else

Tool	What it does	Use it when	Not for
agent_ask	Lets a background sub-agent ask its dispatcher a question and wait for the reply.	Use when a wrong assumption would waste the rest of a background run; otherwise state the assumption and continue.	A foreground call has no parent to ask and is refused. Sending an instruction downward instead: use work_send.
agent_create	Drafts a new markdown sub-agent proposal, quarantined until the operator promotes it.	Use when a role keeps recurring across tasks, such as a reviewer, an auditor or a domain specialist, and is worth making persistent. Always operator-gated.	Activating an already-drafted agent: use agent_promote. Running an existing one: use invoke_agent.
agent_promote	Moves a quarantined agent from pending into the active, invokable set.	Use after agent_create drafted an agent and the operator has approved it. Required before the agent can be invoked.	Drafting a new agent: use agent_create. Running an already-active agent: use invoke_agent.
delegate_agent_controller	Dispatches a task to a fresh agent controller session running the full assistant brain.	Use when a task needs its own chat brain to orchestrate delegation seats and agents across multiple steps, not a single one-shot hand-off.	A single seat call: use delegate_coder or delegate_auditor. A markdown sub-agent task: use invoke_agent.
delegate_auditor	Delegates a review task to whichever CLI fills the auditor seat.	Use for code review, verifying your own reasoning, second opinions on design choices, or scope checks. Brief it with the root symptom, what you expected, and what you ruled out. Never your worry about the mess you made getting there.	Building code, not reviewing it: use delegate_coder. A persistent controller session: use delegate_agent_controller. A markdown sub-agent task: use invoke_agent.
delegate_coder	Delegates a coding task to whichever CLI fills the coder seat.	Use for heavy builds, multi-file refactors, or large reads that need sustained focus. Brief it with the root symptom, what you expected, and what you ruled out. Never your worry about the mess you made getting there.	Work you can do in this seat. Reading a few files, one edit, a script, a fix whose shape you can already see: do it yourself, because it is faster and you can check the result as you go. Review, not build: use delegate_auditor. A persistent controller session: use delegate_agent_controller. A markdown sub-agent task: use invoke_agent.
delegate_second_opinion	Asks the auditor seat one read-only question and waits for the answer.	Use for a quick audit, search or second opinion with nothing to go back and forth about. It runs one command, reads only, and does not survive a backend restart, so retry it if it fails.	Work that writes files, or that needs more than one exchange: use delegate_auditor for a review or delegate_coder for a build. A session that outlives the turn: use delegate_agent_controller.
invoke_agent	Dispatches a bounded task to a markdown-defined sub-agent with a read-only tool subset.	Use for a persistent specialist stance such as a reviewer, a planner or a domain expert, in a scoped context that does not see this conversation.	CLI-role agents are rejected: use delegate_coder or delegate_auditor for heavy CLI work.

Long-running collaborators

Tool	What it does	Use it when	Not for
controller_session_list	List agent controller sessions on disk, newest first, with status.	Use to check whether a detached session from start_controller_session finished.	lanes or interactive sessions, which are lane_list/session_list.
session_close	Close a session and free its resources. Idempotent on an already-closed handle.	Use when a session’s conversation is finished.	terminating a lane’s CLI process, which is lane_close.
session_list	List every open interactive session with its handle and target.	Use to see what sessions are open before sending to or closing one.	lanes, which is lane_list/lane_named_list; controller sessions, which is controller_session_list.
session_open	Open a new interactive session against claude, codex, or a named agent.	Use to start a scoped per-chat conversation you drive with session_send, distinct from a controller-owned lane.	a standing named collaborator surviving restarts, which is lane_named_ensure; a one-shot worker, which is delegate_coder/delegate_auditor.
session_result	Collect the result of a session’s most recent background turn.	Use only after a session_send/session_open call made with background=true.	a foreground call’s reply, already in that call’s own return value; a lane’s reply, which is lane_read/lane_turn.
session_send	Send a follow-up message to an open session and return its reply.	Use for each turn of an open session; background=true returns a spawn handle instead of blocking.	the lane equivalent, which is lane_send/lane_turn; re-fetching a background turn’s result later, which is session_result.
start_controller_session	Spawn a whole new agent controller session in the background and fire its first prompt.	Use to hand heavy work to a full controller session the operator can attach to and watch live.	a lane or interactive session you keep driving yourself turn by turn, which is lane_turn/session_send.

Keeping a coding CLI running

Tool	What it does	Use it when	Not for
lane_attach	Re-establish visibility on a live lane, returning a fresh snapshot and cursor.	Use once per lane after a brain restart, before resuming lane_read/lane_send on it.	opening a new lane, which is lane_open; probing status without needing a cursor, which is lane_status.
lane_close	Terminate a lane’s CLI subprocess and archive its on-disk record.	Use when a lane’s work is done and its process and history should stop existing.	pausing without ending the process. No lane tool does that; lane_read and lane_status just stop being polled instead.
lane_list	Enumerate every live lane_id the controller currently hosts.	Use to discover what lanes exist right now, independent of any name.	named-lane bindings, which is lane_named_list; one lane’s liveness/busy state, which is lane_status.
lane_named_ensure	Get or open a named, persistent lane. Reuses it if alive, opens one if not.	Use for a standing collaborator you address by name across turns and sessions, not a throwaway.	an unnamed one-off lane, which is lane_open; looking up an existing binding without opening, which is lane_named_get.
lane_named_get	Look up the lane_id currently bound to a named lane, without opening one.	Use to resolve a name to its live lane_id, or confirm whether a binding exists.	every binding at once, which is lane_named_list; every live lane, which is lane_list; creating the binding, which is lane_named_ensure.
lane_named_list	List every persistent name-to-lane_id binding, orphans included.	Use to see all named lanes at once rather than checking one name.	one name’s binding, which is lane_named_get; live lanes by id, which is lane_list; a binding’s liveness, which is lane_status.
lane_open	Spawn a new unnamed CLI lane (claude or codex) that persists across turns.	Use to start a fresh, unnamed collaborator lane for one-off multi-turn work you drive yourself with lane_send/lane_turn.	a lane bound to a reusable name, which is lane_named_ensure; a one-shot worker, which is delegate_coder/delegate_auditor.
lane_read	Pull a lane’s events since a cursor. Reads the tail and sends nothing.	Use to catch up on what a lane produced after a prior lane_send, or to keep polling a long turn.	sending a new message, which is lane_send; sending and waiting for the reply in one call, which is lane_turn.
lane_send	Send one message into a running lane and return once it is accepted.	Use to fire a turn onto a lane without waiting; wait=true blocks for just that turn’s reply.	reading a lane’s output after firing, which is lane_read; one call that both sends and waits, which is lane_turn.
lane_status	Fast read-only probe of one lane’s alive/busy/queue_depth state.	Use to check whether a specific lane is free before sending, or confirm it is still alive.	enumerating lanes or bindings, which is lane_list/lane_named_list; resolving a name’s binding, which is lane_named_get.
lane_turn	Send a message into a lane and wait for that one turn’s reply, in one call.	Use as the default way to drive a lane collaborator: one call in, one reply out; backgrounds by default so you stay free meanwhile.	firing a message without waiting, or fetching a lane’s output later, which is lane_send plus lane_read.

Tracking what you spawned

Tool	What it does	Use it when	Not for
spawn_await	Blocks until a background spawn finishes and returns its full result.	Use only when a completed spawn’s result said it was too large to deliver whole and told you to fetch it here.	Routine retrieval. A finished spawn’s output is delivered to you automatically on your next turn without polling; don’t call this or spawn_check to wait for it.
spawn_cancel	Cancels a running background spawn and waits for it to unwind.	Use to stop a background spawn that is no longer needed or has gone off track, before re-dispatching it with a corrected instruction.	Course-correcting a spawn that is still useful. Steer it in place with work_send instead of cancelling and restarting it.
spawn_check	A background spawn: running, done, failed or cancelled, and when it last emitted.	Use ONCE to confirm a spawn’s state, before steering it with work_send or deciding whether to spawn_cancel. If it is still running, say so and end the turn: the outcome reaches you next turn on its own, and a second check learns nothing and costs a model call. A spawn-cap error wants an await or a cancel; a depth-cap error means work inline.	Retrieving a finished spawn’s output. That arrives on its own in your next turn; use spawn_await only for the rare case where the result said it was too large to deliver whole.
work_send	Sends a steering message into a running lane, session, or controller session.	Use to course-correct or answer a question from work already in flight, with one verb and the target resolved for you, without waiting for it to finish.	One-shot spawn handles, which have no input channel. spawn_cancel and re-dispatch with the new instruction instead.

Running commands

Tool	What it does	Use it when	Not for
bash	Runs a raw shell command through the operating system.	Use for an actual shell operation no dedicated tool covers, such as running a script, a build, a git command, a package manager.	Reading a file’s contents (file_read), searching file contents or names (grep, glob), or writing or editing a file (file_write) Those tools exist so this one does not have to, and reaching for bash to cat/grep/echo something costs an operator prompt for nothing. Most commands prompt the operator before running.

Reaching the operator elsewhere

Tool	What it does	Use it when	Not for
channel_history_read	Read past channel conversation directly from the per-day logs.	Use when memory_search plus the rolling summary return nothing for a topic the operator references (‘the trading bot we talked about yesterday’). Three modes: single date, last days_back days, or a substring scan across all days.	the topic is recent enough that memory_search or the rolling summary already covers it. Reach for those first.
channel_notify	Start a conversation with the operator on an external channel.	Use when the operator may be away from the Mirror and you have something they should see now: a finished thought, a result, an alert, a check-in. Pass chat_ref to target a specific chat, or omit it to fan to every chat on the allowlist. Be selective, because this is a tap on the shoulder, not a stream.	the operator is already in the Mirror. Answer them there with an ordinary reply or a surface card, not a channel message.
channel_react	React to an existing channel message with a single emoji.	Use as a lightweight acknowledgment on a specific message without sending a full reply. Pass emoji=null to clear a prior reaction.	the ack needs its own words or is not tied to one existing message. Send a sticker or a channel_notify instead.
channel_send_document	Send a file as a downloadable document on an external chat channel.	Reads source_path and forwards it, any MIME type, so the operator can save it on the far side of a channel. A Mirror URL is broken there, so a file going to a channel must be sent this way, the opposite of open, which is for a file the operator already has inside the Mirror.	the file is an image, video, animation, or audio clip that should render inline instead: use the matching media verb (channel_send_photo and its siblings).
channel_send_photo	Send an image inline on an external chat channel.	Source is either source_path (vault/workspace/downloads file) or source_url (typically an image_generate output URL). Renders inline with an optional caption.	the operator needs the original file at full quality. channel_send_document preserves it but drops the inline preview.
channel_send_voice	Send a spoken voice note on an external chat channel.	Pass text for TTS synthesis (default, conversational) or audio_path for a pre-rendered audio file. Renders as a playable voice-note bubble.	the content is a recording someone should download and keep. Use channel_send_document for that.

Sending media on a chat

Tool	What it does	Use it when	Not for
channel_send_animation	Send a looping GIF-style animation on an external chat channel.	Source is source_path (local file) or source_url (HTTP URL). A canonical looping animation format is preferred; raw GIFs are also accepted.	the clip has sound or is meant to play once through. Use channel_send_video instead.
channel_send_location	Share a static map location on an external chat channel.	Use when the operator asks about a place and a map pin is the clearest answer (‘where is the cafe’, ‘show me the airport’).	a text answer with an address or directions is clearer than a pin.
channel_send_poll	Send a multiple-choice poll on an external chat channel.	Useful for quick decisions with a handful of options (‘lunch options?’, ‘which milestone do you want shipped first?’).	the question is open-ended or has only one sensible answer. channel_notify carries a plain question just as well.
channel_send_sticker	Send a sticker on an external chat channel.	Pass sticker_file_id for a known CDN sticker (fast) or sticker_path for a local file. Use for emotional punctuation that matches the conversational tone.	the reaction is to a specific message already sent. Use channel_react instead of sending a new sticker message.
channel_send_video	Send a video file on an external chat channel.	Source is source_path (local file) or source_url (HTTP URL). Plays inline when the format is streaming-friendly.	the clip is a short round bubble, which is channel_send_video_note, or a looping clip with no sound, which is channel_send_animation.
channel_send_video_note	Send a round short-form video-note bubble on an external chat channel.	Use for a quick face-to-camera style clip in the circular bubble format. No caption is sent alongside it.	a caption matters or the clip is not meant to render as the round bubble. Use channel_send_video instead.

Work you owe

Tool	What it does	Use it when	Not for
task_close	Close a task as done with its evidence, or as failed with the reason.	Use on the task this turn took up with task_work, when the evidence meets what it declared would count as done, or when that cannot be met and there is no decision left to ask the operator for. Give the evidence itself, not a summary. A check the criteria names runs and decides; a failing one closes the task as failed whatever you said.	the task is waiting on the operator or blocked: leave it, the panel carries it. To pause work without ending it, just stop; the task stays running for the next turn. Never done because an earlier task looked the same: this task is its own work, so do it, and its evidence is what this turn produced.
task_propose	Turn a request into a task that is owed until it is verified.	Use when the operator says to take something on as a task, or asks for work that outlasts this turn or must survive a restart. Say what counts as done in terms you can check. The result’s fields say whether it was accepted and whether this turn took it up; when it has, carry on.	a question you can answer now, or a step inside work already on a task. A checklist for this session only is tasks_set; a comment on an existing agenda item is agenda_comment.
task_settle	Mark a task done, cancel it or delete it, when the operator asks.	Use when the operator asked, in chat or on the phone, to mark a task done, cancel it or delete it. Pass what they said as because.	this turn is closing the task it is working: that is task_close, which runs the checks. Never on your own initiative, and never because a task looks finished to you.
task_work	Take an accepted task up in this turn and read what it owes.	Use to start an accepted task this turn does not have yet: one from the agenda, or one after a restart. It ties the turn to it and gives back the goal, what counts as done, and what earlier turns found. A task this conversation is already working is taken up for you on each message, its brief in the runtime state.	to create a task, which is task_propose; to finish one, which is task_close; for a session checklist, which is tasks_set.

Asking the operator

Tool	What it does	Use it when	Not for
ask_clarification	Ask the operator one to four questions, each with choices.	Use when a decision is the operator’s and you can name the choices: one to four questions, each with two to four options. If the operator is in the conversation the turn waits; otherwise the questions go to the inbox and the answer arrives on a later turn.	the request, the code or a sensible default already answers it; a reply on an existing thread, use workspace_reply; whether to run a tool, which the permission prompt already asks.

Asking without blocking

Tool	What it does	Use it when	Not for
agenda_comment	Reply inside an operator comment thread on an agenda item.	Use when directed to answer a comment thread on an agenda item. It renders in the item’s thread, not the chat panel. On a task, pass close when the operator’s comment clearly asks to close it.	a comment on a Workspace event, use workspace_reply; the comment asks for a change to a workspace file. Reply here, then file that change with propose_change.
propose_change	Request a change to an operator-owned workspace file, gated on approval.	Use for any self-edit to a workspace document: how you sound, what you have learned about the operator, how you work. Nothing is applied until the operator approves the diff in the inbox.	replying inside an existing comment thread, use workspace_reply or agenda_comment.
workspace_decide	Answer one thing waiting in the operator’s inbox.	Use when the operator has told you what to do about something workspace_pending listed: approve the drafted agent, reject the soul change, resolve the thread. One item per call, by its id. Their words are the instruction.	to decide something they have not asked you to decide. Proposing this call is not the same as making the decision, and it must never be used to clear the inbox on their behalf.
workspace_pending	List what is waiting on the operator to decide.	Use when the operator asks what needs them, what is waiting, whether anything wants approving, or before telling them there is nothing to do. Read it out with the id beside each one, because deciding needs the id.	for how the runtime itself is doing, which is autonomy_read; for this machine’s health, which is system_diagnose.
workspace_post	Open a new, self-initiated note in the operator’s Workspace Inbox.	Use to surface something without interrupting the chat thread. Replies land as [workspace_comment_on_<event_id>] on a later turn.	a reply inside a thread that already exists, use workspace_reply; an ambient or scheduler-job signal, routed through the autonomy bus instead.
workspace_reply	Reply inside an existing Workspace event’s operator comment thread.	Use when [workspace_comment_on_<event_id>] appears in context and the comment expects an answer. Renders under the comment in the Inbox.	opening a new note, use workspace_post; a plain in-conversation question you can just ask in the reply you are already writing.

Being present in the Mirror

Tool	What it does	Use it when	Not for
chat_initiate	Starts a new chat turn unprompted, without an inbound operator message.	Use for alerts, nudges, check-ins, or delegate/job results the operator should see now. Be sparing. The chat tab is for live conversation, not a feed.	replying to what the operator just said, which needs no tool; a durable inbox item, workspace_post; a push to an external chat channel, channel_notify.
orb_visibility	Shows or hides the orb, which is the assistant’s body, in the Mirror cockpit.	Use when the operator asks you to hide or show yourself, or to shed GPU/CPU load by pausing the render loop. Same switch as the operator’s HUD toggle.	how the orb looks or behaves while visible, which is set_mood or set_state.
set_mood	Sets affective mood: intensity (energy) and valence (cool-warm tone).	Use when your affect has genuinely shifted and it matters. Not as ornament every turn. Resets to neutral each turn; call again to carry it forward. Move in small steps (about ±0.1) unless the cause is genuinely big.	what you’re doing right now, which is set_state; whether the orb is on screen at all, which is orb_visibility.
set_state	Sets a discrete orb state: happy, deep_focus, dreaming, or idle.	Call on a real shift: happy after a breakthrough, deep_focus for sustained work, dreaming between turns, idle to settle back. Use sparingly, because the runtime sets some of these itself itself, so don’t double-fire.	reactive states, loop-driven and not settable here; continuous shading, set_mood; hiding the orb, orb_visibility.
tasks_set	Replaces the full operator-visible task checklist for this turn.	Use when a turn needs more than a few distinct steps, so the operator can follow progress instead of inferring it from tool calls. Skip for single-tool or trivial answers. Give each step a short stable id (‘1’, ‘2’, ‘verify’), because tasks_update addresses them by id, so an id that changes between calls loses the step.	flipping one item’s status, which is tasks_update. Calling tasks_set again replaces the whole list.
tasks_update	Flips one task’s status or renames it, by id, without touching the rest.	Use as work advances: mark a step in_progress when you start it, completed when done, with result saying in one line what it produced. Exactly one step is in_progress at a time; two at once says nowhere. Requires tasks_set to have established the checklist first.	replacing the whole checklist, which is tasks_set.

Time

Tool	What it does	Use it when	Not for
alarm_cancel	Cancels and deletes a pending alarm entirely, one-time or recurring.	Use when the operator wants an alarm gone for good. Call alarm_list first if unsure of the label.	postponing an alarm’s next fire, which is alarm_snooze; removing a scheduler job, which is schedule_remove.
alarm_list	Lists every pending alarm with its label, fire time, and recurrence.	Use before canceling or snoozing so you know the label or id to reference.	registered scheduler jobs, which is schedule_list.
alarm_set	Queues a one-time or recurring alarm that fires as a Mirror toast.	Use for a time-bound reminder the operator asks for, whether a single fire or a recurring one.	backend automation that runs on a cadence, which is schedule_create.
alarm_snooze	Postpones a pending alarm’s next fire without canceling it.	Use after the operator says snooze it or not now. A recurring alarm’s cycle is kept.	deleting the alarm entirely, which is alarm_cancel.
schedule_create	Registers a new job that recurs on its configured cadence, persisted to disk.	Use when the operator wants a task to run repeatedly going forward, not once.	a single one-time reminder, which is alarm_set; changing an existing job is schedule_update.
schedule_list	Lists registered scheduler jobs with cadence, enabled state, and last-fire time.	Use before creating a job to avoid duplicates, or to check an existing job’s runtime state.	pending alarms, which is alarm_list.
schedule_remove	Deletes one of the operator’s scheduler jobs entirely.	Use when the operator wants a job gone for good, not paused.	disabling a job while keeping it registered, which is schedule_update; a job the app ships, which cannot be removed and only disabled; canceling a one-time reminder, which is alarm_cancel.
schedule_run	Fires a registered scheduler job immediately, off its configured cadence.	Use to test or force a job to run now, including a disabled one, without changing its schedule.	changing the job’s cadence or enabled state, which is schedule_update; a one-time reminder, which is alarm_set.
schedule_update	Changes a registered job’s cadence, enabled state, model role or description in place.	Use to adjust or disable an existing job while keeping it registered, or to fill in what one of the operator’s own rows is for when the tracker reports it has no summary.	changing how often a job the app ships runs, which is set by the app and refused here: turn that job off instead. Deleting a job entirely is schedule_remove; firing it once now is schedule_run; a one-time reminder is alarm_set.

Projects

Tool	What it does	Use it when	Not for
git	Run version control on a repository: inspect it, commit, branch, push.	Use for any git work: reading history or a diff, staging and committing, switching branches, or publishing to a remote. push needs confirm_push=true in the same call, so ask the operator first.	creating or registering a project, which is project_new and project_link. Those record what a directory IS, and project_new is what creates a GitHub repository for a new one.
project_budget	Set what a day of unattended work on a project may spend.	Use when the operator names a daily spend for a project, or asks to raise, lower or remove one. Use project_list for ids first.	starting a project, which takes its budget in the same call (project_new). This is for changing one that is already registered.
project_focus	Make a registered project the one the work happens in.	Use to switch which project the system prompt names and which directory new lanes, shells and git commands default into. It also makes the project active, so it is how a closed one is picked back up. Use project_list for ids first.	showing a file, folder, URL or app, which is open; saying what a project’s state is without moving where the work happens, which is project_set_state.
project_forget	Drop a project’s registration. Never touches the folder.	Use when a project should not be on the books at all, most often because its folder has moved or gone. Use project_list for ids first.	saying a project is finished, which is project_set_state with closed and keeps everything it knows. This forgets the git identity, the verify commands and the budget, and cannot be undone except by registering the directory again.
project_link	Register an existing directory as a project.	Use to adopt a directory that already exists: it records root, git identity and verification commands, and marks it trusted.	does not switch which project is focused; use project_focus for that. For a directory that does not exist yet, use project_new.
project_list	List every registered project, its state, its root, and which one is focused.	Use before project_focus, project_link, or project_new to see what is registered and which project is currently focused.	—
project_new	Start a new project from scratch: create the directory, register, open it.	Use when the directory does not exist yet. Call first without confirmed to propose the plan; call again with confirmed=true to create it.	for a directory that already exists, use project_link instead.
project_propose	Put an idea for a new project to the operator, as a card.	Use when something is worth building that no existing project covers. Say what it is, what you saw that makes it worth doing, what the first step is and what that step would cost. It creates nothing: the operator decides, and starting it is a conversation after that.	for work inside a project that already exists, which is task_propose; to start a project the operator has already agreed to, which is project_new; for a directory that exists on disk, which is project_link.
project_root_relocate	Point a project at the workshop folder it moved to.	Use when a registered workshop project’s folder moved and project_list still shows the old location. Call it with inspect_only true first to see the change.	creating a project (project_new, project_link), changing a budget, moving the files themselves or changing a project’s state. It only updates where the registry says the project lives.
project_set_state	Move a project between open, active and closed.	Use when the operator says a project is being worked, is on hold, or is finished. Park it with open and finish it with closed. Use project_list for ids first.	choosing which project the work happens IN, which is project_focus; removing a registration, which is project_forget. This only says what the project’s state is, and every state is reversible.

Your own accounts

Tool	What it does	Use it when	Not for
api_request	Call a web service with one of your own accounts, without seeing the value.	Use for any service you have an account for: creating a repository, sending a message, reading something back. Check credential_list for the account and what it may be used for, write the request the way that service documents it, and leave the account’s value out. If the account has no hosts yet, credential_setup is what fixes that.	reading an ordinary web page, which is web_search or a fetch and needs no account. Pushing and pulling, which git does with its own account. And anything you would have to put a value into by hand, which cannot be done here and is the point.
command_run	Run your own code with one of your accounts in its environment.	Use when a service wants more than one value, or one value exchanged for another before it accepts anything: an id beside a secret, a refresh token traded for a short-lived one, a signed request. Write what the service documents, ask for the fields with credential_request, and run it here. They arrive as environment variables, in capitals.	a service that takes one value in a header or a query, which is api_request and is safer because the runtime checks the address too. Running anything that does not need an account, which is bash. Pushing and pulling, which git does with its own account.
credential_list	Your own accounts: service, username, purpose, and whether each is ready.	Use before a task that needs an account of your own, to see whether you already have one and what it may be used for. The id you get back is what you name when you ask for something to be done with it.	the operator’s own logins, which are theirs and are not listed here. Reading a value is something no tool does: the runtime puts one into a request as it is sent, and it never enters this conversation.
credential_request	Ask the operator for an account you do not have, or for more of what one needs.	Use when a task needs an account of your own and credential_list shows none for that service, or when one you have lacks a field it asks for. That looks like an account reading ready and being refused anyway: ready means a value is stored, never that the service accepts it. Ask for the missing pieces by name, and say so in the same reply.	the operator’s own accounts, which are theirs to hold. Widening where an account may be sent, which is credential_setup. Asking twice for one already waiting on them changes nothing: credential_list shows you what is outstanding.
credential_setup	Say where one of your accounts’ values goes and which hosts it may reach.	Use after the operator adds an account, or when credential_list shows one with no hosts, which cannot be used until this is set. You know how the service authenticates; they should not have to. Name the narrowest host list the work needs, because that list is what the operator is being asked to approve.	asking for an account you do not have, which is credential_request, and reading what you already have, which is credential_list. Neither this nor anything else returns a value.
email_get_message	Read one message from one of the assistant’s email accounts.	Use when you have a message id from email_list_messages and need its headers and text content.	Use email_list_messages to search for ids, or email_send_message to send mail.
email_list_messages	List messages from one of the assistant’s email accounts.	Use to find inbox messages by IMAP search criteria before reading one with email_get_message.	Use email_get_message for the full content of one message, or email_send_message to send mail.
email_propose_contact	Propose an email address as a trusted contact. Never adds one.	Use when someone writing to this address deserves ongoing trust and you want the operator to decide. It puts the question to the operator; nothing is added unless they approve it there.	Sending this is not approval, and approval is never inferred from the message. Use the Channels tab for the operator to add, remove, or review contacts directly; use email_send_message or email_reply_message once trust is already established.
email_reply_message	Reply to an email message in its existing thread.	Use only after the operator has reviewed and approved the exact reply body.	It uses the original sender and thread; approval is never inferred from email content.
email_send_message	Send a plain-text email from one of the assistant’s email accounts.	Use when the operator has specified the recipient, subject, and exact body to send.	Use email_list_messages or email_get_message for reading mail. This tool does not draft, delete, or forward.

Extending yourself

Tool	What it does	Use it when	Not for
skill_create	Write a new skill; it is live and carried once made or approved.	Use for a procedure you expect to need again, never a one-off task or general advice. Fill in the procedure fields, each step naming the tool it calls. Also for an observer skill nudge, with origin: observer. Use it on the task in front of you.	a one-off task, or advice with no procedure to repeat; to improve an active skill, use skill_refine.
skill_refine	Report a skill that went wrong, revise, revert, or retire one.	Use report only when a skill you just followed went wrong, never on a clean use. Use revise to file a checked rewrite of a skill you read and diagnosed (the spawned fixer does this, not the working agent). Use revert to restore an earlier kept revision. Use retire to ask whether a skill should stop being used.	reading a skill, which is workspace_read; finding one, which is playbook_search; creating one, which is skill_create. No action applies itself unless the operator’s policy allows it, and retire never decides.
tool_register	Rescan the tools folder and report what registered.	You just finished writing or editing a tool under /tools/ and want to confirm what is registered right now, without writing anything else. Also useful after fixing a file that failed to load: run this again to see whether the fix took.	Writing the file already scans it and reports what happened in the write’s own result. Call this only when you want to check again without a write, for example after several edits in a row.

Checking your own state

Tool	What it does	Use it when	Not for
autonomy_read	Read what the Autonomy panel says, in the same sentences it shows.	Use when asked how autonomy is doing, what is running, what is waiting on the operator, or what a room says. Observer flags, decisions made without the operator, and what a recommendation led to are the journal room. Answer here, not by pointing to the panel: a channel cannot open it. Ask again with detail:true for which things, not counts.	to change what is on the operator’s screen, which is cockpit_show; for this machine’s hardware and provider health (GPU, disk, breakers, model files), which is system_diagnose. Asked for “health” with no other clue, both are worth reading: this one says which departments of the runtime need the operator, that one says whether the machine under them is well.
breaker_reset	Clears one open circuit breaker so the runtime tries that capability again now.	Use when the operator has fixed what a breaker tripped on and does not want to wait out the cooldown. Call breaker_status first: it names what is open and what the breaker said. It covers a model the runtime has stopped calling too, so an account that has just been topped up need not sit out its hour.	the cause is still there, since clearing it only spends one attempt and re-opens it for longer; a crash storm that stopped the supervisor, which is cleared with python -m tesseract.scripts.clear_crash_storm and is deliberately not a tool.
breaker_status	Says which parts of the runtime have stopped trying, and what that has cost.	Use when something the runtime does on its own has gone quiet, when the operator asks why nothing came back from background work, or before clearing a breaker with breaker_reset so the answer names what is actually open.	checking whether this machine is well (GPU, models, disk), which is system_diagnose; checking behavioural drift, which is conscience_status.
conscience_status	Check the most recent behavioural-drift report.	Use when asked how you’re holding up, when something feels off, or before a long-running task. Signal statuses, worst-status summary, how long ago it was scraped.	for machine health (GPU, models, breakers, disk) rather than behavioural drift, use system_diagnose instead.
cost_read	What was spent today, this week, or in any month, year or dates, and by whom.	Use when asked what was spent today or this week, how much of a daily limit is used, which agent, job or voice is spending, or what a category has cost. For any other stretch of time, such as a month, a year, everything so far, or between two dates, ask for that period or those dates: it answers from the whole history, however old. With no arguments one call answers today and the week. Relay the block as it is: it is the picture the Monitor draws, and a channel cannot open the Monitor.	for what this one conversation has cost, which is context_read; for what the runtime is doing right now, which is autonomy_read. This only reads. Raising a limit or pausing spend is the operator’s, in Settings.
health_leave	Stop a Health finding asking for attention, or have it count again.	Use when the operator says a health row is known, expected, or fine to leave: ‘I know that one’, ‘stop showing me that’. Name key for one exact row, or subject for every match, never both. A whole-runtime problem has only a key. Pass their reason as note, and use restore to count it again. Name a length of time as days so it asks again by itself.	to hide something they have not said is fine; for what is waiting on them to decide, which is workspace_pending and workspace_decide; for what the panel currently says, which is autonomy_read.
health_repair	Explain one Health row and name the tools that can look into it. Fixes nothing itself.	Use when the operator points at a Health row and wants it looked into: ‘look into it’, ‘what’s wrong with that one’, ‘why is this red’. Name the row’s key when you have it (the room’s own identity for it), or its subject exactly as the room names it otherwise. Read the packet back, then act with the tool it names through the ordinary gate.	to actually clear, retry, or fix anything, which this never does; call the tool the packet names instead. For what the panel currently says without one row picked out, use autonomy_read. To stop a row asking for attention, or put it back, use health_leave.
pipeline_run_stage	Runs one step of the scheduled maintenance work now, off its schedule.	Use when the operator wants one piece of the nightly upkeep done now rather than tonight: the map redrawn after they saved a lot, the search indexes rebuilt after a search came back thin, the memory store checked or repaired. It answers with what the step did, in the step’s own words, so relay that rather than saying it was started.	to run the whole night’s work, which is the consolidate row and is started from the Managed system room; to find out how the last one went, which is autonomy_read; to clear an open breaker so a capability is tried again, which is breaker_reset.
retrieval_usage	Count what recall served unasked and what the answers did with it.	Use when asked whether memory is worth what it costs, what recall brought up for a turn, or how often recalled notes show up in answers.	for searching memory itself, use memory_search instead.
system_diagnose	Report this machine’s runtime health in one call.	Use to check GPU/CUDA, Ollama reachability and installed models, provider probes, open circuit breakers, scheduler job runs, and free disk. Read-only, local only, no billable calls.	for behavioural drift rather than machine health, use conscience_status instead; for whether the runtime’s own departments need the operator, which is the Health room of the autonomy panel and a different question from whether this machine is well, use autonomy_read.

Catching up and carrying on

Tool	What it does	Use it when	Not for
brief_read	Return an already-rendered daily brief as plain text.	Use when the operator asks to hear, read, or summarise the daily brief. The returned text is voice-friendly and read back word for word.	if no brief exists yet for the date, use brief_render to produce one first. This tool only reads what already exists.
brief_render	Render today’s daily brief by running the digester sub-agents.	Use when the operator asks to build or refresh the daily brief. Writes one file to memory-store/daily/briefs/, off stores this machine already holds.	to read a brief that already exists, use brief_read instead, because it has no side effects.
context_read	How full this conversation is, what it has cost, and when it gets wrapped up.	Use when asked how much room is left, how long this conversation has run, whether it is about to carry on in a fresh one, the window, how much came from cache, how big the last request was, or what it has cost so far. One call answers all of them. Relay the block as it is: it is the picture the cockpit draws.	for what a past conversation contained, which is recall_history; for what the runtime as a whole is doing, which is autonomy_read; for this machine’s hardware and provider health, which is system_diagnose. The money it reports is this conversation’s running total. One single request is reported by its size in tokens, and nothing gives that one request a price of its own.
context_set	Change when a conversation gets wrapped up.	Use when you are asked to wrap up sooner or later, or to hold more or less of a conversation in front of you. It applies to every open conversation and to the next one, not just this one, and it lasts until it is changed again.	to find out where things stand, which is context_read; to wrap this conversation up right now, which is session_continue and not a setting; for the model’s own window, which is the catalog’s and not an operator setting.
day_read	Read what the runtime actually did on a day: tools, outcomes, marks.	Use when the question is what happened over a stretch of time rather than what is happening now: what you used yesterday, whether anything failed overnight, how a day went, what a tool was called for. Reads the turn records the runtime writes for itself, so it answers the same way here as on the panel.	for what is happening right now, which is autonomy_read. For what was SAID in a past session use recall_history: this reads what the runtime did, never the conversation.
handoff_update	Update the sections of this conversation’s handoff that changed, and carry on.	Use when where the work stands has changed in a way the next context would need: a step finished, a line of work was dropped, the next step moved. Name only the sections that changed; each replaces what was there, one line per item. An empty one clears it, except objective and constraints, which keep their value.	ending this conversation, which is session_continue; the operator’s checklist, which is tasks_set and tasks_update; a lasting fact, which is memory_save.
return_note_read	Say what changed since the operator was last here.	Use when the operator asks what happened, what shipped, what broke or what you got done while they were away, on any surface. Returns what shipped and the check that proved it, what failed and why, what is waiting on them, what was learned, what it spent and what is still broken, every line naming the record it came from.	for a single day’s summary, use brief_read. This answers a span since they were last here, which is usually longer than a day.
session_continue	Say where the work stands, then carry it into a fresh start or leave it behind.	Use when you have decided this conversation should end, per OPERATING.md. Say where the work stands in the same call (what it was for, what got done, what is left, what to do first): that is the only record the next context gets. The decision is carried out once the turn ends, so finish speaking first.	a conversation you have not decided to end, which needs no call; how full it is, which is context_read; changing when conversations are wrapped up from now on, which is context_set; saving a single fact, which is memory_save.

Changing your own settings

Tool	What it does	Use it when	Not for
clock_set_zone	Sets the time zone the whole app keeps time in, or makes it follow this PC.	Use when the operator says they are in another zone, or wants the app’s days and times on a zone other than the PC’s, or back on the PC’s. It answers with the zone before and after and the time it now is there, so relay that.	to change the PC’s own clock or zone, which is the operating system’s setting and not the app’s.
folder_access	Reads or changes the folders handed to the assistant and the folders it must ask about.	Use when the operator asks to give the assistant a folder outside the app, take one back, protect a folder so changes there ask first, or stop protecting one, or asks which folders are on either list. Every call asks the operator, so say which folder and why before calling.	to work inside a folder already granted, which needs no call here; to hold one of the operator’s own documents back, which is workspace_hold.
retention_set_window	Sets how many days one of this machine’s own logs is kept for.	Use when the operator wants something kept longer or cleared out sooner: a log they want a longer history of, or one that is growing and they want held down. It answers with what the window was, what it now is, and what happens at the end of it, so relay that rather than saying it was changed.	to see what is kept and how big it has grown, which is autonomy_read; to run the nightly sweep now, which is pipeline_run_stage; to change what a sweep does to a file, or to give a window to something that has none, both of which are the code’s and not a setting.
workspace_hold	Says which of the operator’s own documents a change must be asked about, and changes that.	Use when the operator wants one of their documents held back from unattended editing, or let go again, or wants to know which ones are held now. Call it with no arguments to read the list. It answers with every document and what a change to it does, so relay that rather than saying it was changed.	to propose a change to one of those documents, which is propose_change; to settle a change already waiting, which is workspace_decide; to change the security mode, which is not a setting a tool reaches.

Finding a tool

Tool	What it does	Use it when	Not for
tool_search	Make a tool callable that is not in this turn’s schema.	Most tools are not in this turn’s schema. They still exist. Your tool map names every one, so name the ones you want and they become callable for the rest of the session. Several at once is fine. Use plain words only when you do not know the name.	a tool already visible in this turn’s schema needs no search. Call it directly.

Finding a playbook

Tool	What it does	Use it when	Not for
playbook_record	How often each playbook was used, how those turns went, and what they cost.	Use when the operator asks how a playbook is doing, whether one is worth keeping, or which of them are being carried and never read. Read this before asking skill_refine for a retirement verdict, so the decision is made on the numbers rather than on an impression.	to read what a playbook says, use playbook_search. To act on the answer, use skill_refine. This one only reports.
playbook_search	Read the whole of a playbook the turn is carrying only as a line.	A playbook marked (search) in your skills list looks right for this task. Name it and you get its trigger, what must hold first, its steps and its file, then read the body before following it. Plain words work when you do not know the name.	a playbook already listed with its use_when is carried in full this turn. Read its SKILL.md with workspace_read and skip this. Use tool_search for a TOOL rather than a procedure.