Reference
Managed runtime tools
The 17 workspace, document, shell, and turn-control tools available inside managed agents.
On this page
Where these tools exist
These 17 tools belong to Arc's managed agent execution loop. They are not public stdio MCP tools and are not Python ArcClient methods. Workspace policy, room Safe/Full Access, connection capabilities, and task mode determine availability. Some are discovered only when needed.
submit_plan and answer_user are planning-mode tools, not part of every ordinary seat turn.
Existing-file writes require a fresh expected_sha256 even when the outer schema marks that property optional. Journaled writes remain inside the project. Shell side effects are not journaled. Read the workspace and shell guide before using them.
workspace_list
List workspace files by relative path; truncated results name the next offset.
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "relative directory; default ."
},
"recursive": {
"type": "boolean",
"default": true
},
"limit": {
"type": "integer",
"default": 200
},
"offset": {
"type": "integer",
"default": 0,
"description": "pagination offset"
}
},
"required": []
}workspace_read
Read a bounded UTF-8 file slice. Returns whole-file sha256 and the next start_line when truncated.
{
"type": "object",
"properties": {
"path": {
"type": "string"
},
"start_line": {
"type": "integer",
"default": 1,
"description": "1-based first line"
}
},
"required": [
"path"
]
}workspace_search
Search UTF-8 project files for literal text, case-insensitively.
{
"type": "object",
"properties": {
"query": {
"type": "string"
},
"path": {
"type": "string",
"description": "relative directory; default ."
},
"limit": {
"type": "integer",
"default": 50
}
},
"required": [
"query"
]
}workspace_document_inspect
Inspect a PDF locally without placing the whole document in context. Returns source SHA-256, page count, bounded metadata, and an honest text-layer status from a distributed page sample. Use this before a broad document task. Scanned/image-only PDFs are reported; OCR is not included in this release.
Available through on-demand discovery rather than the initial direct tool list.
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "relative path to a PDF"
}
},
"required": [
"path"
]
}workspace_document_read
Read bounded, page-labelled text from a text-backed PDF locally. Read at most 12 pages per call. A truncated result includes an exact next call, including start_character when one unusually dense page needs continuation. Text extraction does not preserve images or guarantee visual layout.
Available through on-demand discovery rather than the initial direct tool list.
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "relative path to a PDF"
},
"start_page": {
"type": "integer",
"default": 1
},
"end_page": {
"type": "integer",
"description": "inclusive; defaults to start_page + 4"
},
"start_character": {
"type": "integer",
"default": 0,
"description": "only use the continuation value returned for one dense page"
}
},
"required": [
"path"
]
}workspace_document_search
Search a text-backed PDF locally for literal text, case-insensitively, without dumping the document into context. Results carry PDF page numbers and bounded excerpts. A truncated search includes an exact next call.
Available through on-demand discovery rather than the initial direct tool list.
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "relative path to a PDF"
},
"query": {
"type": "string"
},
"start_page": {
"type": "integer",
"default": 1
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 50
}
},
"required": [
"path",
"query"
]
}workspace_write
Create/replace one UTF-8 file atomically. Existing files require expected_sha256; changes are undoable.
{
"type": "object",
"properties": {
"path": {
"type": "string"
},
"content": {
"type": "string"
},
"expected_sha256": {
"type": "string"
}
},
"required": [
"path",
"content"
]
}workspace_edit
Read the file first, then replace exact UTF-8 text. Requires expected_sha256; changes are undoable.
{
"type": "object",
"properties": {
"path": {
"type": "string"
},
"old_string": {
"type": "string",
"description": "must match once unless replace_all"
},
"new_string": {
"type": "string"
},
"expected_sha256": {
"type": "string"
},
"replace_all": {
"type": "boolean",
"default": false
}
},
"required": [
"path",
"old_string",
"new_string"
]
}workspace_history
List recent workspace mutations and their change ids/status.
Available through on-demand discovery rather than the initial direct tool list.
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"default": 50
}
},
"required": []
}workspace_recovery_status
Read the startup journal-recovery report. Mutation is blocked when ambiguous or tampered entries appear here; reads remain available.
Available through on-demand discovery rather than the initial direct tool list.
{
"type": "object",
"properties": {},
"required": []
}workspace_undo
Undo one exact workspace mutation. It refuses if the file changed after Arc wrote it. Pass the change_id returned by workspace_write.
Available through on-demand discovery rather than the initial direct tool list.
{
"type": "object",
"properties": {
"change_id": {
"type": "string"
}
},
"required": [
"change_id"
]
}shell_exec
Run one non-interactive host command. Past block_budget_sec it backgrounds (max 4 jobs); output is spooled (spool_id) — find shell_job/shell_output by search. Shell changes are not Arc-journaled or undoable; stdin_text is not an interactive terminal.
{
"type": "object",
"additionalProperties": false,
"properties": {
"command": {
"type": "string",
"description": "non-interactive command"
},
"cwd": {
"type": "string",
"description": "relative to the project folder, or any existing absolute host directory"
},
"timeout_sec": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 900,
"description": "default 120, max 900 s; also bounds a backgrounded job"
},
"block_budget_sec": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 60,
"description": "seconds before backgrounding to a job_id (the turn continues); default 15, max 60"
},
"stdin_text": {
"type": "string",
"maxLength": 65536,
"description": "UTF-8 stdin written once then EOF; max 65536 bytes; closed when omitted"
}
},
"required": [
"command"
]
}shell_output
Read one byte range of a shell command's complete spooled output (stdout and stderr interleaved in arrival order). Use the spool_id returned by shell_exec or shell_job and page with offset until eof is true. Bytes are decoded as UTF-8 with replacement characters.
Available through on-demand discovery rather than the initial direct tool list.
{
"type": "object",
"additionalProperties": false,
"properties": {
"spool_id": {
"type": "string"
},
"offset": {
"type": "integer",
"minimum": 0,
"default": 0,
"description": "byte position to read from; continue at offset + bytes"
},
"max_bytes": {
"type": "integer",
"minimum": 1,
"maximum": 65536,
"default": 65536,
"description": "bytes to read; at most 65536 per call"
}
},
"required": [
"spool_id"
]
}shell_job
Check one background shell job started by shell_exec. Returns status (running, completed, failed, timed_out, or killed), exit code, duration, spool_id, and new spooled output (tail=true re-reads the last 2 KiB). Do other work between polls, or wait for the [shell-job] room notice.
Available through on-demand discovery rather than the initial direct tool list.
{
"type": "object",
"additionalProperties": false,
"properties": {
"job_id": {
"type": "string"
},
"tail": {
"type": "boolean"
}
},
"required": [
"job_id"
]
}finish
Ask Arc to finish the assigned run. Arc validates the observable completion gates first; if anything is missing the tool result tells you what to do next.
{
"type": "object",
"properties": {
"summary": {
"type": "string"
}
},
"required": [
"summary"
]
}submit_plan
Submit the complete ordered plan for Arc to validate and record. This ends the planning turn; do not call it until the workspace has been inspected enough to name exact target files and observable acceptance criteria.
{
"type": "object",
"additionalProperties": false,
"properties": {
"summary": {
"type": "string",
"description": "one-line summary of the whole plan"
},
"subtasks": {
"type": "array",
"minItems": 1,
"maxItems": 12,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string"
},
"instruction": {
"type": "string"
},
"target_files": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
},
"acceptance": {
"type": "string"
}
},
"required": [
"title",
"instruction",
"target_files",
"acceptance"
]
}
}
},
"required": [
"summary",
"subtasks"
]
}answer_user
Return a substantive conversational answer without changing the workspace. Use this for questions, brainstorming, alternatives, recommendations, critique, or any request that does not clearly authorize file changes. Include the useful answer now, then offer to apply a chosen direction if appropriate.
{
"type": "object",
"additionalProperties": false,
"properties": {
"answer": {
"type": "string",
"description": "the complete answer to show in chat"
}
},
"required": [
"answer"
]
}