chuk-tool-processor 0.10__tar.gz → 0.11__tar.gz

{chuk_tool_processor-0.10 → chuk_tool_processor-0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chuk-tool-processor
-Version: 0.10
+Version: 0.11
 Summary: Async-native framework for registering, discovering, and executing tools referenced in LLM responses
 Author-email: CHUK Team <chrishayuk@somejunkmailbox.com>
 Maintainer-email: CHUK Team <chrishayuk@somejunkmailbox.com>
@@ -96,15 +96,15 @@ Works with OpenAI, Anthropic, local models (Ollama/MLX/vLLM), and any framework
 
 ```python
 import asyncio
-from chuk_tool_processor import ToolProcessor, register_tool, initialize
+from chuk_tool_processor import ToolProcessor, tool
 
-@register_tool(name="weather")
+@tool(name="weather")  # Clean decorator syntax
 class WeatherTool:
     async def execute(self, city: str) -> dict:
         return {"temp": 72, "condition": "sunny", "city": city}
 
 async def main():
-    await initialize()
+    # No need for initialize() - auto-initializes on first use!
     async with ToolProcessor(enable_caching=True, enable_retries=True) as p:
         # Works with OpenAI, Anthropic, or JSON formats
         result = await p.process('<tool name="weather" args=\'{"city": "SF"}\'/>')
@@ -374,10 +374,10 @@ Copy-paste this into a file and run it:
 
 ```python
 import asyncio
-from chuk_tool_processor import ToolProcessor, register_tool, initialize
+from chuk_tool_processor import ToolProcessor, tool
 
-# Step 1: Define a tool
-@register_tool(name="calculator")
+# Step 1: Define a tool with the clean @tool decorator
+@tool(name="calculator")
 class Calculator:
     async def execute(self, operation: str, a: float, b: float) -> dict:
         ops = {"add": a + b, "multiply": a * b, "subtract": a - b}
@@ -387,7 +387,7 @@ class Calculator:
 
 # Step 2: Process LLM output
 async def main():
-    await initialize()
+    # No initialize() needed - it auto-initializes!
 
     # Use context manager for automatic cleanup
     async with ToolProcessor() as processor:
@@ -412,10 +412,87 @@ asyncio.run(main())
 - ✅ Automatic timeouts, retries, and caching
 - ✅ Clean resource management (context manager)
 - ✅ Full type checking support
+- ✅ Auto-initialization (no boilerplate!)
 
 > **Why not just use OpenAI tool calls?**
 > OpenAI's function calling is great for parsing, but you still need: parsing multiple formats (Anthropic XML, etc.), timeouts, retries, rate limits, caching, subprocess isolation, connecting to external MCP servers, and **per-tool** policy control with cross-provider parsing and MCP fan-out. CHUK Tool Processor **is** that missing middle layer.
 
+### Enhanced Developer Experience
+
+CHUK Tool Processor provides intuitive APIs and helpful error messages:
+
+**1. Clean Decorator Syntax**
+```python
+from chuk_tool_processor import tool
+
+@tool(name="calculator")  # Short and clean!
+class Calculator:
+    async def execute(self, a: int, b: int) -> int:
+        return a + b
+```
+
+**2. Auto-Initialization (No Boilerplate)**
+```python
+from chuk_tool_processor import ToolProcessor
+
+# No initialize() needed - it auto-initializes!
+async with ToolProcessor() as p:
+    results = await p.process(llm_output)
+```
+
+**3. Type-Safe Tool Discovery**
+```python
+from chuk_tool_processor import get_default_registry, ToolInfo
+
+registry = await get_default_registry()
+
+# List all registered tools with clear, typed results
+tools = await registry.list_tools()
+for tool in tools:  # Each tool is a ToolInfo object
+    print(f"{tool.namespace}:{tool.name}")  # Clear attribute access!
+    # No more confusing tuple unpacking: (namespace, name) vs (name, namespace)?
+```
+
+**4. Helpful Error Messages**
+```python
+# Typo in tool name? Get helpful suggestions!
+try:
+    await registry.get_tool_strict("calcuator", namespace="default")
+except Exception as e:
+    print(e)
+    # Output:
+    # Tool 'calcuator' not found in namespace 'default'
+    #
+    # Did you mean: calculator?
+    #
+    # Available namespaces: default, math, mcp
+    #
+    # Tip: Use `await registry.list_tools()` to see all registered tools
+```
+
+**5. Clean MCP Configuration**
+```python
+from chuk_tool_processor.mcp import setup_mcp_stdio, MCPConfig, MCPServerConfig
+
+# Clean Pydantic config object instead of 14+ parameters!
+processor, manager = await setup_mcp_stdio(
+    config=MCPConfig(
+        servers=[MCPServerConfig(name="echo", command="uvx", args=["mcp-echo"])],
+        namespace="tools",
+        enable_caching=True,
+        cache_ttl=600,
+    )
+)
+```
+
+**Key improvements:**
+- ✅ **`@tool` decorator**: Shorter, cleaner than `@register_tool`
+- ✅ **Auto-initialization**: No need for explicit `initialize()` calls
+- ✅ **Type-safe tool listing**: `ToolInfo` objects instead of confusing tuples
+- ✅ **Helpful errors**: Fuzzy matching suggestions when tools aren't found
+- ✅ **MCPConfig**: Clean Pydantic model instead of 14+ parameters
+- ✅ **Better discoverability**: Clear guidance on how to explore available tools
+
 ## Quick Decision Tree (Commit This to Memory)
 
 ```
@@ -425,8 +502,8 @@ asyncio.run(main())
 │   ⚠️ No → IsolatedStrategy (sandboxed)     │
 │                                          │
 │ Where do your tools live?                │
-│   📦 Local → @register_tool               │
-│   🌐 Remote → setup_mcp_http_streamable    │
+│   📦 Local → @tool decorator              │
+│   🌐 Remote → setup_mcp_* with MCPConfig  │
 ╰──────────────────────────────────────────╯
 ```
 
@@ -436,22 +513,25 @@ asyncio.run(main())
 
 Understanding the lifecycle helps you use CHUK Tool Processor correctly:
 
-1. **`await initialize()`** — loads the global registry; call **once per process** at application startup
+1. **Auto-initialization** — Registry auto-initializes on first access (or call `await initialize()` explicitly)
 2. Create a **`ToolProcessor(...)`** (or use the one returned by `setup_mcp_*`)
 3. Use **`async with ToolProcessor() as p:`** to ensure cleanup
 4. **`setup_mcp_*`** returns `(processor, manager)` — reuse that `processor`
 5. If you need a custom registry, pass it explicitly to the strategy
 6. You rarely need `get_default_registry()` unless you're composing advanced setups
 
-**⚠️ Important:** `initialize()` must run **once per process**, not once per request or processor instance. Running it multiple times will duplicate tools in the registry.
+**New in this version:** The registry auto-initializes when you create a `ToolProcessor` or access `get_default_registry()`, so you can skip the explicit `initialize()` call in most cases!
 
 ```python
-# Standard pattern
-await initialize()  # Step 1: Register tools
+# New simplified pattern (auto-initialization)
+async with ToolProcessor() as p:  # Auto-initializes on first use!
+    results = await p.process(llm_output)
+    # Processor automatically cleaned up on exit
 
-async with ToolProcessor() as p:  # Step 2-3: Create + auto cleanup
+# Traditional explicit pattern (still works)
+await initialize()  # Explicit initialization
+async with ToolProcessor() as p:
     results = await p.process(llm_output)
-    # Step 4: Processor automatically cleaned up on exit
 ```
 
 ## Production Features by Example
@@ -618,7 +698,41 @@ asyncio.run(main())
 
 See `examples/04_mcp_integration/notion_oauth.py` for complete OAuth flow.
 
-**Pattern 3: Local SQLite database via STDIO**
+**Pattern 3: Local SQLite database via STDIO (New Clean API)**
+```python
+import asyncio
+from chuk_tool_processor.mcp import setup_mcp_stdio, MCPConfig, MCPServerConfig
+
+async def main():
+    # NEW: Clean Pydantic config approach (recommended!)
+    processor, manager = await setup_mcp_stdio(
+        config=MCPConfig(
+            servers=[
+                MCPServerConfig(
+                    name="sqlite",
+                    command="uvx",
+                    args=["mcp-server-sqlite", "--db-path", "./app.db"],
+                )
+            ],
+            namespace="db",
+            initialization_timeout=120.0,  # First run downloads the package
+            enable_caching=True,
+            cache_ttl=600,
+        )
+    )
+
+    # Query your local database via MCP
+    results = await processor.process(
+        '<tool name="db.query" args=\'{"sql": "SELECT * FROM users LIMIT 10"}\'/>'
+    )
+    print(results[0].result)
+
+asyncio.run(main())
+```
+
+<details>
+<summary><strong>Legacy approach (still works)</strong></summary>
+
 ```python
 import asyncio
 import json
@@ -643,7 +757,7 @@ async def main():
         config_file="mcp_config.json",
         servers=["sqlite"],
         namespace="db",
-        initialization_timeout=120.0  # First run downloads the package
+        initialization_timeout=120.0
     )
 
     # Query your local database via MCP
@@ -654,6 +768,7 @@ async def main():
 
 asyncio.run(main())
 ```
+</details>
 
 See `examples/04_mcp_integration/stdio_sqlite.py` for complete working example.
 
@@ -937,7 +1052,11 @@ register_fn_tool(get_current_time, namespace="utilities")
 For production tools, use Pydantic validation:
 
 ```python
-@register_tool(name="weather")
+from chuk_tool_processor import tool
+from chuk_tool_processor.models import ValidatedTool
+from pydantic import BaseModel, Field
+
+@tool(name="weather")  # Clean @tool decorator
 class WeatherTool(ValidatedTool):
     class Arguments(BaseModel):
         location: str = Field(..., description="City name")
@@ -951,14 +1070,28 @@ class WeatherTool(ValidatedTool):
         return self.Result(temperature=22.5, conditions="Sunny")
 ```
 
+<details>
+<summary><strong>Alternative: Using @register_tool (still works)</strong></summary>
+
+```python
+from chuk_tool_processor import register_tool
+
+@register_tool(name="weather")  # Longer form, but identical functionality
+class WeatherTool(ValidatedTool):
+    # ... same as above
+```
+</details>
+
 #### StreamingTool (Real-time Results)
 
 For long-running operations that produce incremental results:
 
 ```python
+from chuk_tool_processor import tool
 from chuk_tool_processor.models import StreamingTool
+from pydantic import BaseModel
 
-@register_tool(name="file_processor")
+@tool(name="file_processor")  # Clean @tool decorator
 class FileProcessor(StreamingTool):
     class Arguments(BaseModel):
         file_path: str

{chuk_tool_processor-0.10 → chuk_tool_processor-0.11}/README.md

@@ -68,15 +68,15 @@ Works with OpenAI, Anthropic, local models (Ollama/MLX/vLLM), and any framework
 
 ```python
 import asyncio
-from chuk_tool_processor import ToolProcessor, register_tool, initialize
+from chuk_tool_processor import ToolProcessor, tool
 
-@register_tool(name="weather")
+@tool(name="weather")  # Clean decorator syntax
 class WeatherTool:
     async def execute(self, city: str) -> dict:
         return {"temp": 72, "condition": "sunny", "city": city}
 
 async def main():
-    await initialize()
+    # No need for initialize() - auto-initializes on first use!
     async with ToolProcessor(enable_caching=True, enable_retries=True) as p:
         # Works with OpenAI, Anthropic, or JSON formats
         result = await p.process('<tool name="weather" args=\'{"city": "SF"}\'/>')
@@ -346,10 +346,10 @@ Copy-paste this into a file and run it:
 
 ```python
 import asyncio
-from chuk_tool_processor import ToolProcessor, register_tool, initialize
+from chuk_tool_processor import ToolProcessor, tool
 
-# Step 1: Define a tool
-@register_tool(name="calculator")
+# Step 1: Define a tool with the clean @tool decorator
+@tool(name="calculator")
 class Calculator:
     async def execute(self, operation: str, a: float, b: float) -> dict:
         ops = {"add": a + b, "multiply": a * b, "subtract": a - b}
@@ -359,7 +359,7 @@ class Calculator:
 
 # Step 2: Process LLM output
 async def main():
-    await initialize()
+    # No initialize() needed - it auto-initializes!
 
     # Use context manager for automatic cleanup
     async with ToolProcessor() as processor:
@@ -384,10 +384,87 @@ asyncio.run(main())
 - ✅ Automatic timeouts, retries, and caching
 - ✅ Clean resource management (context manager)
 - ✅ Full type checking support
+- ✅ Auto-initialization (no boilerplate!)
 
 > **Why not just use OpenAI tool calls?**
 > OpenAI's function calling is great for parsing, but you still need: parsing multiple formats (Anthropic XML, etc.), timeouts, retries, rate limits, caching, subprocess isolation, connecting to external MCP servers, and **per-tool** policy control with cross-provider parsing and MCP fan-out. CHUK Tool Processor **is** that missing middle layer.
 
+### Enhanced Developer Experience
+
+CHUK Tool Processor provides intuitive APIs and helpful error messages:
+
+**1. Clean Decorator Syntax**
+```python
+from chuk_tool_processor import tool
+
+@tool(name="calculator")  # Short and clean!
+class Calculator:
+    async def execute(self, a: int, b: int) -> int:
+        return a + b
+```
+
+**2. Auto-Initialization (No Boilerplate)**
+```python
+from chuk_tool_processor import ToolProcessor
+
+# No initialize() needed - it auto-initializes!
+async with ToolProcessor() as p:
+    results = await p.process(llm_output)
+```
+
+**3. Type-Safe Tool Discovery**
+```python
+from chuk_tool_processor import get_default_registry, ToolInfo
+
+registry = await get_default_registry()
+
+# List all registered tools with clear, typed results
+tools = await registry.list_tools()
+for tool in tools:  # Each tool is a ToolInfo object
+    print(f"{tool.namespace}:{tool.name}")  # Clear attribute access!
+    # No more confusing tuple unpacking: (namespace, name) vs (name, namespace)?
+```
+
+**4. Helpful Error Messages**
+```python
+# Typo in tool name? Get helpful suggestions!
+try:
+    await registry.get_tool_strict("calcuator", namespace="default")
+except Exception as e:
+    print(e)
+    # Output:
+    # Tool 'calcuator' not found in namespace 'default'
+    #
+    # Did you mean: calculator?
+    #
+    # Available namespaces: default, math, mcp
+    #
+    # Tip: Use `await registry.list_tools()` to see all registered tools
+```
+
+**5. Clean MCP Configuration**
+```python
+from chuk_tool_processor.mcp import setup_mcp_stdio, MCPConfig, MCPServerConfig
+
+# Clean Pydantic config object instead of 14+ parameters!
+processor, manager = await setup_mcp_stdio(
+    config=MCPConfig(
+        servers=[MCPServerConfig(name="echo", command="uvx", args=["mcp-echo"])],
+        namespace="tools",
+        enable_caching=True,
+        cache_ttl=600,
+    )
+)
+```
+
+**Key improvements:**
+- ✅ **`@tool` decorator**: Shorter, cleaner than `@register_tool`
+- ✅ **Auto-initialization**: No need for explicit `initialize()` calls
+- ✅ **Type-safe tool listing**: `ToolInfo` objects instead of confusing tuples
+- ✅ **Helpful errors**: Fuzzy matching suggestions when tools aren't found
+- ✅ **MCPConfig**: Clean Pydantic model instead of 14+ parameters
+- ✅ **Better discoverability**: Clear guidance on how to explore available tools
+
 ## Quick Decision Tree (Commit This to Memory)
 
 ```
@@ -397,8 +474,8 @@ asyncio.run(main())
 │   ⚠️ No → IsolatedStrategy (sandboxed)     │
 │                                          │
 │ Where do your tools live?                │
-│   📦 Local → @register_tool               │
-│   🌐 Remote → setup_mcp_http_streamable    │
+│   📦 Local → @tool decorator              │
+│   🌐 Remote → setup_mcp_* with MCPConfig  │
 ╰──────────────────────────────────────────╯
 ```
 
@@ -408,22 +485,25 @@ asyncio.run(main())
 
 Understanding the lifecycle helps you use CHUK Tool Processor correctly:
 
-1. **`await initialize()`** — loads the global registry; call **once per process** at application startup
+1. **Auto-initialization** — Registry auto-initializes on first access (or call `await initialize()` explicitly)
 2. Create a **`ToolProcessor(...)`** (or use the one returned by `setup_mcp_*`)
 3. Use **`async with ToolProcessor() as p:`** to ensure cleanup
 4. **`setup_mcp_*`** returns `(processor, manager)` — reuse that `processor`
 5. If you need a custom registry, pass it explicitly to the strategy
 6. You rarely need `get_default_registry()` unless you're composing advanced setups
 
-**⚠️ Important:** `initialize()` must run **once per process**, not once per request or processor instance. Running it multiple times will duplicate tools in the registry.
+**New in this version:** The registry auto-initializes when you create a `ToolProcessor` or access `get_default_registry()`, so you can skip the explicit `initialize()` call in most cases!
 
 ```python
-# Standard pattern
-await initialize()  # Step 1: Register tools
+# New simplified pattern (auto-initialization)
+async with ToolProcessor() as p:  # Auto-initializes on first use!
+    results = await p.process(llm_output)
+    # Processor automatically cleaned up on exit
 
-async with ToolProcessor() as p:  # Step 2-3: Create + auto cleanup
+# Traditional explicit pattern (still works)
+await initialize()  # Explicit initialization
+async with ToolProcessor() as p:
     results = await p.process(llm_output)
-    # Step 4: Processor automatically cleaned up on exit
 ```
 
 ## Production Features by Example
@@ -590,7 +670,41 @@ asyncio.run(main())
 
 See `examples/04_mcp_integration/notion_oauth.py` for complete OAuth flow.
 
-**Pattern 3: Local SQLite database via STDIO**
+**Pattern 3: Local SQLite database via STDIO (New Clean API)**
+```python
+import asyncio
+from chuk_tool_processor.mcp import setup_mcp_stdio, MCPConfig, MCPServerConfig
+
+async def main():
+    # NEW: Clean Pydantic config approach (recommended!)
+    processor, manager = await setup_mcp_stdio(
+        config=MCPConfig(
+            servers=[
+                MCPServerConfig(
+                    name="sqlite",
+                    command="uvx",
+                    args=["mcp-server-sqlite", "--db-path", "./app.db"],
+                )
+            ],
+            namespace="db",
+            initialization_timeout=120.0,  # First run downloads the package
+            enable_caching=True,
+            cache_ttl=600,
+        )
+    )
+
+    # Query your local database via MCP
+    results = await processor.process(
+        '<tool name="db.query" args=\'{"sql": "SELECT * FROM users LIMIT 10"}\'/>'
+    )
+    print(results[0].result)
+
+asyncio.run(main())
+```
+
+<details>
+<summary><strong>Legacy approach (still works)</strong></summary>
+
 ```python
 import asyncio
 import json
@@ -615,7 +729,7 @@ async def main():
         config_file="mcp_config.json",
         servers=["sqlite"],
         namespace="db",
-        initialization_timeout=120.0  # First run downloads the package
+        initialization_timeout=120.0
     )
 
     # Query your local database via MCP
@@ -626,6 +740,7 @@ async def main():
 
 asyncio.run(main())
 ```
+</details>
 
 See `examples/04_mcp_integration/stdio_sqlite.py` for complete working example.
 
@@ -909,7 +1024,11 @@ register_fn_tool(get_current_time, namespace="utilities")
 For production tools, use Pydantic validation:
 
 ```python
-@register_tool(name="weather")
+from chuk_tool_processor import tool
+from chuk_tool_processor.models import ValidatedTool
+from pydantic import BaseModel, Field
+
+@tool(name="weather")  # Clean @tool decorator
 class WeatherTool(ValidatedTool):
     class Arguments(BaseModel):
         location: str = Field(..., description="City name")
@@ -923,14 +1042,28 @@ class WeatherTool(ValidatedTool):
         return self.Result(temperature=22.5, conditions="Sunny")
 ```
 
+<details>
+<summary><strong>Alternative: Using @register_tool (still works)</strong></summary>
+
+```python
+from chuk_tool_processor import register_tool
+
+@register_tool(name="weather")  # Longer form, but identical functionality
+class WeatherTool(ValidatedTool):
+    # ... same as above
+```
+</details>
+
 #### StreamingTool (Real-time Results)
 
 For long-running operations that produce incremental results:
 
 ```python
+from chuk_tool_processor import tool
 from chuk_tool_processor.models import StreamingTool
+from pydantic import BaseModel
 
-@register_tool(name="file_processor")
+@tool(name="file_processor")  # Clean @tool decorator
 class FileProcessor(StreamingTool):
     class Arguments(BaseModel):
         file_path: str

{chuk_tool_processor-0.10 → chuk_tool_processor-0.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chuk-tool-processor"
-version = "0.10"
+version = "0.11"
 description = "Async-native framework for registering, discovering, and executing tools referenced in LLM responses"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -146,6 +146,8 @@ disallow_incomplete_defs = true  # NEW: Require either all or no params typed
 module = [
     "chuk_mcp.*",
     "httpx_sse.*",
+    "opentelemetry.*",
+    "prometheus_client.*",
 ]
 ignore_missing_imports = true
 

{chuk_tool_processor-0.10 → chuk_tool_processor-0.11}/src/chuk_tool_processor/__init__.py

@@ -47,8 +47,9 @@ from chuk_tool_processor.mcp.stream_manager import StreamManager
 from chuk_tool_processor.models.tool_call import ToolCall
 from chuk_tool_processor.models.tool_result import ToolResult
 
-# Registry functions
+# Registry functions and types
 from chuk_tool_processor.registry import (
+    ToolInfo,
     ToolRegistryProvider,
     get_default_registry,
     initialize,
@@ -56,7 +57,7 @@ from chuk_tool_processor.registry import (
 from chuk_tool_processor.registry.auto_register import register_fn_tool
 
 # Decorators for registering tools
-from chuk_tool_processor.registry.decorators import register_tool
+from chuk_tool_processor.registry.decorators import register_tool, tool
 
 # Type checking imports (not available at runtime)
 if TYPE_CHECKING:
@@ -85,11 +86,13 @@ __all__ = [
     "ToolCall",
     "ToolResult",
     # Registry
+    "ToolInfo",
     "initialize",
     "get_default_registry",
     "ToolRegistryProvider",
     # Decorators
     "register_tool",
+    "tool",
     "register_fn_tool",
     # Execution strategies
     "InProcessStrategy",

{chuk_tool_processor-0.10 → chuk_tool_processor-0.11}/src/chuk_tool_processor/core/exceptions.py

@@ -1,6 +1,7 @@
 # chuk_tool_processor/exceptions.py
+from difflib import get_close_matches
 from enum import Enum
-from typing import Any
+from typing import Any, cast
 
 
 class ErrorCode(str, Enum):
@@ -73,13 +74,63 @@ class ToolProcessorError(Exception):
 class ToolNotFoundError(ToolProcessorError):
     """Raised when a requested tool is not found in the registry."""
 
-    def __init__(self, tool_name: str, available_tools: list[str] | None = None):
+    def __init__(
+        self,
+        tool_name: str,
+        namespace: str = "default",
+        available_tools: list[tuple[str, str]] | list[str] | None = None,
+        available_namespaces: list[str] | None = None,
+    ):
         self.tool_name = tool_name
-        details: dict[str, Any] = {"tool_name": tool_name}
+        self.namespace = namespace
+
+        # Build helpful error message
+        message_parts = [f"Tool '{tool_name}' not found in namespace '{namespace}'"]
+
+        # Find similar tool names using fuzzy matching
+        similar_tools: list[str] = []
+        if available_tools:
+            # Handle both tuple format (namespace, name) and string format
+            if isinstance(available_tools[0], tuple):
+                # Type narrowing: cast to the expected type
+                tuple_tools = cast(list[tuple[str, str]], available_tools)
+                all_tool_names = [name for _, name in tuple_tools]
+                # Also check for namespace:name format
+                full_names = [f"{ns}:{name}" for ns, name in tuple_tools]
+                similar_in_namespace = get_close_matches(tool_name, all_tool_names, n=3, cutoff=0.6)
+                similar_full = get_close_matches(f"{namespace}:{tool_name}", full_names, n=3, cutoff=0.6)
+                similar_tools = list(similar_in_namespace) + list(similar_full)
+            else:
+                # Type narrowing: cast to the expected type
+                str_tools = cast(list[str], available_tools)
+                similar_tools = list(get_close_matches(tool_name, str_tools, n=3, cutoff=0.6))
+
+        if similar_tools:
+            message_parts.append(f"\n\nDid you mean: {', '.join(similar_tools)}?")
+
+        # Add available namespaces
+        if available_namespaces:
+            message_parts.append(f"\n\nAvailable namespaces: {', '.join(available_namespaces)}")
+
+        # Add helpful tip
+        message_parts.append(
+            "\n\nTip: Use `await registry.list_tools()` to see all registered tools, "
+            "or `await registry.list_namespaces()` to see available namespaces."
+        )
+
+        message = "".join(message_parts)
+
+        # Store details
+        details: dict[str, Any] = {"tool_name": tool_name, "namespace": namespace}
         if available_tools:
             details["available_tools"] = available_tools
+        if available_namespaces:
+            details["available_namespaces"] = available_namespaces
+        if similar_tools:
+            details["suggestions"] = similar_tools
+
         super().__init__(
-            f"Tool '{tool_name}' not found in registry",
+            message,
             code=ErrorCode.TOOL_NOT_FOUND,
             details=details,
         )