chore: Improve Agent pydoc

haystack/components/agents/agent.py

@@ -81,23 +81,69 @@ class Agent:
     from haystack.components.agents import Agent
     from haystack.components.generators.chat import OpenAIChatGenerator
     from haystack.dataclasses import ChatMessage
-    from haystack.tools.tool import Tool
-
-    tools = [Tool(name="calculator", description="..."), Tool(name="search", description="...")]
+    from haystack.tools import Tool
+
+    # Tool functions - in practice, these would have real implementations
+    def search(query: str) -> str:
+        '''Search for information on the web.'''
+        # Placeholder: would call actual search API
+        return "In France, a 15% service charge is typically included, but leaving 5-10% extra is appreciated."
+
+    def calculator(operation: str, a: float, b: float) -> float:
+        '''Perform mathematical calculations.'''
+        if operation == "multiply":
+            return a * b
+        elif operation == "percentage":
+            return (a / 100) * b
+        return 0
+
+    # Define tools with JSON Schema
+    tools = [
+        Tool(
+            name="search",
+            description="Searches for information on the web",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "The search query"}
+                },
+                "required": ["query"]
+            },
+            function=search
+        ),
+        Tool(
+            name="calculator",
+            description="Performs mathematical calculations",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "operation": {"type": "string", "description": "Operation: multiply, percentage"},
+                    "a": {"type": "number", "description": "First number"},
+                    "b": {"type": "number", "description": "Second number"}
+                },
+                "required": ["operation", "a", "b"]
+            },
+            function=calculator
+        )
+    ]
 
+    # Create and run the agent
     agent = Agent(
         chat_generator=OpenAIChatGenerator(),
-        tools=tools,
-        exit_conditions=["search"],
+        tools=tools
     )
 
-    # Run the agent
     result = agent.run(
-        messages=[ChatMessage.from_user("Find information about Haystack")]
+        messages=[ChatMessage.from_user("Calculate the appropriate tip for an €85 meal in France")]
     )
 
-    assert "messages" in result  # Contains conversation history
+    # The agent will:
+    # 1. Search for tipping customs in France
+    # 2. Use calculator to compute tip based on findings
+    # 3. Return the final answer with context
+    print(result["messages"][-1].text)
     ```
+
     """
 
     def __init__(