Drastically Improve Agent Tool Usage Clarity for All Developers

This update significantly enhances the "Tool Behavior Definitions" documentation, directly addressing the common challenges and wasted time developers previously experienced. Without clear examples and explicit guidance on import paths and usage patterns, implementing advanced agent tool behaviors was often a source of confusion and trial-and-error.

**Key improvements in this update include:**

-   **Explicitly defining crucial import paths** for `StopAtTools` and `ToolsToFinalOutputFunction`, removing guesswork.
-   **Providing comprehensive and corrected code examples** for all `tool_choice` and `tool_use_behavior` configurations, including `"stop_on_first_tool"`, `StopAtTools`, and `ToolsToFinalOutputFunction`. These examples are now streamlined and use consistent, easy-to-understand tools like `get_weather`.
-   **Ensuring proper Markdown formatting** for code blocks and notes to enhance readability and accuracy.

My personal experience, including significant time spent troubleshooting these very behaviors due to lack of clear examples, fueled this contribution. This update aims to drastically reduce ambiguity and improve the developer experience by offering ready-to-use and well-explained code snippets, saving countless hours for others.

Author: muhammadhamidrazasidtechno

docs/agents.md

@@ -147,16 +147,15 @@ Supplying a list of tools doesn't always mean the LLM will use a tool. You can f
 from agents import Agent, Runner, function_tool, ModelSettings
 
 @function_tool
-def get_stock_price(ticker: str) -> str:
-    """Fetches the stock price for a given ticker symbol."""
-    prices = {"AAPL": "$150.00", "GOOGL": "$2750.00"}
-    return prices.get(ticker, "Stock not found")
+def get_weather(city: str) -> str:
+    """Returns weather info for the specified city."""
+    return f"The weather in {city} is sunny"
 
 agent = Agent(
-    name="Stock Price Agent",
-    instructions="Retrieve the stock price if relevant, otherwise respond directly.",
-    tools=[get_stock_price],
-    model_settings=ModelSettings(tool_choice="get_stock_price") 
+    name="Weather Agent",
+    instructions="Retrieve weather details.",
+    tools=[get_weather],
+    model_settings=ModelSettings(tool_choice="get_weather") 
 )
 
 ```
@@ -171,16 +170,14 @@ The `tool_use_behavior` parameter in the `Agent` configuration controls how tool
 from agents import Agent, Runner, function_tool, ModelSettings
 
 @function_tool
-def get_stock_price(ticker: str) -> str:
-    """Fetches the stock price for a given ticker symbol."""
-    prices = {"AAPL": "$150.00", "GOOGL": "$2750.00"}
-    return prices.get(ticker, "Stock not found")
+def get_weather(city: str) -> str:
+    """Returns weather info for the specified city."""
+    return f"The weather in {city} is sunny"
 
-# Create the agent
 agent = Agent(
-    name="Stock Price Agent",
-    instructions="Retrieve the stock price.",
-    tools=[get_stock_price],
+    name="Weather Agent",
+    instructions="Retrieve weather details.",
+    tools=[get_weather],
     tool_use_behavior="stop_on_first_tool"
 )
 ```
@@ -191,16 +188,20 @@ from agents import Agent, Runner, function_tool
 from agents.agent import StopAtTools
 
 @function_tool
-def get_stock_price(ticker: str) -> str:
-    """Fetches the stock price for a given ticker symbol."""
-    prices = {"AAPL": "$150.00", "GOOGL": "$2750.00"}
-    return prices.get(ticker, "Stock not found")
+def get_weather(city: str) -> str:
+    """Returns weather info for the specified city."""
+    return f"The weather in {city} is sunny"
+
+@function_tool
+def sum_numbers(a: int, b: int) -> int:
+    """Adds two numbers."""
+    return a + b
 
 agent = Agent(
     name="Stop At Stock Agent",
-    instructions="Get stock price and stop.",
-    tools=[get_stock_price],
-    tool_use_behavior=StopAtTools(stop_at_tool_names=["get_stock_price"])
+    instructions="Get weather or sum numbers.",
+    tools=[get_weather, sum_numbers],
+    tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"])
 )
 ```
 - `ToolsToFinalOutputFunction`: A custom function that processes tool results and decides whether to stop or continue with the LLM.
@@ -212,37 +213,36 @@ from agents.agent import ToolsToFinalOutputResult
 from typing import List, Any
 
 @function_tool
-def get_product_price(product_id: str) -> str:
-    """Fetches the price for a given product ID."""
-    prices = {"P101": "$25.00", "P102": "$49.99"}
-    return prices.get(product_id, "Product not found")
+def get_weather(city: str) -> str:
+    """Returns weather info for the specified city."""
+    return f"The weather in {city} is sunny"
 
 def custom_tool_handler(
     context: RunContextWrapper[Any],
     tool_results: List[FunctionToolResult]
 ) -> ToolsToFinalOutputResult:
     """Processes tool results to decide final output."""
     for result in tool_results:
-        if result.output and "$25.00" in result.output:
+        if result.output and "sunny" in result.output:
             return ToolsToFinalOutputResult(
                 is_final_output=True,
-                final_output=f"Final result: {result.output}"
+                final_output=f"Final weather: {result.output}"
             )
     return ToolsToFinalOutputResult(
         is_final_output=False,
         final_output=None
     )
 
-# Create the agent
 agent = Agent(
-    name="Product Price Agent",
-    instructions="Retrieve product prices and format them.",
-    tools=[get_product_price],
+    name="Weather Agent",
+    instructions="Retrieve weather details.",
+    tools=[get_weather],
     tool_use_behavior=custom_tool_handler
 )
 
 ```
- !!! note
+
+!!! note
 
     To prevent infinite loops, the framework automatically resets `tool_choice` to "auto" after a tool call. This behavior is configurable via [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice]. The infinite loop is because tool results are sent to the LLM, which then generates another tool call because of `tool_choice`, ad infinitum.