[DOCS] BetaMessage type includes ToolResultBlocks without explaining Server Tools behavior

Documentation Type

Unclear/confusing documentation

Documentation Location

https://platform.claude.com/docs/en/api/python/beta/messages

Section/Topic

Domain Types section, BetaMessage class definition

Current Documentation

The BetaMessage return type (which has role="assistant") includes tool result blocks in its content list:

- class BetaMessage: …
- role: Literal["assistant"]
- content: List[BetaContentBlock]
- class BetaWebSearchToolResultBlock: …
- class BetaCodeExecutionToolResultBlock: …

What's Wrong or Missing?

In the standard Anthropic Tool Use workflow:

1. Assistant sends tool_use blocks (requesting to use a tool)
2. User sends tool_result blocks back to the API (with execution results)

Including ToolResultBlock types in the assistant message's content definition contradicts this standard turn-taking pattern without explanation.

This appears to be intentional behavior for Server Tools (web_search, code_execution) where the API auto-executes the tool and returns results in the same response. However:

• This behavior isn't explained in the type definitions
• Users may be confused why result blocks appear in assistant messages
• The departure from standard tool use flow isn't documented

Suggested Improvement

Add clarifying documentation to the BetaMessage.content type definition:

Suggested addition:

Note on Server Tools: For server-side tools like web_search and code_execution, the API automatically executes the tool and includes the result in the assistant's response. This differs from standard tool use where results are sent back by the user in a subsequent turn. When using server tools, the assistant message's content may include both: - tool_use blocks (the tool invocation) - tool_result blocks (the server-executed results)

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | SDK | Context |
|------|-----|---------|
| https://platform.claude.com/docs/en/api/python/beta/messages | Python | BetaMessage type definition |
| https://platform.claude.com/docs/en/api/python/beta/messages/create | Python | Return type |
| https://platform.claude.com/docs/en/api/typescript/beta/messages | TypeScript | BetaMessage type definition |
| https://platform.claude.com/docs/en/api/ruby/beta/messages | Ruby | BetaMessage type definition |
| https://platform.claude.com/docs/en/api/java/beta/messages | Java | BetaMessage type definition |
| https://platform.claude.com/docs/en/api/go/beta/messages | Go | BetaMessage type definition |

Total scope: 42 files across all SDK reference docs contain BetaWebSearchToolResultBlock or BetaCodeExecutionToolResultBlock in assistant message definitions.

Patterns searched: BetaWebSearchToolResultBlock|BetaCodeExecutionToolResultBlock

Cross-reference: Server Tools documentation should link to these type definitions and explain the different flow.