From ac49ac3dd2d37c37c728af94b3e9d3d74663bb5b Mon Sep 17 00:00:00 2001
From: Sharifa <66180927+MuhammadSaqib786@users.noreply.github.com>
Date: Tue, 7 Oct 2025 17:06:20 +0200
Subject: [PATCH 1/2] Update context.md

---
 docs/context.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/context.md b/docs/context.md
index 6e54565e0..4d2b96a8c 100644
--- a/docs/context.md
+++ b/docs/context.md
@@ -68,6 +68,44 @@ if __name__ == "__main__":
 4. The context is passed to the `run` function.
 5. The agent correctly calls the tool and gets the age.
 
+---
+
+### Advanced: `ToolContext`
+
+In some cases, you might want to access extra metadata about the tool being executed — such as its name, call ID, or raw argument string.  
+For this, you can use the [`ToolContext`][agents.tool_context.ToolContext] class, which extends `RunContextWrapper`.
+
+```python
+from dataclasses import dataclass
+from agents import function_tool
+from agents.tool_context import ToolContext
+
+@dataclass
+class UserInfo:
+    name: str
+    uid: int
+
+@function_tool
+async def fetch_user_age(ctx: ToolContext[UserInfo]) -> str:
+    """Fetch the age of the user, with access to tool metadata."""
+    print(ctx.tool_name)        # e.g. "fetch_user_age"
+    print(ctx.tool_call_id)     # unique ID for this invocation
+    print(ctx.tool_arguments)   # raw arguments as string
+    return f"The user {ctx.context.name} is 47 years old."
+```
+
+`ToolContext` provides the same `.context` property as `RunContextWrapper`,  
+plus additional fields specific to the current tool call:
+
+- `tool_name` – the name of the tool being invoked  
+- `tool_call_id` – a unique identifier for this tool call  
+- `tool_arguments` – the raw argument string passed to the tool  
+
+Use `ToolContext` when you need tool-level metadata during execution.  
+For general context sharing between agents and tools, `RunContextWrapper` remains sufficient.
+
+---
+
 ## Agent/LLM context
 
 When an LLM is called, the **only** data it can see is from the conversation history. This means that if you want to make some new data available to the LLM, you must do it in a way that makes it available in that history. There are a few ways to do this:

From 71afa616ed069a8f261334f43f76f53520d5bf18 Mon Sep 17 00:00:00 2001
From: Sharifa <66180927+MuhammadSaqib786@users.noreply.github.com>
Date: Sat, 11 Oct 2025 12:17:30 +0200
Subject: [PATCH 2/2] docs: update ToolContext example with WeatherContext per
 reviewer feedback

---
 docs/context.md | 31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)

diff --git a/docs/context.md b/docs/context.md
index 4d2b96a8c..c8e393ca0 100644
--- a/docs/context.md
+++ b/docs/context.md
@@ -76,22 +76,29 @@ In some cases, you might want to access extra metadata about the tool being exec
 For this, you can use the [`ToolContext`][agents.tool_context.ToolContext] class, which extends `RunContextWrapper`.
 
 ```python
-from dataclasses import dataclass
-from agents import function_tool
+from typing import Annotated
+from pydantic import BaseModel, Field
+from agents import Agent, Runner, function_tool
 from agents.tool_context import ToolContext
 
-@dataclass
-class UserInfo:
-    name: str
-    uid: int
+class WeatherContext(BaseModel):
+    user_id: str
+
+class Weather(BaseModel):
+    city: str = Field(description="The city name")
+    temperature_range: str = Field(description="The temperature range in Celsius")
+    conditions: str = Field(description="The weather conditions")
 
 @function_tool
-async def fetch_user_age(ctx: ToolContext[UserInfo]) -> str:
-    """Fetch the age of the user, with access to tool metadata."""
-    print(ctx.tool_name)        # e.g. "fetch_user_age"
-    print(ctx.tool_call_id)     # unique ID for this invocation
-    print(ctx.tool_arguments)   # raw arguments as string
-    return f"The user {ctx.context.name} is 47 years old."
+def get_weather(ctx: ToolContext[WeatherContext], city: Annotated[str, "The city to get the weather for"]) -> Weather:
+    print(f"[debug] Tool context: (name: {ctx.tool_name}, call_id: {ctx.tool_call_id}, args: {ctx.tool_arguments})")
+    return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")
+
+agent = Agent(
+    name="Weather Agent",
+    instructions="You are a helpful agent that can tell the weather of a given city.",
+    tools=[get_weather],
+)
 ```
 
 `ToolContext` provides the same `.context` property as `RunContextWrapper`,