Refactor documentation to improve clarity and structure. Updated import paths for MCPTool and enhanced examples for x402 payments and agent creation. Added detailed system prompts and improved agent capabilities with real-time web search and scraping tools. This enhances the usability and comprehensiveness of the guides for building AI agents.

Author: veithly

docs/core-concepts/agents-detailed.md

@@ -61,7 +61,7 @@ class SpoonMacroAnalysisAgent(SpoonReactMCP):
 
 **Stdio-based Transport:**
 ```python
-from spoon_ai.tools import MCPTool
+from spoon_ai.tools.mcp_tool import MCPTool
 
 tavily_tool = MCPTool(
     name="tavily-search",

docs/core-concepts/mcp-protocol.md

@@ -64,16 +64,29 @@ pip install spoon-ai
 
 ```python
 import asyncio
-from spoon_ai.mcp import MCPClient
+from spoon_ai.tools.mcp_tool import MCPTool
 
-async def main():
-    async with MCPClient.from_config({
+# Create an MCP tool that connects to an external MCP server
+mcp_tool = MCPTool(
+    name="filesystem",
+    description="Access filesystem via MCP",
+    mcp_config={
         "command": "npx",
         "args": ["-y", "@anthropic/mcp-server-filesystem", "/tmp"]
-    }) as client:
-        tools = await client.list_tools()
-        result = await client.call_tool("read_file", {"path": "/tmp/test.txt"})
-        print(result)
+    }
+)
+
+async def main():
+    # Load tool parameters from the MCP server
+    await mcp_tool.ensure_parameters_loaded()
+    
+    # List available tools
+    tools = await mcp_tool.list_mcp_tools()
+    print("Available tools:", [t.name for t in tools])
+    
+    # Call a tool
+    result = await mcp_tool.call_mcp_tool("read_file", path="/tmp/test.txt")
+    print(result)
 
 asyncio.run(main())
 ```

docs/core-concepts/tools.md

@@ -69,9 +69,9 @@ from spoon_ai.tools import ToolManager
 
 # Define a tool with JSON-schema parameters
 class GreetTool(BaseTool):
-    name = "greet"
-    description = "Greet someone by name"
-    parameters = {
+    name: str = "greet"
+    description: str = "Greet someone by name"
+    parameters: dict = {
         "type": "object",
         "properties": {"name": {"type": "string"}},
         "required": ["name"]
@@ -102,9 +102,9 @@ All tools inherit from `BaseTool` with three required attributes and one method:
 from spoon_ai.tools.base import BaseTool
 
 class MyTool(BaseTool):
-    name = "my_tool"                    # Unique identifier
-    description = "What this tool does" # LLM reads this to decide when to use it
-    parameters = {                      # JSON-schema for input validation
+    name: str = "my_tool"                    # Unique identifier
+    description: str = "What this tool does" # LLM reads this to decide when to use it
+    parameters: dict = {                      # JSON-schema for input validation
         "type": "object",
         "properties": {
             "arg1": {"type": "string", "description": "First argument"},

docs/core-concepts/x402-payments.md

@@ -56,19 +56,35 @@ sequenceDiagram
 ## Quick Start
 
 ```bash
-pip install spoon-ai
+pip install spoon-ai x402
 export PRIVATE_KEY="your-wallet-private-key"
+export X402_RECEIVER_ADDRESS="0xYourReceiverWallet"
 ```
 
 ```python
-from spoon_ai.agents import SpoonReactAI
-from spoon_ai.payments import x402_paywalled_request
-
-# Agent auto-detects 402 and signs payments
-agent = SpoonReactAI(tools=[x402_paywalled_request])
-result = await agent.run("Fetch https://api.example.com/premium")
+import asyncio
+from spoon_ai.payments import X402PaymentService, X402PaymentRequest
+
+# Initialize the payment service
+service = X402PaymentService()
+
+async def main():
+    # Create a payment request
+    request = X402PaymentRequest(
+        amount_usdc="0.01",  # Amount in USDC
+        resource="/premium-data",
+        description="Access to premium data"
+    )
+    
+    # Sign and create payment receipt
+    receipt = await service.sign_and_pay(request)
+    print(f"Payment signed: {receipt}")
+
+asyncio.run(main())
 ```
 
+> **Note:** For agent-based x402 payments, the agent handles 402 responses automatically when configured with payment capabilities. See the full examples in the x402 package for complete integration patterns.
+
 ---
 
 ## Components