refactor: updated tools doc with function naming: roll_die → roll_dice (#1986)

Co-authored-by: Marcelo Trylesinski <[email protected]>

Author: yamanahlawat

docs/tools.md

@@ -40,7 +40,7 @@ agent = Agent(
 
 
 @agent.tool_plain  # (3)!
-def roll_die() -> str:
+def roll_dice() -> str:
     """Roll a six-sided die and return the result."""
     return str(random.randint(1, 6))
 
@@ -87,7 +87,7 @@ print(dice_result.all_messages())
     ModelResponse(
         parts=[
             ToolCallPart(
-                tool_name='roll_die', args={}, tool_call_id='pyd_ai_tool_call_id'
+                tool_name='roll_dice', args={}, tool_call_id='pyd_ai_tool_call_id'
             )
         ],
         usage=Usage(requests=1, request_tokens=90, response_tokens=2, total_tokens=92),
@@ -97,7 +97,7 @@ print(dice_result.all_messages())
     ModelRequest(
         parts=[
             ToolReturnPart(
-                tool_name='roll_die',
+                tool_name='roll_dice',
                 content='4',
                 tool_call_id='pyd_ai_tool_call_id',
                 timestamp=datetime.datetime(...),
@@ -152,7 +152,7 @@ sequenceDiagram
     activate LLM
     Note over LLM: LLM decides to use<br>a tool
 
-    LLM ->> Agent: Call tool<br>roll_die()
+    LLM ->> Agent: Call tool<br>roll_dice()
     deactivate LLM
     activate Agent
     Note over Agent: Rolls a six-sided die
@@ -192,7 +192,7 @@ Use the player's name in the response.
 """
 
 
-def roll_die() -> str:
+def roll_dice() -> str:
     """Roll a six-sided die and return the result."""
     return str(random.randint(1, 6))
 
@@ -205,14 +205,14 @@ def get_player_name(ctx: RunContext[str]) -> str:
 agent_a = Agent(
     'google-gla:gemini-1.5-flash',
     deps_type=str,
-    tools=[roll_die, get_player_name],  # (1)!
+    tools=[roll_dice, get_player_name],  # (1)!
     system_prompt=system_prompt,
 )
 agent_b = Agent(
     'google-gla:gemini-1.5-flash',
     deps_type=str,
     tools=[  # (2)!
-        Tool(roll_die, takes_ctx=False),
+        Tool(roll_dice, takes_ctx=False),
         Tool(get_player_name, takes_ctx=True),
     ],
     system_prompt=system_prompt,

tests/test_examples.py

@@ -290,8 +290,8 @@ async def list_tools() -> list[None]:
     'I bet five is the winner': ToolCallPart(
         tool_name='roulette_wheel', args={'square': 5}, tool_call_id='pyd_ai_tool_call_id'
     ),
-    'My guess is 6': ToolCallPart(tool_name='roll_die', args={}, tool_call_id='pyd_ai_tool_call_id'),
-    'My guess is 4': ToolCallPart(tool_name='roll_die', args={}, tool_call_id='pyd_ai_tool_call_id'),
+    'My guess is 6': ToolCallPart(tool_name='roll_dice', args={}, tool_call_id='pyd_ai_tool_call_id'),
+    'My guess is 4': ToolCallPart(tool_name='roll_dice', args={}, tool_call_id='pyd_ai_tool_call_id'),
     'Send a message to John Doe asking for coffee next week': ToolCallPart(
         tool_name='get_user_by_name', args={'name': 'John'}
     ),
@@ -545,7 +545,7 @@ async def model_logic(  # noqa: C901
         return ModelResponse(
             parts=[ToolCallPart(tool_name='final_result', args={'response': win}, tool_call_id='pyd_ai_tool_call_id')],
         )
-    elif isinstance(m, ToolReturnPart) and m.tool_name == 'roll_die':
+    elif isinstance(m, ToolReturnPart) and m.tool_name == 'roll_dice':
         return ModelResponse(
             parts=[ToolCallPart(tool_name='get_player_name', args={}, tool_call_id='pyd_ai_tool_call_id')]
         )