[DOCS] Client SDK Tool Runner capabilities and Missing Beta Headers

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://platform.claude.com/docs/en/agent-sdk/overview - https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use - https://platform.claude.com/docs/en/api/beta-headers

Section/Topic

1. The "Compare the Agent SDK to other Claude tools" section in the Agent SDK Overview. 2. The "Available beta features" list in the Beta Headers reference page.

Current Documentation

Regarding SDK Comparisons:

Agent SDK vs Client SDK: The Anthropic Client SDK gives you direct API access: you send prompts and implement tool execution yourself... With the Client SDK, you implement a tool loop. With the Agent SDK, Claude handles it. (Source: agent-sdk/overview)

Contradicted by:

Tool runner (beta): The tool runner provides an out-of-the-box solution for executing tools with Claude. Instead of manually handling tool calls... the tool runner automatically executes tools when Claude calls them. (Source: tool-use/implement-tool-use)

Regarding Beta Headers:
The central list at docs/en/api/beta-headers currently lists older headers but omits several required for new features documented elsewhere.

What's Wrong or Missing?

Issue 1: Contradictory SDK Capabilities
The documentation is inconsistent regarding the capabilities of the standard Client SDK. The Agent SDK overview claims the Client SDK requires manual tool loops, but the Tool Use documentation introduces the tool_runner which automates this process. This makes the distinction between the Agent SDK and the Client SDK unclear for developers choosing between them.

Issue 2: Out of Sync Beta Headers
The central "Beta headers" reference page is significantly out of sync with specific feature guides. It is missing critical headers required to use major new features. If a developer relies on the central list, their API calls will fail.

Missing headers include:

• computer-use-2025-11-24 (Required for Claude Opus 4.5 Computer Use)
• structured-outputs-2025-11-13 (Required for Structured Outputs)
• advanced-tool-use-2025-11-20 (Required for Programmatic Tool Calling)
• effort-2025-11-24 (Required for Effort parameter)

Suggested Improvement

For SDK Comparison:
Update the comparison table in agent-sdk/overview to acknowledge that the standard Client SDK now supports automated tool execution via the tool_runner (beta). Clarify that the unique value proposition of the Agent SDK is the persistent shell/filesystem context and higher-level agentic behaviors, rather than just the "auto-looping" capability.

For Beta Headers:
Update docs/en/api/beta-headers to include the complete list of currently active beta headers found scattered throughout the feature documentation (Computer Use, Structured Outputs, etc.) so there is a single source of truth.

Impact

High - Prevents users from using a feature

Additional Context

These issues represent major severity inconsistencies that can lead to implementation errors or incorrect architectural decisions by developers.

Links to conflicting pages:

• Agent SDK Overview
• Implement Tool Use
• Beta Headers Reference