These are the built-in tools Polytoken can expose to the model. The model
requests a tool call; Polytoken validates the input, runs the tool, and returns
the result. You decide which tools a facet exposes through the polytoken.tools
key in its frontmatter. Write the names from the table below as the values for
that key. See Facets for how granting works,
including the mcp__<server>, tag!ALL, and tag!ALL_MCP shorthands.
The editing and reading tools come in more than one form. A model’s edit format
decides which edit tool Polytoken registers, and a large-file read can come back
as a structural outline instead of whole-file content. Each form has its own
name, listed below. To expose editing without tracking which edit format a model
uses, list all of the edit-tool names, or use the tag!ALL shorthand, which
covers every tool.
| Tool | What it does |
|---|
file_read, file_read_hashline | Reads a file. For a file too large to return whole, Polytoken returns a structural outline of the file, and the model requests a specific range when it needs the lines. Models using the hashline edit format get file_read_hashline with editable line anchors; other edit formats get file_read. These tools can read an absolute path outside the project once you grant that path for the session. |
file_edit_search_replace, file_edit_hashline, patch_edit | Changes existing files. A successful search/replace edit returns a bounded diff snippet of the changed lines as the model-visible result. The expanded live cards can additionally show a bounded unified diff for small replacements; replayed history retains the full diff snippet. A model gets one edit tool, chosen by its edit format. List the names a facet’s models need, or use tag!ALL for every format. These tools need read and write approval to change existing absolute paths outside the project. When the hashline edit format is active, the model reads anchors (line#hash per line) and sends structured batch edits with replace, delete, insert_before, and insert_after operations in one request, all validated atomically before any write. When a model edits by sending a patch, Polytoken asks once for the filesystem approvals the patch needs. Patch edits are applied one change at a time; if a later change fails, earlier changes may remain. |
file_write | Creates a new file or overwrites an existing one. As a guard against accidental clobbers, it refuses to overwrite a much larger file with a very small replacement and directs the model to delete the file and re-create it. To change part of a file, expose an edit tool instead. It can write an absolute path outside the project after write approval. Expanded live tool cards can show a diff-style preview of the first 10 written lines with an omission note for longer content; replayed history and the model-visible result remain a byte-count summary. |
glob | Finds files by name pattern. Honors your ignore files and returns project-relative paths for project matches, sorted by modification time. It can search an approved external directory too; those matches are returned as absolute paths. The path field accepts one root or an array of roots; overlapping roots are deduplicated. When path is omitted and the pattern starts with a literal directory prefix, Polytoken checks permission for the directory before the first wildcard. For example, /path/**/something/*.md asks for read access to /path. Absolute literal patterns without wildcards check the literal path itself. |
grep | Searches file contents by regular expression and returns matching lines with surrounding context. It can search an approved external file or directory; project matches are project-relative and external matches are absolute. The path field accepts one root or an array of roots; overlapping roots are deduplicated. |
flag_important | Marks a file as important for the session so it survives compaction. In included mode, Polytoken inlines the file’s content; in referenced mode, it records a pointer to the file. |
| Tool | What it does |
|---|
shell_exec | Runs a shell command and returns its output. Polytoken runs the command in a non-login Bash shell and sets the working directory to the project root. |
shell_monitor | Runs a readiness check repeatedly until it succeeds or a deadline passes. Use it to wait for a process such as a server to start, not for one-shot commands. |
shell_service | Starts and manages a named long-running Bash process for the current session. Query, restart, or stop a service by name. Polytoken saves stdout and stderr to session log files and stops services when the session shuts down. Service names are permanent for the session. Use restart instead of stop followed by start when you want to replace a running process. After stopping a service, start the replacement under a new name. Set notification_match to a literal string to receive notifications for complete stdout/stderr lines containing that string anywhere. The default is agent-notification; an empty string disables matching. Notifications identify the service and output stream. Polytoken shortens long lines and summarizes excess matches while preserving the full logs. With automatic notification draining enabled, these notifications can start a new agent turn when the session is idle. |
pushd, popd | Changes the model’s effective working directory (pushd) or returns to the previous one (popd). Relative paths in file, glob, grep, and shell tools resolve from the new directory. The bare ~ and paths beginning with ~/ expand to $HOME. Directories outside the project require chdir permission approval, and approving one also grants read access to that directory. This is path relocation only; it does not change permissions or configuration. |
job_status | Reports whether a background job is reserved, queued, running, completed, failed, or cancelled. |
job_block | Waits for a background job to finish, up to a deadline. |
job_result | Fetches the output of a finished background job. |
job_cancel | Cancels a running background job. |
list_jobs | Lists async background jobs with optional filtering by type and liveness, plus pagination. |
| Tool | What it does |
|---|
subagent | Runs a configured subagent as a background job. The subagent works in its own context and reports back on completion. Optionally fork a prior subagent’s context by passing its job handle as resume_from. |
message_subagent | Sends a text message to a running subagent. Polytoken delivers the message before the subagent’s next step, never mid-response. Returns immediately. |
skill | Loads a skill’s instructions into the conversation. The model passes a skill name, and the loaded instructions become guidance for the current task. |
todo_create, todo_update, todo_complete, todo_delete, todo_list | Manage the session’s todo list. These are the same todos the sidebar and /todo show. Polytoken treats todo_create as lightweight batchable work and can run several todo creation requests from one model response. |
write_plan | Records a plan document for the session. A revised plan replaces the current plan file in place, so one planning effort keeps a single numbered plan file. After an approved handoff, Polytoken starts a fresh numbered plan file for the next planning effort. The plan facet uses this while researching. |
edit_plan | Edits the active plan by replacing one unique string. The plan facet uses this to fix the recorded handoff plan after review. |
handoff_plan | Submits the active plan for your review before handing the work off to another facet. The plan facet runs the built-in plan-reviewer subagent after the latest write_plan or edit_plan as a recommendation; you can skip it at the approval step. The handoff guard refuses newer or changed plan files until you confirm the active plan with confirm_plan_path. This is the planning-to-execution transition; see Facets. |
compact_context | Compacts the session context immediately instead of waiting for the automatic threshold, so the next step of a long plan starts with the most working context available. Compaction is an operator-instructed action; the model should not request it on its own initiative. Requires the context window to be substantially occupied; when the context is not sufficiently full, it returns guidance instead of compacting. The required directive says what to do once compaction finishes and may reference a skill with @skill:name; it is appended verbatim as the continuation after compaction. Long continuation directives that exceed the supported bound return guidance instead of queueing. An optional facet switches to a registered facet before compaction when the active facet exposes switch_facet; facets such as plan should use handoff_plan instead. A declined switch skips compaction, while a successful switch remains in effect if compaction later fails. |
propose_goal, read_goal, complete_goal, block_goal | Manage the active saved-session goal from model turns. propose_goal asks you to approve a model-proposed goal unless goal_driver.agent_goal_auto_accept is configured. read_goal shows the active goal and goal file content. complete_goal and block_goal move the goal to a terminal state and stop goal continuation. |
switch_facet | Switches the session to another facet, changing the system prompt and available tools while keeping the conversation. The model can call this only if the active facet lists switch_facet in polytoken.tools. The shipped execute facet lists it; plan does not. |
tool_flow | Runs a short Python-subset script that chains dependent tool calls from an approved list and returns the script’s final value. |
| Tool | What it does |
|---|
web_search | Searches the web and returns results with their URLs. |
web_fetch | Fetches a web page. Returns the page text, or extracts a specific answer when the model provides a query. |
mcp_list_resources | Lists the resources available from your configured MCP servers. |
mcp_read_resource | Reads a single resource from an MCP server by its URI. |
| Tool | What it does |
|---|
lsp | Gives the model symbol-aware code navigation through language servers that Polytoken spawns on demand: definitions, type definitions, implementations, references, document and workspace symbols, diagnostics, and cross-file rename. rename previews its edits by default; apply: true requests write approval for every affected path before anything changes on disk. status and a cold capabilities call never start a server process. |
| Tool | What it does |
|---|
ask_user_question | Asks you one to four structured questions and blocks the session until you answer. Every question allows a free-text answer. The model calls this tool when your answer would change its next step. |
tool_search | Looks up the full definition of a tool by name. Polytoken exposes this when the active model loads tool definitions on demand rather than all at once, or when MCP servers are configured. See Templating for the frontmatter key that controls which tools load up front. |