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

# Add Tools

> Add tools from files or GitHub to PraisonAI

## Understanding Tool Discovery

PraisonAI **automatically discovers** tools from `~/.praisonai/tools/`. Any `.py` file you place there will be loaded and its functions become available as tools.

## How to Add Tools from Local Files (Recommended)

<Steps>
  <Step title="Create Your Tools File">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # my_pandas_tools.py
    import pandas as pd
    from io import StringIO

    def analyze_csv_data(csv_data: str) -> str:
        """Analyze CSV data using pandas DataFrame.
        
        Args:
            csv_data: CSV-formatted string data
            
        Returns:
            Analysis summary
        """
        df = pd.read_csv(StringIO(csv_data))
        return f"""Shape: {df.shape}
    Columns: {list(df.columns)}
    Statistics:
    {df.describe().to_string()}"""
    ```
  </Step>

  <Step title="Add File to Tools Directory">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tools add ./my_pandas_tools.py
    ```

    Output:

    ```
    ✅ Added tools file: my_pandas_tools.py
       Copied to: ~/.praisonai/tools/my_pandas_tools.py
       Found 1 tools: analyze_csv_data
    ```
  </Step>

  <Step title="Verify Tools Are Discovered">
    Tools in `~/.praisonai/tools/` are auto-discovered:

    ```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)
    print("analyze_csv_data" in registry)  # True
    ```
  </Step>

  <Step title="Use in Agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="data_analyst",
        role="Data Analyst",
        tools=[analyze_csv_data]
    )

    csv = "name,age\\nAlice,30\\nBob,25"
    result = agent.start(f"Analyze this data: {csv}")
    ```
  </Step>
</Steps>

## Why Packages Need Wrapper Tools

Running `praisonai tools add pandas` will show:

```
⚠️  Package 'pandas' is installed but NOT directly usable as tools
    Found 102 callable items in package

    To use this package with agents, create wrapper tools:
    1. Create a file: ~/.praisonai/tools/my_tools.py
    2. Define wrapper functions with docstrings
    3. Tools will be auto-discovered
```

**Packages like pandas are NOT tools** - they are libraries. To use them with agents, you must create **wrapper functions** with:

* Type hints for parameters
* Docstrings with Args section
* JSON-serializable return values

## How to Add Tools from Local Files

<Steps>
  <Step title="Create Tools File">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # my_tools.py
    def my_custom_tool(query: str) -> str:
        """Process a query.
        
        Args:
            query: Input query
            
        Returns:
            Processed result
        """
        return f"Processed: {query}"
    ```
  </Step>

  <Step title="Add File to Tools">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tools add ./my_tools.py
    ```

    Output:

    ```
    ✅ Added tools file: my_tools.py
       Copied to: ~/.praisonai/tools/my_tools.py
       Found 1 tools: my_custom_tool
    ```
  </Step>

  <Step title="Use in Template">
    Reference the tool in your `agents.yaml`:

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    roles:
      processor:
        tools:
          - my_custom_tool
    ```
  </Step>
</Steps>

## How to Add Tools from GitHub

<Steps>
  <Step title="Add from GitHub Repository">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tools add github:MervinPraison/PraisonAI-tools/praisonai_tools
    ```
  </Step>

  <Step title="Verify Download">
    Tools are downloaded to `~/.praisonai/tools/`
  </Step>
</Steps>

## Configuration File

Tools sources are stored in `~/.praisonai/tools_sources.yaml`:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sources:
- pandas
- numpy
```

## Key Concept

**Packages vs Tools**: When you add a package like `pandas`, you're registering it as a source. To use it with agents, you need to create **wrapper functions** that expose specific functionality as tools with proper docstrings and type hints.