Adding Tools to a Subagent

A subagent without tools can talk. A subagent with tools can act — look things up in your systems, post to Slack, create tickets, update records. This guide covers how to pick tools for a subagent, what the difference between built-in and custom tools is, and how to update a subagent's tools over time.

Before you begin

How the tool whitelist works

Every subagent has a tool whitelist. Two simple rules:

  • Empty whitelist — the agent has access to every tool in the workspace (subject to project scoping). This is the least restrictive configuration.
  • Populated whitelist — the agent has access to only the tools you selected, plus the built-in delegation and scheduling tools that every agent always has.

Populate the whitelist. An empty whitelist is fine for experimentation but is almost never the right setting for an agent that will see real data or real customers. Tight whitelists make agents predictable, cheaper to run, easier to debug, and safer to share with teammates.

Built-in versus custom tools

Tools in your workspace fall into two broad groups.

Built-in tool packs ship with Assist. They cover common capabilities — web search, Slack, filesystem, knowledge base lookup, timezone math, map and location lookups, subagent delegation, scheduling. You can use them out of the box; they do not need to be built.

Custom tools are the ones you or your team build at /tools/new. They are how you connect Assist to your own internal systems — your WMS, your ERP, your CRM, your ticketing system, your homegrown APIs. Custom tools live in the dynamic_tools pack. A subagent uses them the same way it uses a built-in one.

The distinction matters in two places: the tool selector groups tools by pack so you can find them, and custom tools require one extra step (publishing) before a subagent can call them.

Steps

1. Open the subagent's edit page

Go to Subagents in the main navigation. Find the agent you want to configure. Click the pencil icon on the card to open the edit page.

2. Scroll to the Tools selector

The Tools selector shows every tool in the workspace, grouped by tool pack. Each pack is collapsible. The header for each pack shows how many of the tools in that pack are currently selected — so you can see at a glance what the agent has access to.

3. Search or browse

If you know what you're looking for, type a few letters into the search field. The selector matches against tool label, slug, description, and pack name. For browsing, expand the packs that look relevant.

4. Select the tools the agent should have

Click each tool you want to include. The count in each pack header updates. Keep it minimal — the smallest set of tools that can answer the questions the agent is supposed to handle.

A few heuristics for scoping:

  • Scope by system first. If the agent only answers questions about the WMS, include only WMS tools.
  • Read before write. If you are unsure, leave write tools out. You can always add them later.
  • Delegate don't duplicate. If another subagent already owns a domain, have this one delegate to that one rather than duplicating its tool set.
  • Include what the agent needs to reply. If the agent runs in Slack, include the Slack tool pack so it can post responses. If it needs to save notes across chats, turn on the filesystem (separate toggle — see agent filesystem).

5. Save

Click Save at the bottom of the edit page. Changes apply immediately. Any delegation, scheduled run, or channel-routed call made after you save uses the updated whitelist.

Updating tools on an existing subagent

Open the edit page, add or remove tools in the selector, save. The agent's next invocation — whether that's a chat, a scheduled trigger, or a channel routing — uses the new whitelist.

If you remove a tool the agent was relying on, it will tell you in its next run that it can no longer do the thing. If you add a new tool, the agent notices and starts using it when the agent's system prompt describes a use case for it.

If a custom tool isn't in the selector

Custom tools only appear in the selector once they have a published current version. A freshly created tool starts as a draft. To publish:

  1. Go to /tools and find the tool.
  2. Open it, then open the draft version on the edit page.
  3. Test it. When it behaves correctly, commit the draft to lock it as an immutable version.
  4. Publish the committed version to make it the current version.

Now it appears in the subagent selector. The draft/commit/publish flow exists precisely so that tool changes do not silently break production agents — you decide when a new version goes live.

Secrets, credentials, and permissions

Tools declare their own credentials and network permissions. When a subagent calls a tool, the tool executes in a secure runtime environment with a restricted filesystem and the exact set of environment variables and allowed network domains the tool was configured with. The agent never sees the underlying credential value.

This is why tool whitelisting is the right guardrail: by picking a tool for an agent, you are giving that agent exactly the access the tool was granted — no more. You do not have to separately configure credentials per agent.

If a tool fails because of a missing credential or OAuth connection, the fix is on the tool (/tools/<id>), not on the agent.

Observability

Every tool call your subagent makes is logged at /tool-history. You can see:

  • Which tool was called.
  • What input was passed.
  • What the tool returned.
  • How long it took.
  • Whether it succeeded or errored.

This is the first place to look when an agent's answer is wrong or missing. The tool history tells you whether the tool was called at all, and what it actually returned.

A good default whitelist

For an agent that answers operational questions in a Slack channel and uses a few internal-system custom tools, a reasonable starting whitelist is:

  • The specific custom tools for the systems the agent queries.
  • slack_v1 tools (at minimum, the send-message tool) so it can reply in the channel.
  • Nothing else.

From there, add more only when the agent's description grows to cover something the current whitelist cannot answer.

Related guides