docs: clarify on_tool_start and on_tool_end hooks for local tools only (#2037)

Author: ihower

examples/basic/agent_lifecycle_example.py

@@ -28,6 +28,10 @@ async def on_handoff(self, context: RunContextWrapper, agent: Agent, source: Age
             f"### ({self.display_name}) {self.event_counter}: Agent {source.name} handed off to {agent.name}"
         )
 
+    # Note: The on_tool_start and on_tool_end hooks apply only to local tools.
+    # They do not include hosted tools that run on the OpenAI server side,
+    # such as WebSearchTool, FileSearchTool, CodeInterpreterTool, HostedMCPTool,
+    # or other built-in hosted tools.
     async def on_tool_start(self, context: RunContextWrapper, agent: Agent, tool: Tool) -> None:
         self.event_counter += 1
         print(

examples/basic/lifecycle_example.py

@@ -70,6 +70,10 @@ async def on_agent_end(self, context: RunContextWrapper, agent: Agent, output: A
             f"### {self.event_counter}: Agent {agent.name} ended with output {output}. Usage: {self._usage_to_str(context.usage)}"
         )
 
+    # Note: The on_tool_start and on_tool_end hooks apply only to local tools.
+    # They do not include hosted tools that run on the OpenAI server side,
+    # such as WebSearchTool, FileSearchTool, CodeInterpreterTool, HostedMCPTool,
+    # or other built-in hosted tools.
     async def on_tool_start(self, context: RunContextWrapper, agent: Agent, tool: Tool) -> None:
         self.event_counter += 1
         # While this type cast is not ideal,

src/agents/lifecycle.py

@@ -62,7 +62,7 @@ async def on_tool_start(
         agent: TAgent,
         tool: Tool,
     ) -> None:
-        """Called concurrently with tool invocation."""
+        """Called immediately before a local tool is invoked."""
         pass
 
     async def on_tool_end(
@@ -72,7 +72,7 @@ async def on_tool_end(
         tool: Tool,
         result: str,
     ) -> None:
-        """Called after a tool is invoked."""
+        """Called immediately after a local tool is invoked."""
         pass
 
 
@@ -113,7 +113,7 @@ async def on_tool_start(
         agent: TAgent,
         tool: Tool,
     ) -> None:
-        """Called concurrently with tool invocation."""
+        """Called immediately before a local tool is invoked."""
         pass
 
     async def on_tool_end(
@@ -123,7 +123,7 @@ async def on_tool_end(
         tool: Tool,
         result: str,
     ) -> None:
-        """Called after a tool is invoked."""
+        """Called immediately after a local tool is invoked."""
         pass
 
     async def on_llm_start(