Debug Tools

Step-by-step guide to debugging and troubleshooting tools

Use doctor commands and targeted logs when tools fail to import or execute.

from praisonaiagents import Agent, tool

@tool
def flaky() -> str:
    """Simulate a tool for debugging."""
    return "ok"

agent = Agent(name="Tool Debugger", tools=[flaky])
agent.start("Call flaky and report errors if any.")

The user runs praisonai tools doctor, fixes dependencies, and retries the agent call.

How It Works

---

How to Use Tools Doctor

praisonai tools doctor now walks the full ToolResolver chain — local tools.py, wrapper ToolRegistry, praisonaiagents.tools, praisonai-tools, and entry-point plugins. As of PR #2642, a tool that resolves at run time is guaranteed to appear here, so the doctor no longer reports false “missing” results for registered or plugin tools.

1. Run Tools Doctor

   praisonai tools doctor
   
2. Check Specific Tool

   praisonai tools info shell_tool
   
3. Review Diagnostics

   Doctor output shows:

   • Tool availability
   • Missing dependencies
   • Configuration issues
   • Import errors
4. Fix Identified Issues

   Install missing packages or fix configuration based on doctor output.

How to Debug Tool Resolution

1. Resolve Tool Name

   praisonai tools resolve my_tool
   
2. Check Tool Sources

   praisonai tools show-sources
   
3. Discover Available Tools

   praisonai tools discover
   
4. Search for Tools

   praisonai tools search "search"
   

How to Debug Tools with Python

1. Test Tool Directly

   from my_tools import my_custom_tool
   
   # Test with sample input
   result = my_custom_tool("test query")
   print(f"Result: {result}")
   print(f"Type: {type(result)}")
   
2. Check Tool Signature

   import inspect
   
   sig = inspect.signature(my_custom_tool)
   print(f"Parameters: {sig.parameters}")
   print(f"Return annotation: {sig.return_annotation}")
   
3. Validate Docstring

   print(f"Docstring: {my_custom_tool.__doc__}")
   
4. Test with Agent

   from praisonaiagents import Agent
   import logging
   
   logging.basicConfig(level=logging.DEBUG)
   
   agent = Agent(
       name="tester",
       tools=[my_custom_tool]
   )
   
   result = agent.start("Test the tool")
   

How to Debug Tool Registry

1. Create Registry

   from praisonai.templates.tool_override import create_tool_registry_with_overrides
   
   registry = create_tool_registry_with_overrides(include_defaults=True)
   
2. List All Tools

   print("Available tools:")
   for name in sorted(registry.keys()):
       print(f"  - {name}")
   
3. Check Specific Tool

   tool_name = "shell_tool"
   if tool_name in registry:
       tool = registry[tool_name]
       print(f"Found: {tool}")
       print(f"Module: {tool.__module__}")
   else:
       print(f"Tool '{tool_name}' not found")
   

Common Tool Issues

Issue	Cause	Solution
Tool not found	Not in registry	Add to tools list or tools_sources
Import error	Missing dependency	Install required package
Type error	Wrong parameter types	Add proper type hints
No docstring	Missing documentation	Add docstring with Args section
Not serializable	Complex return type	Return dict/list/str instead

Debug CLI Commands

praisonai tools doctor              # Run diagnostics
praisonai tools list                # List all tools
praisonai tools info <name>         # Get tool details
praisonai tools resolve <name>      # Resolve tool location
praisonai tools search <query>      # Search for tools
praisonai tools show-sources        # Show tool sources
praisonai tools discover            # Discover from packages

Best Practices

Run tools doctor first

The doctor walks the whole resolver chain, so it distinguishes a missing dependency from a genuinely unregistered tool in one command.

Test the tool in isolation

Call the function directly and check its return type before blaming the agent — most failures are plain Python errors.

Inspect the signature and docstring

Use inspect.signature to confirm the tool exposes the parameters and return type the model expects.

---

Related

Create Custom Tools

Build tools with correct signatures

Assign Tools to Templates

Wire tools into recipes