The ContextWrapper class returns a ToolContext instead of a standard Python dataclass.

[khalidhussain-Projects]

Please read this first

• Have you read the docs?Agents SDK docs
• Have you searched for related issues? Others may have had similar requests

Question

The ContextWrapper class returns a ToolContext instead of a standard Python dataclass in the response output. Why its not returning the standard dataclass which is supposed to be as return type of Contextwrapper.

[AbdulSamad94]

ToolContext is not replacing or avoiding a standard Python dataclass. Instead:

1. ToolContext is a dataclass
2. ToolContext extends RunContextWrapper, It inherits from RunContextWrapper and adds additional tool-specific fields:
   • tool_name: The name of the tool being invoked
   • tool_call_id: The ID of the tool call
   • tool_arguments: The raw arguments string of the tool call

The system works as lik this:

• When the agent runtime executes a tool call, it creates a ToolContext instance by calling ToolContext.from_agent_context()
• This method takes the existing RunContextWrapper and adds tool-specific information to it
• Functions that accept a context parameter will receive the appropriate context type:
  • Regular context-aware functions → RunContextWrapper
  • Tool functions → ToolContext (includes all RunContextWrapper fields plus tool-specific fields)

Why This Design?

This inheritance approach provides:

• Enhanced functionality: Tool functions get access to both the user's context and tool-specific information
• Type safety: Different context types for different use cases
• Backward compatibility: Code expecting RunContextWrapper still works with ToolContext
• Consistency: Both classes are proper Python dataclasses with the @dataclass decorator

In short: ToolContext is a standard dataclass, it’s just a specialized one designed for tool execution contexts, rather than general run contexts.

[khalidhussain-Projects]

@AbdulSamad94 , yes i also know it but the point is it should be updated in the tool documentation when i hovers it is still showing the return type as ContextWrapper. Ideally it should be showing the extended/child class.