> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Debug Tools"
        U[📋 Failing Tool] --> A[🔍 tools doctor]
        A --> O[✅ Resolved Call]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class U input
    class A process
    class O output
```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI
    participant Resolver

    User->>CLI: praisonai tools doctor
    CLI->>Resolver: Walk the resolver chain
    Resolver-->>CLI: Availability + import errors
    CLI-->>User: Fixes 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](https://github.com/MervinPraison/PraisonAI/pull/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.

<Steps>
  <Step title="Run Tools Doctor">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tools doctor
    ```
  </Step>

  <Step title="Check Specific Tool">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tools info shell_tool
    ```
  </Step>

  <Step title="Review Diagnostics">
    Doctor output shows:

    * Tool availability
    * Missing dependencies
    * Configuration issues
    * Import errors
  </Step>

  <Step title="Fix Identified Issues">
    Install missing packages or fix configuration based on doctor output.
  </Step>
</Steps>

## How to Debug Tool Resolution

<Steps>
  <Step title="Resolve Tool Name">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tools resolve my_tool
    ```
  </Step>

  <Step title="Check Tool Sources">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tools show-sources
    ```
  </Step>

  <Step title="Discover Available Tools">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tools discover
    ```
  </Step>

  <Step title="Search for Tools">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tools search "search"
    ```
  </Step>
</Steps>

## How to Debug Tools with Python

<Steps>
  <Step title="Test Tool Directly">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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)}")
    ```
  </Step>

  <Step title="Check Tool Signature">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import inspect

    sig = inspect.signature(my_custom_tool)
    print(f"Parameters: {sig.parameters}")
    print(f"Return annotation: {sig.return_annotation}")
    ```
  </Step>

  <Step title="Validate Docstring">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    print(f"Docstring: {my_custom_tool.__doc__}")
    ```
  </Step>

  <Step title="Test with Agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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")
    ```
  </Step>
</Steps>

## How to Debug Tool Registry

<Steps>
  <Step title="Create Registry">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai.templates.tool_override import create_tool_registry_with_overrides

    registry = create_tool_registry_with_overrides(include_defaults=True)
    ```
  </Step>

  <Step title="List All Tools">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    print("Available tools:")
    for name in sorted(registry.keys()):
        print(f"  - {name}")
    ```
  </Step>

  <Step title="Check Specific Tool">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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")
    ```
  </Step>
</Steps>

## 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Test the tool in isolation">
    Call the function directly and check its return type before blaming the agent — most failures are plain Python errors.
  </Accordion>

  <Accordion title="Inspect the signature and docstring">
    Use `inspect.signature` to confirm the tool exposes the parameters and return type the model expects.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Create Custom Tools" icon="plus" href="/docs/guides/tools/create-custom-tools">
    Build tools with correct signatures
  </Card>

  <Card title="Assign Tools to Templates" icon="link" href="/docs/guides/tools/assign-tools-to-templates">
    Wire tools into recipes
  </Card>
</CardGroup>