Detailed Analysis
Anthropic's Claude Code documentation outlines a framework for extending the Claude Agent SDK through custom tool definitions, enabling developers to grant Claude structured, programmable access to external systems, proprietary databases, domain-specific logic, and third-party APIs. The mechanism centers on a tool abstraction composed of four required components: a unique name Claude uses as an identifier, a natural language description Claude reads to determine when invocation is appropriate, an input schema specifying required arguments (expressed as Zod schemas in TypeScript or type-annotated dictionaries in Python), and an asynchronous handler function that executes the tool's logic and returns structured results. These tools are bundled into an in-process MCP (Model Context Protocol) server using the `createSdkMcpServer` or `create_sdk_mcp_server` helpers and passed to Claude's `query()` function, with tool names following the namespaced convention `mcp__{server_name}__{tool_name}` to prevent collisions across multiple servers.
The documentation introduces a layered system for controlling tool access that distinguishes between availability and permissions. Developers register tools in an `allowedTools` list to pre-approve execution without triggering runtime permission prompts, and wildcard patterns such as `mcp__weather__*` allow blanket access to all tools within a given server. Critically, the same `tools` configuration array can be used not only to add custom capabilities but to selectively remove Anthropic's built-in tools from Claude's context entirely, giving application developers precise control over Claude's active capability surface. This bidirectional control — adding and subtracting — reflects a philosophy of least privilege, allowing production deployments to tightly scope what actions Claude is permitted to attempt.
Tool annotations represent a metadata layer designed to improve runtime scheduling and inform users about behavioral expectations, though the documentation explicitly notes they carry no enforcement weight. The `readOnlyHint` flag is the most consequential in practice: when set to `true`, it signals that a tool produces no side effects, enabling the SDK to invoke such tools in parallel and improve throughput in multi-tool workflows. Other annotation fields — `destructiveHint`, `idempotentHint`, and `openWorldHint` — are described as informational only, intended to communicate intent to operators and orchestration layers rather than constrain the handler's actual behavior. This design acknowledges a fundamental limitation in declarative tool systems: the runtime cannot verify that a handler annotated as read-only actually refrains from writes, placing accuracy responsibility on the developer.
The architecture described reflects broader trends in agentic AI development, where the central engineering challenge has shifted from model capability to capability governance. By routing tool access through a named, permissioned MCP server layer rather than giving Claude open function-call access, Anthropic enforces a separation of concerns between model reasoning and side-effecting execution. The documentation's note that every registered tool consumes context window space on every turn — and its recommendation to use on-demand tool search for deployments exceeding a modest tool count — underscores the persistent tension between extensibility and the finite context constraints of large language models. As agentic frameworks mature across the industry, this pattern of in-process tool registries with fine-grained permission lists is emerging as a de facto standard for balancing developer flexibility against operational safety, and Claude Code's implementation represents Anthropic's current production position within that design space.
Read original article →