Built-in Tools in the Claude Agent SDK

The full built-in tool set

The Claude Agent SDK ships with a complete set of tools out of the box. The same tools Claude Code uses. This is not a coincidence — they share the same engine, so the entire tool library is available to every agent you build.

Here is a quick map of the tool groups:

File tools. Read, write, edit files. Glob for pattern-matching filenames. Grep for searching file content. These are the core primitives for any agent that touches a codebase or document store.

Shell tools. The bash tool runs terminal commands. It is powerful and broad — it can execute arbitrary code, run CLI scripts, and interact with the operating system. That breadth is exactly why you want to be deliberate with permissions around it. More on that in a moment.

Web tools. websearch works like a Google search for your agent. webfetch reads a specific URL. Together, they let agents do competitive research, pull live data, and read documentation — without you having to build any integrations.

Interaction tools. The ask_user tool lets your agent pause, ask a clarifying question, and wait for a response. If you have built interactive workflows in Claude Code, this is the same mechanism, now available in your own deployments.

Sub-agent tools. Spin up independent sub-agents to handle parallel work. Each runs in its own context window. There is a dedicated section on sub-agent patterns later in this series.

Task management tools. The to-do list you see in Claude Code? That runs on these tools. You can give your agents the same internal planning capability.

Plan mode tools. Enter and exit plan mode programmatically. Useful for agents that should think before they act.

MCP tools. Connect external MCP servers to extend the tool set. Covered in the external MCP guide later in this series.

Skills tool. Loads skills from your .claude/ folder when settingSources is set to project. See the skills guide for how this fits a production workflow.

WorkTree tool. Lets an agent enter an isolated Git worktree. Mostly relevant for coding agent use cases, but worth knowing exists.

> Anthropic adds tools regularly. Because the Agent SDK stays in parity with Claude Code, any new tool that ships in Claude Code will appear here too. Worth checking the SDK changelog periodically.

Controlling which tools the agent can use

By default, the SDK enables every tool. For most production agents, you want to be more deliberate. There are two separate mechanisms, and they work differently.

The tools array: an allow list

Pass an array of tool names to the tools option and the agent can only use those tools. Everything else is invisible to it.

for await (const message of query("What files are in this directory?", {
  tools: ["read", "glob", "grep"],
  permissionMode: "bypassPermissions",
  dangerouslyAllowBypassPermissions: true,
})) {
  // handle messages
}

This agent can read, glob, and grep. It cannot write files, run bash commands, or search the web. For a read-only research workflow, that is exactly the right scope.

The disallowedTools array: a block list

Pass tool names here to remove them from the agent entirely. The agent can use everything except those tools.

for await (const message of query(prompt, {
  disallowedTools: ["bash", "write"],
  permissionMode: "bypassPermissions",
  dangerouslyAllowBypassPermissions: true,
})) {
  // handle messages
}

This agent has full access to every tool except bash and write. Useful when you want broad capability but need to protect file writes or prevent arbitrary command execution.

A critical distinction: tools vs allowedTools

The SDK has a third option called allowedTools that behaves differently than you might expect. It is a permission level override, not a tool allow list. Tools listed in allowedTools bypass the permission callback — they get auto-approved regardless of mode.

The tools array is what controls which tools the agent can see at all.

This naming is confusing and is currently mislabeled in the official docs. The behavior is:

> Operator note: For agents you deploy to client workflows, the tools array is your primary safety lever. Scope it tightly to what the task actually requires. A client-facing research agent does not need bash. A reporting agent does not need web_search. Explicit allow lists are easier to reason about than broad denylists.

How tools and permission modes interact

Tools are checked before permission mode. If a tool is not in your tools array, the agent cannot use it even in bypassPermissions mode. The evaluation order is:

1. Is the tool in the tools array? If no tools array exists, all tools are available. 2. Is the tool in disallowedTools? If yes, block it. 3. What is the permission mode? Apply accordingly.

This matters for operators: you can safely run bypassPermissions for fast, autonomous workflows as long as you have scoped the tool list correctly. The permission mode does not override your tool list.

---

Author: FractionalSkill