Tool Reference

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 front matter. 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.

File and project

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. file_read is always available; file_read_hashline is the form a model on the hashline edit format uses. 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 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. Small successful search/replace edits can show a bounded unified diff when you expand the live tool card; replayed history and the model-visible result remain a one-line summary. 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. 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. 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.
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.

Shell and jobs

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.
job_status	Reports whether a background job is reserved, 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.

Work and delegation

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.
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. The plan facet uses this while researching.
handoff_plan	Submits the active plan for your review before handing the work off to another facet. This is the planning-to-execution transition; see Facets.
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.

Web and external

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.

Interaction

Tool	What it does
ask_user_question	Asks you one to four structured questions and waits for your answers. 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 front-matter key that controls which tools load up front.