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

# Debug Tools

> Step-by-step guide to debugging and troubleshooting tools

## How to Use Tools Doctor

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