Claude Agent Tool Integration Guide: Custom Tools, MCP, and Subagents

Claude agents can already read files, but to make them take on responsibilities in real workflows, you need to give them a capable set of tools. From custom functions to MCP servers to subagents, this toolchain determines how complex a task an agent can handle.

Custom Tools: From Functions to Agent Capabilities

Custom tools are essentially functions in your own code. Using the TypeScript tool function or the Python tool decorator, you declare a name, description, input schema, and handler, turning an ordinary piece of logic into a capability the agent can invoke.

The key detail lies in error handling: setting the return value to is_error: true lets you control what Claude reads when a tool fails. This isn't simply throwing an exception—it lets the model understand "what happened" and make decisions accordingly. Read-only tools are marked with read_only_hint, allowing them to execute in parallel and improving responsiveness in multi-tool scenarios.

MCP Servers: Unified Access to In-Process and External Services

Wrapping custom tools in an in-process MCP server, passing it via the mcp_servers parameter, and listing its MCP name in allowed_tools brings the tools into the agent's callable scope. The value of this mechanism is unification: whether local functions or external services, everything is exposed via the MCP protocol.

When you need external services, point the MCP server at a command or HTTP URL and allow it with a wildcard. The initialization message indicates which servers failed or need to be shut down—this is the first place to check for tool availability.

According to the video demo, when the number of tools reaches hundreds, tool search is enabled by default, and Claude only loads the subset needed for the current task. This solves the context pressure caused by tool proliferation and makes large-scale tool libraries practical.

MCP (Model Context Protocol) is an open protocol proposed by Anthropic for establishing a standardized communication contract between models and external tools/data sources. It abstracts the "tool provider" as a Server and the "tool caller" as a Client (i.e., the agent runtime), with both parties exchanging capability lists and invocation requests via JSON-RPC-style messages. The protocol defines primitives such as tools, resources, and prompts, and specifies the initialization handshake flow—which is exactly why the initialization message can report server status. The core value of MCP lies in decoupling: the same server can be embedded in a local process, run as a standalone process, or run as a remote HTTP service, without the caller needing to change code. This design allows the tool ecosystem to be reused across products and enables enterprises to encapsulate internal systems once and connect them in multiple places.

Subagents: Context Isolation and Budget Control

Subagents are defined in the agents option and added to the allowed tools list via agent. Each subagent runs in a fresh context and returns only the final message—meaning the main agent doesn't have to carry the intermediate process of subtasks, effectively saving context window space.

Budget control relies on the max_budget_usd parameter, which sets a spending cap for each subagent. For scenarios that call paid APIs or consume large amounts of tokens, this is a direct way to cage costs. The engineering of multi-agent collaboration is largely about designing such isolation and quota mechanisms.

Context window refers to the maximum total tokens a model can hold in a single inference, simultaneously carrying the system prompt, conversation history, tool definitions, and tool return results. When the main agent calls a subtask requiring many intermediate steps, intermediate artifacts such as retrieval results and trial-and-error logs continuously occupy the window, crowding out truly important information. The essence of the subagent mechanism is context isolation: subtasks run in independent windows, and only the final message is returned to the main agent, with the intermediate process "compressed" into a single conclusion. This is similar to the process isolation approach in software engineering—trading boundaries for controllability. The cost is information loss: the main agent cannot see the reasoning details of the subtask, so the subagent's final output needs to be self-contained and independently understandable, which places higher demands on prompt design.

Engineering Trade-offs in Tool Design

The design thinking revealed by this toolchain is worth pondering. Delivering error information as part of the tool output to the model treats the model as a decision-maker that can read state, rather than a passive executor. Trading read-only markers for parallel execution is an explicit trade-off between latency and resources. Tool search being enabled by default acknowledges the reality that tool scale will grow.

For teams building production-grade agent products, these mechanisms are not optional. Tool definitions, MCP integration, subagent isolation, and budget caps form the basic skeleton for an agent to move from demo to an operable system. The documentation covers the remaining details, but every link in the skeleton needs to be adapted to the specific product.

Tool search addresses the problem of tool scale proliferation. When an agent has hundreds of callable tools, stuffing all tool names, descriptions, and schemas into the context at once could consume a considerable token budget just for tool definitions, and would dilute the model's attention to the current task. Tool search works by first making the tool library a searchable index, and the model retrieves and loads only the relevant subset based on the current task semantics. This essentially transforms the "context budget allocation" problem into a retrieval problem, in line with the RAG approach—the difference being that the retrieval object is capabilities rather than knowledge. The risk is that inaccurate retrieval recall could cause the model to "not see" tools that are actually available, so the quality of tool descriptions directly determines the ceiling of this mechanism.

One-line Summary

From custom tools to MCP servers to subagents—building the toolchain skeleton for operable agents.

Paragraph Summary

The article systematically outlines three layers for building tool capabilities for Claude agents. At the most basic level are custom tools, declared with TypeScript's tool function or Python decorators specifying name, description, input schema, and handler, with is_error controlling what the model reads on failure and read_only_hint marking read-only tools to support parallel execution. The middle layer is MCP servers, unifying in-process functions or external command/HTTP services via the protocol, with initialization messages used to troubleshoot failed servers; when tools reach hundreds, tool search is enabled by default to load only what the task needs. The top layer is subagents, running in fresh contexts and returning only final messages to save the main agent's context window, with max_budget_usd limiting spending. The article concludes that these mechanisms form the basic skeleton for agents moving from demo to production systems.