Tools
fx uses tools to read and edit files, run commands, and gather information. Describe what you need in your prompt; fx chooses the tools and shows their results in the conversation.
Built-in tools
| Tools | Description |
|---|---|
glob_files, grep_files, read_file | Find files, search their contents, and read them |
write_file, edit_file | Create or update files |
shell | Run commands, including interactive programs and development servers |
web_search, web_fetch | Search the web (AI Gateway) and read public URLs |
vision | Analyze images for models without image input (AI Gateway) |
install_skill | Install skills |
subagent | Delegate work to another agent |
toolbox | Open, run, or search skills, MCP tools, and the built-in tools kept in toolbox |
ask_user_question | Ask you for input |
read_tool_result | Search or read a stored tool result, or search turns saved by compaction |
Models with image input analyze attached images directly. See Vision.
The agent reads skills and uses MCP tools through toolbox. install_skill is in toolbox by default.
glob_files matches file paths with glob patterns. grep_files searches for literal text.
write_file and edit_file handle files up to 16 MiB. If an edit would exceed that limit, the tool returns an error so the agent can use a shell command instead. Saved sessions retain the edit's diff for Ctrl+O, with a notice when rows exceed the saved-text limit.
Toolbox
fx sends the same tools with every request in a conversation, so the model provider can reuse the cached start of the prompt. Skills, MCP tools, and the built-in tools kept in toolbox aren't sent as tools of their own. The toolbox tool lists them in a short menu instead: each skill with a short description, each MCP server by name, and each built-in tool in toolbox. The agent uses toolbox to:
opena skill, an MCP server, or a tool. A skill returns its instructions and a tool its definition. A server with up to 10 tools returns each tool with its arguments when they fit in 8 KiB; otherwise it returns its tools' names and what each does, and the agent searches it for the ones it needs. When a name is under more than one heading, such as a skill and a server that are both calledkit,kindsays which one to open.runa tool by its exact name, with its arguments.searchfor skills and tools by what they do. Each tool comes with its arguments, so the agent can run it next.serversearches one MCP server, so a server with many tools never fills the context, and with an empty search lists that server's tools;limitreturns up to 20 matches, 5 by default, andcursorgets the next page of a server's.
A run goes through the same permission checks as a direct call of that tool, and the conversation shows it as that tool. Opening a skill follows your rules for skill, opening an MCP server or tool follows mcp_select_tool, and a search follows capability_search, so rules written for those names keep working. An agent profile works the same way: one that lists toolbox or * can open and search everything, one that lists skill can only open skills, and one that lists a tool you keep in toolbox gets toolbox to run it. If you deny toolbox, the agent can't use anything in it, skills and MCP tools included.
The menu stays as fx first sent it for the rest of the conversation, for as long as fx runs. When you resume a conversation, fx builds the menu again. It's the same unless skills, MCP servers, or tool placement changed. When a skill or MCP server is added or removed, fx adds a note to the conversation that names what toolbox holds now. If the menu would pass its context limit, fx shortens its descriptions, then lists fewer entries; search still finds the rest.
Choose which tools are in toolbox
By default, install_skill is in toolbox and the other built-in tools are sent directly. Use tool_placement in ~/.fx/settings.json to move a tool either way:
{
"tool_placement": {
"web_search": "toolbox",
"install_skill": "direct"
}
}
Tools you don't name keep their default. You can move glob_files, grep_files, read_file, write_file, edit_file, web_fetch, web_search, shell, install_skill, subagent, ask_user_question, and read_tool_result. A workspace entry can set tool_placement for one project; a project .fx.json can't.
To change one tool from the command line:
fx config set tool_placement.web_search toolboxfx config unset tool_placement.web_search restores the default, and fx config get tool_placement.web_search shows where the tool is and which setting put it there. To move a tool for one run without saving it, put --tool-placement before the command, once for each tool:
fx --tool-placement web_search=toolbox --tool-placement shell=toolboxfx reads the placement when it starts. If you resume a conversation with a different placement, fx sends a different tool list, so that conversation's next request can't reuse its cached prompt.
Background commands
fx can keep a development server or file watcher running while it continues working. Ask it to check the output, send input to an interactive program, or stop a command:
Start the development server and keep it running while you update the homepage.
The shell tool uses run to start a command, interact to read output or send input, and stop to end it. A running command remains available across prompts in the same conversation.
While a command runs, each result tells the agent how long the command has run and how long it has printed nothing. After 2 minutes with no output, the result asks the agent to check whether the command is still working or has hung, since a server or watcher can stay quiet while it works. A wait on the command, such as an interact call, ends when the command reaches 2 minutes of quiet, before its yield_time_ms runs out, so the agent can check the command right away. If the command prints again and then goes quiet again, the next wait ends the same way. fx doesn't stop a quiet command; the agent decides whether to keep waiting, check on it, or stop it. A command running in a terminal, such as an interactive program, waits for input by design and gets no notice.
fx loads shell startup files once per process and reuses that configuration for later commands. Use /shell reload after changing your startup files; this also clears remembered command approvals. The agent can also reload them before a command, for example after it installs a tool. Terminals launched by the shell tool stop when fx exits and are not recovered on resume.
Large tool results
In saved conversations, fx stores large tool results separately and gives the model a preview and a handle. The agent uses read_tool_result to search that output or read a specific range, including after you resume the conversation. After context compaction, it also searches the turns and tool calls fx saved.
max_tool_result_bytes sets the tool output budget for model context. Results stored for later reads can exceed this budget.
Scope and permissions
File and command tools start from the primary workspace. Additional directories extend that scope. Tool actions follow your permission mode and rules.