Tools
The built-in tools that let agents work with files, shell commands, the web, skills, memory, connectors and sub-agents.
Tools are the actions that your agents can do. Each tool gives an agent one capability, for example to read files, run commands or search the web.
Some tools are always available. You turn on the other tools for each agent when you deploy or edit the agent in Desktop.
Turn tools on and off
In Desktop, open the agent page, click the Configuration tab and open the Tools card. You select tools by group. Click Select all to select all the groups. Then click Save. After you save, Desktop shows Tools updated — restart the agent to apply changes.
The deploy wizard has the same groups.
| Group | Tools |
|---|---|
| Read & Search | read, ls, find, grep |
| Modify Files | write, edit |
| Shell | bash |
| Web | web_search, web_fetch, browser |
| Skills | create_skill, install_skill, remove_skill |
| Manage Connectors / MCP Servers | mcp, mcp_add_server, mcp_list_servers, mcp_remove_server |
If an agent has no tool list, it gets read, bash, edit, write, grep, find and ls.
These tools are always available and are not in the tool list: load_skill, the memory tools, task, get_location, ask_user_question and the sub-agent tools. The chat and name tools are also always available.
File tools
The file tools use the workspace of the agent as their start folder. A relative path starts at the workspace. The tools also accept absolute paths and paths that start with ~.
Reads a file. Text files come back as text. The tool can also read images.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | The file to read |
offset | number | no | The first line to read |
limit | number | no | The maximum number of lines to read |
The tool cuts long text at 2,000 lines or 50 KB. Use offset and limit to read the rest of the text.
Shell
Runs a shell command and gives its output.
| Parameter | Type | Required | Description |
|---|---|---|---|
command | string | yes | The shell command |
timeout | number | no | The time limit in seconds. The default is 120 seconds. The maximum is 1800 seconds. |
If the time limit ends, the HQ stops the command and all the processes that it started. The tool then fails and gives the output to that point. Stop stops the command immediately.
The command starts in the workspace of the agent. If the output is longer than 2,000 lines or 50 KB, the tool keeps only the end of the output. It writes the full output to a temporary file and tells the agent its path.
Web
Searches the internet with Brave Search and gives a list of results.
The search stops after 30 seconds. This limit covers the full request and its results. To stop a search sooner, select Cancel response in Chat.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | yes | The search query |
count | number | no | The number of results (default: 10, maximum: 20) |
This tool needs a Brave Search API key. In Desktop, go to Settings → Agent defaults and add the key in the Web Search section. If there is no key, the tool gives Web search API key not configured.
Skills
The load_skill tool is always available when the agent has skills. With it, the agent reads the full instructions of a skill when it needs them. You do not turn on load_skill.
The tools in this section let an agent manage its own skills. You must turn them on. Refer to Skills for more information.
Creates a skill that stays available in future conversations.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | The skill name (lowercase letters, digits and hyphens, maximum 64 characters) |
description | string | yes | When to use the skill. The agent uses this text to find the skill. |
content | string | yes | The full skill instructions, in Markdown |
trigger | string | no | A word or phrase that starts the skill |
tools | string[] | no | The tools that the skill uses |
tags | string[] | no | Tags to sort skills |
The tool also accepts model, context, allowed_tools and dependencies. The HQ keeps these values but does not use them.
The agent creates a skill when you tell it to remember a procedure or keep a workflow. The HQ writes the skill to the managed skills folder of the agent.
Memory
When memory is on for an agent, the agent gets the three tools in this section automatically. You do not select them. Refer to Memory for more information.
Saves or updates one memory that stays available in future conversations.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | A short, stable name (lowercase letters, digits and hyphens, maximum 64 characters). If the name exists, the tool updates that memory. |
description | string | yes | One line for the memory index, maximum 200 characters |
type | string | yes | user, feedback, project or reference |
content | string | yes | The memory, in Markdown, maximum 2,048 characters |
Each agent can keep a maximum of 200 memories. Sub-agents and swarm workers do not get this tool. They can only read the memory of the parent agent.
Other built-in tools
| Tool | What it does |
|---|---|
task | Keeps a task list for work with many steps. The agent sends the full list each time. Each item has an id, a content text and a status: pending, in_progress or completed. |
get_location | Gives the location that your app sent to this conversation: the time zone, the locale and the country or region. If you share your precise location, it also gives the position. It takes no parameters and never asks your device for a new location. |
Chat and name tools
Each squad member has these three tools. Sub-agents do not get them. You do not turn them on.
| Tool | What it does |
|---|---|
rename_agent | Changes the name of the squad member, or of a different squad member. agent is self or the name of a squad member. new_name has a maximum of 64 characters on one line, and no other squad member can have it. |
rename_chat | Changes the title of this chat, or of a different chat of the same squad member (chat_id). title has a maximum of 60 characters. |
start_chat | Starts a new chat for the same squad member, with a title and an optional message. If the agent sends a message, the agent starts work in the new chat immediately. The message has a maximum size of 16 KB. |
These limits apply:
rename_agentandstart_chatwork only in a turn that you started. Thus a squad member uses them only when you ask in the chat.rename_chatcan change a title that you set only in a turn that you started.rename_agentandrename_chatcan each rename one time in each turn.rename_agentcan rename one squad member 3 times each day.rename_chatcan rename one chat 10 times in 24 hours.
The chat shows a note for each change. For example:
- After a rename: Renamed this chat to “Trip plan”.
- In the old chat, after a new chat starts: Started a new chat: “Trip plan”.
In Desktop, click Open chat on that note to open the new chat. The new chat starts with a row that shows Started from and a link to the old chat. Refer to Desktop.
Integrations
Connects the agent to external tools and data through the Model Context Protocol (MCP).
When this tool is on, the agent can find and use the tools of the MCP servers that it can access. An agent sees only the MCP servers that you assign to it.
Some connectors require browser authorization before their tools become available. For a local HQ, open the authorization link on the same computer as the HQ and complete sign-in within five minutes. The callback uses that computer’s loopback address, so opening the link on another computer does not complete authorization.
If authorization is denied, cancelled or times out, authorize the connector again. The HQ can cancel a pending request through its management API. This keeps the saved connector configuration. Closing the Desktop dialog only stops its status checks; it does not cancel the HQ request.
If you remove the connector, dashsquad also removes its saved credentials. Successful authorization is saved for later HQ restarts.
Sub-agents
An agent can give a separate task to a sub-agent. A sub-agent is a child agent with its own context, its own tools and its own transcript. The child does not see the conversation of the parent. It gets only the prompt that the parent writes. When it is done, it sends one final report to the parent, and the parent tells you the result.
Sub-agents are on by default for all agents. The agent and send_message tools are always available and are not in the tool list. To turn off sub-agents, set limits or change how frequently an agent uses them, refer to Configuration → Sub-agents.
Starts a sub-agent for one task.
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | yes | The task. Write it so that it is complete, because the sub-agent does not see the conversation. |
description | string | yes | A short description (3 to 5 words). The chat shows it on the row of the sub-agent. |
subagent_type | string | no | The agent type to start (default: general-purpose) |
model | string | no | A different model: a provider/model ID, or inherit for the model of the parent. Refer to the note below the table. |
name | string | no | A name for send_message. Maximum 64 characters. It starts with a letter or digit, then letters, digits, _ or -. |
run_in_background | boolean | no | Run the sub-agent separately and get a notification when it is done (default: false) |
isolation | string | no | worktree gives the sub-agent its own git worktree of the workspace |
The model parameter also accepts short aliases such as opus or haiku. An alias works only if you configure it in subagents.modelAliases. If you do not configure the alias, the HQ writes a warning and uses the model of the parent. Refer to Sub-agent problems.
The tool gives an error result in these conditions:
- A limit is reached.
- The type is not known. The message lists the valid types.
- The requested model is not permitted.
- The definition gives the sub-agent no tools.
isolation: worktreeis set, but the workspace is not a git repository.
Foreground or background. By default, agent waits. The parent stops until the child is done, and the report of the child is the tool result. With run_in_background: true, the call returns immediately with Squad member <name> launched in the background. You will be notified when it completes. The child continues after the turn of the parent ends. Its result comes later as a notification.
Many at the same time. An agent can call agent more than one time in one turn. Those children run at the same time. If you cancel the turn, the HQ cancels its foreground children. Background children continue.
Built-in agent types.
| Type | Use | Tools |
|---|---|---|
general-purpose | Research, code searches and tasks with many steps | All the tools of the parent, but not the skill-management tools, the connector-management tools or the four legacy swarm tools. If the sub-agent can start sub-agents, it gets agent and send_message. At the nesting limit, it gets neither. |
Explore | Large read-only searches where you want only the conclusion | read, grep, find, ls, web_fetch, web_search, load_skill |
Plan | A plan with steps for an implementation | The same read-only tools |
Explore and Plan are one-shot. They are read-only and cannot get a new task, so send_message refuses a new task for them. An answer to a question is not a new task. Your own types and plugin types are not one-shot. One exception: a definition with the name Explore or Plan replaces the built-in type in that workspace. You can continue it as any other type.
Your own agent types. Put a Markdown file with Claude Code frontmatter into .dash/agents/ (or .claude/agents/) in the workspace of the agent. It then becomes a type that the agent can start. The frontmatter sets the name, the description, the tool list, the model and the skills to load first. The body is the system prompt.
Plugins can also supply types. Refer to Configuration → Sub-agent types for the file format. A sub-agent can never get a tool or an MCP server that its parent does not have.
Nesting. A sub-agent can start its own sub-agents, to the configured depth (subagents.maxDepth, default 3). The chat shows one level of nesting. When you expand a child, you see its transcript. The row of a grandchild shows there, but you cannot open it.
Notifications. When a background sub-agent is done, the HQ tells its parent in a new turn. This also occurs for a sub-agent that you continued or sent a message to. In the chat, you see a small notification row and then the response of the agent. If the parent is busy, the notifications wait and arrive together when its current turn ends.
What you see
Each sub-agent shows a collapsed row at the location where it started. The row shows the status, the type, the description, the number of tools it used and the time since it started. Click or tap the row to expand it. Then you see the transcript of the child live, with a box at the bottom to type to that child. When many sub-agents start together, one summary line groups them.
Each app also has a list of all sub-agents in the conversation:
- Web app: a Tasks button in the top bar, with a live count, opens a tasks panel. Each row has Stop and Resume.
- iOS app: a Tasks button opens a sheet. A strip above the composer shows while a sub-agent runs.
- Android app: open Tasks from the chat menu or activity strip. Tap a row to see the child. Use Stop or Resume to guide it. Resume opens a follow-up box. One-shot children accept only answers while they wait.
- Desktop: the people icon in the chat header opens the Sub-agents panel, with Stop, Resume and the transcript of the child. The icon shows when the conversation has sub-agents, or when the Swarm card of the agent is on.
Only the chat apps show sub-agent rows. In Telegram or WhatsApp, you get only the final answer of the agent.
Squad messages
Squad messages need Desktop 0.16.0 or later. They are on by default. To turn them off for a squad member, clear its Messages options and click Save. If you start the HQ yourself, DASHSQUAD_LONG_HORIZON=0 turns them off for all squad members.
A squad member can send a message to another squad member on the same HQ. Two tools do this: list_agents and send_message. Only a top-level squad member gets these tools. A sub-agent does not get them.
Lists the other squad members on the HQ. For each one, the result has the name, a one-line description, the status (idle, working or disabled) and if it accepts messages. The tool has no parameters.
Delivery
A squad message starts a turn in a chat of the receiver. The HQ uses the chat of the thread. If there is no such chat, it uses the newest chat of the receiver. If the receiver has no chat, the HQ makes a new chat with the name Messages. If the chat is busy, the message waits in a queue until the chat is free.
Limits
These limits stop loops between squad members. You cannot change them.
| Limit | Value | When the limit applies |
|---|---|---|
| Messages in one thread | 12 | The thread pauses |
| Replies back and forth in one thread (hops) | 6 | The thread pauses |
| Messages from one squad member | 20 in one hour, 100 in one day | The HQ refuses the message |
| Different receivers in one turn | 5 | The HQ refuses the message |
| Messages in the queue of one receiver | 20 | The HQ refuses the message |
| The same message to the same receiver | 1 in 10 minutes | The HQ refuses the message |
A paused thread waits for you. You can resume or close it. When you resume a thread, it can have 12 more messages and 6 more hops.
Refusals
| Reason | What it means |
|---|---|
messaging_off | The sender cannot send messages. Its Can message other agents option is clear. |
not_accepting | The receiver does not accept messages, or you disabled the receiver. |
rate_limited | The sender reached a limit for each hour, each day or each turn. |
duplicate | The sender sent the same message to the same receiver in the last 10 minutes. |
thread_paused | You or a limit paused the thread. |
thread_closed | You closed the thread. The HQ does not accept replies in a closed thread, and it does not deliver the messages in its queue. A new message starts a new thread. |
recipient_queue_full | 20 messages wait for the receiver. |
budget_reached | The receiver reached its daily limit for work without you. |
self | The squad member tried to send a message to itself. |
channel_turn | The turn came from a messaging-app chat that anyone can write to. To let it send messages, limit the chat to known senders in Settings → Messaging Apps. |
To turn messages on or off for a squad member, refer to Squad members → Messages between squad members.
Legacy swarm tools
spawn_worker, wait_workers, send_to_worker and check_workers are the earlier swarm tools. They continue to work. They show together with agent and send_message when sub-agents are on. They now use the same system as the sub-agent tools, so that old prompts continue to work. Use agent and send_message for new agents.
Important points:
spawn_workeris anagentcall withsubagent_type: general-purposeandrun_in_background: true. Therolebecomes the description of the child. If the role is a valid name, it also becomes the name.send_to_workerdoes the same assend_message. Thus it continues a worker that is finished and does not refuse it. When it refuses a message, it gives a "not ok" result.send_messagegives an error that the agent sees as a failed tool call.wait_workersandcheck_workersread the same children as the sub-agent tools.- Workers and sub-agents share one set of limits.
- A worker is read-only by default. If you do not give
tools, it getsread,grep,findandls, but only the tools that the parent has. - If the
subagents.allowedTypesof an agent does not includegeneral-purpose, the agent refusesspawn_worker. A worker can start its own sub-agents.
Limits. The limits of the agent control the children that it can start. There are limits for children at the same time, children in each turn, messages to each child, and time. There is also a limit for the full HQ.
Refer to Configuration → Sub-agents. If a call goes above a limit, it fails with an error result, and the chat shows an error tool block. The agent can then change its plan.
Starts a worker with a role and a complete brief.
| Parameter | Type | Required | Description |
|---|---|---|---|
role | string | yes | A short role or name for the worker, for example researcher |
brief | string | yes | A complete brief: the goal, the related files and paths, and the report to send back. The worker does not see the conversation. |
tools | string[] | no | Some of the tools of the parent for the worker. The default is the read-only tools. |
model | string | no | A model ID for the worker. It must be a permitted model. The default is the model of the parent. |
The tool gives an error result if a limit is reached or the model is not permitted. It also gives an error if the parent does not have a requested tool.
A worker is a sub-agent. Thus it gets ask_orchestrator, and it shows the same row in the chat. You can watch and control a worker from the tasks panel, the tasks sheet or the Sub-agents panel in Desktop. Refer to Architecture → Sub-agents.
Questions for you
Sometimes an agent must make a decision that only you can make. Then it does not guess. It asks you with ask_user_question. The chat shows a card with a maximum of four multiple-choice questions.
Each question has 2 to 4 options with a short description. One option frequently has the label Recommended. Some questions let you select more than one option.
- Tap the options that you want. To type your own answer, select Other.
- Tap Submit to send your answers.
To skip the questions, tap ✕. In the Android app, tap Skip. The card then shows Skipped.
You can also type a usual reply. The model reads it as your answer, and the card shows Replied in chat.
In voice mode, the agent speaks each question and its options. You speak your answer.
The turn of the agent pauses until you answer or skip, so the agent does not continue on a guess.
The question card is available in the iOS app (iPhone and iPad), the Android app, the web app and Desktop. All agents get ask_user_question automatically. It is not in the tool list.
Workspace
Each agent has a workspace: the folder where it works. The default is <dataDir>/workspaces/<agent-id>, in the data directory of the HQ. You can set a different path when you deploy or edit the agent. The HQ creates the folder if it does not exist.
The workspace is the start folder for the file tools and for bash:
- Relative paths start at the workspace.
ls,findandgrepsearch the workspace if you do not give apath.bashcommands start in the workspace.- Browser downloads go to a
downloadsfolder in the workspace, and browser uploads must come from the workspace.
Do not think of the workspace as a sandbox. The file tools and bash accept absolute paths and paths that start with ~. Thus an agent can read and change files outside its workspace, with the permissions of the user account that runs the HQ. Give file and shell tools only to agents that you trust.