Skip to main content
Tools Doctor diagnoses tool availability, checks dependencies, and reports issues with your PraisonAI tools setup — using the same ToolResolver source of truth as praisonai tools list.

Quick Start

from praisonai.templates import ToolsDoctor

doctor = ToolsDoctor()
result = doctor.diagnose()

print(f"praisonai-tools installed: {result['praisonai_tools_installed']}")
print(f"Built-in tools: {len(result['builtin_tools'])}")
print(f"Issues found: {len(result['issues'])}")

# Human-readable output
print(doctor.diagnose_human())

How Tools Are Discovered

ToolsDoctor delegates to ToolResolver.list_available_sources() — the same resolution chain that praisonai tools list and resolve() use at run time. This guarantees that the doctor’s counts and listings match what actually loads when agents run. Bucket mapping:
Doctor fieldResolver bucketWhat’s included
builtin_toolsbuiltinTools from praisonaiagents.tools, sorted alphabetically
praisonai_tools_availableexternalTools from praisonai-tools package, sorted alphabetically
Registered tools (new)registeredTools from ToolRegistry.register_function() or entry-point plugins
Registered tools are now visible. As of PR #2642, tools registered via ToolRegistry.register_function() and core SDK entry-point plugins appear in the doctor’s output. Previously they were silently omitted — they resolved correctly at runtime but were invisible to diagnostics.See ToolResolver.list_available_sources() and the source label table for full details.

Fallback Behaviour

When ToolResolver cannot be imported (e.g. the praisonai wrapper package is not installed), the doctor falls back to:
  • _get_builtin_tools() → direct praisonaiagents.tools.TOOL_MAPPINGS scan (unsorted, legacy labels)
  • _get_praisonai_tools_list() → direct praisonai_tools module scan (unsorted, legacy labels)
The fallback path covers the same builtin and praisonai-tools sources, but misses the local, external (resolver-filtered), and registered buckets. Install the praisonai wrapper to get full resolver-backed diagnostics.

Python API

from praisonai.templates import ToolsDoctor

# Create doctor instance
doctor = ToolsDoctor()

# Run full diagnostics
result = doctor.diagnose()

# Check results
print(f"praisonai-tools installed: {result['praisonai_tools_installed']}")
print(f"Built-in tools: {len(result['builtin_tools'])}")
print(f"Issues found: {len(result['issues'])}")

# Get JSON output
json_output = doctor.diagnose_json()

# Get human-readable output
human_output = doctor.diagnose_human()
print(human_output)

Diagnostic Results

The diagnose() method returns a dictionary with:
KeyTypeDescription
praisonai_tools_installedboolWhether praisonai-tools package is installed
praisonaiagents_installedboolWhether praisonaiagents is installed
builtin_toolslistSorted list of available built-in tool names (resolver builtin bucket)
praisonai_tools_availablelistSorted list of tools from praisonai-tools (resolver external bucket)
custom_tools_dirslistStatus of custom tool directories
tool_dependenciesdictOptional dependencies for known tools
issueslistDetected issues with severity and hints
builtin_tools and praisonai_tools_available are sorted alphabetically — matching praisonai tools list output order. The legacy fallback path returns them in dict-iteration order (unsorted).

Custom Tool Directories

The doctor checks these default directories for custom tools:
  • ~/.praison/tools (primary)
  • ~/.config/praison/tools (XDG-friendly)
# Check with additional custom directories
doctor = ToolsDoctor(custom_dirs=["./my-tools", "~/shared-tools"])
result = doctor.diagnose()

for dir_info in result["custom_tools_dirs"]:
    status = "" if dir_info["exists"] else ""
    print(f"{status} {dir_info['path']} ({dir_info['tool_count']} tools)")

Tool Dependencies

The doctor checks optional dependencies for known tools:
result = doctor.diagnose()

for tool, deps in result["tool_dependencies"].items():
    missing = [d["name"] for d in deps if not d["available"]]
    if missing:
        print(f"Tool '{tool}' missing: {', '.join(missing)}")

Issue Severity Levels

SeverityDescription
errorCritical issue preventing tool usage
warningNon-critical issue that may affect functionality
infoInformational message about optional features

Tools Doctor CLI

Run diagnostics from the command line

Tool Resolver

list_available_sources() and source buckets

Tools

Source label table and CLI reference

Strict Tools Mode

Fail-fast dependency checking for templates