Praison AI

Debug Tools

Step-by-step guide to debugging and troubleshooting tools

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

python
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.

Diagram

Debug Tools

📋 Failing Tool

🔍 tools doctor

✅ Resolved Call

How It Works

Diagram
ResolverCLIUserResolverCLIUserpraisonai tools doctorWalk the resolver chainAvailability + import errorsFixes to apply, then retry

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
    bash
    praisonai tools doctor
  2. Check Specific Tool
    bash
    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
    bash
    praisonai tools resolve my_tool
  2. Check Tool Sources
    bash
    praisonai tools show-sources
  3. Discover Available Tools
    bash
    praisonai tools discover
  4. Search for Tools
    bash
    praisonai tools search "search"

How to Debug Tools with Python

  1. Test Tool Directly
    python
    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
    python
    import inspect

sig = inspect.signature(my_custom_tool)
print(f"Parameters: {sig.parameters}")
print(f"Return annotation: {sig.return_annotation}")
  3. Validate Docstring
    python
    print(f"Docstring: {my_custom_tool.__doc__}")
  4. Test with Agent
    python
    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
    python
    from praisonai.templates.tool_override import create_tool_registry_with_overrides

registry = create_tool_registry_with_overrides(include_defaults=True)
  2. List All Tools
    python
    print("Available tools:")
for name in sorted(registry.keys()):
    print(f"  - {name}")
  3. Check Specific Tool
    python
    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

IssueCauseSolution
Tool not foundNot in registryAdd to tools list or tools_sources
Import errorMissing dependencyInstall required package
Type errorWrong parameter typesAdd proper type hints
No docstringMissing documentationAdd docstring with Args section
Not serializableComplex return typeReturn dict/list/str instead

Debug CLI Commands

bash
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