Skip to main content
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

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

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

The doctor walks the whole resolver chain, so it distinguishes a missing dependency from a genuinely unregistered tool in one command.
Call the function directly and check its return type before blaming the agent — most failures are plain Python errors.
Use inspect.signature to confirm the tool exposes the parameters and return type the model expects.

Create Custom Tools

Build tools with correct signatures

Assign Tools to Templates

Wire tools into recipes