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

# Tools

> Discover and manage available tools for agents

The `tools` command helps you discover, explore, and manage the tools available for your agents.

<Note>
  The same resolver chain used by `praisonai tools list` also powers `praisonai tools doctor`, `praisonai tools discover`, `--rewrite-tools`, `--expand-tools`, and `praisonai research --tools`. Any name shown by `praisonai tools list` is accepted by all of them. As of [PR #2642](https://github.com/MervinPraison/PraisonAI/pull/2642), the diagnostics commands walk the full resolver source list instead of a `TOOL_MAPPINGS` subset. See [Tool Resolution](/cli/deep-research#which-tool-names-work) for the full resolution order.
</Note>

## Quick Start

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List all available tools
praisonai tools list
```

<Frame>
  <img src="https://mintcdn.com/praisonai/2OBv0nvWLwS-3tNQ/docs/cli/tools-list-available-tools.gif?s=5483b552d2f1b804c217926240915d43" alt="List available tools example" width="1497" height="1104" data-path="docs/cli/tools-list-available-tools.gif" />
</Frame>

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Get info about a specific tool
praisonai tools info internet_search
```

<img src="https://mintcdn.com/praisonai/fT4nF3hY6KPMOPvS/docs/cli/tools-discover-and-manage-available-.gif?s=cb3d7527f47eec12fb8208b1ff3c9bff" alt="Discover and Manage Available Tools" width="1497" height="1104" data-path="docs/cli/tools-discover-and-manage-available-.gif" />

<img src="https://mintcdn.com/praisonai/Rqp2Yho_5cGAckvS/docs/cli/trust-trust-all-tools.gif?s=10f9da99ae2080bb95b59ae498cba314" alt="Trust All Tools" width="1497" height="1104" data-path="docs/cli/trust-trust-all-tools.gif" />

## Commands

### List Tools

Each tool is attributed to one of four source categories — `builtin`, `local`, `external`, or `registered` — reflecting the exact source that `resolve()` would use at run time. The same resolver-backed enumeration now powers `praisonai tools doctor` and template dependency checking — see [Tools Doctor](/docs/cli/tools-doctor) and [Strict Tools Mode](/docs/cli/strict-tools).

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai tools list
```

Filter by source using `--source` (or `-s`):

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai tools list --source registered
praisonai tools list -s local
praisonai tools list -s builtin
praisonai tools list -s external
```

**Expected Output:**

```
🔧 Available Tools:
--------------------------------------------------

  internet_search     [builtin]   Perform internet searches using DuckDuckGo
  wikipedia_search    [builtin]   Search Wikipedia
  my_custom_tool      [local]     Tool from local tools.py
  my_plugin_tool      [registered] Entry-point plugin tool

--------------------------------------------------
Total: <count> tools
Built-in: <X> | Local: <Y> | External: <Z> | Registered: <W>
```

**Source categories:**

| Source       | What it means                                                                        |
| ------------ | ------------------------------------------------------------------------------------ |
| `builtin`    | Shipped with `praisonaiagents.tools` — no extra install needed                       |
| `local`      | Loaded from your local `tools.py` file                                               |
| `external`   | From the optional `praisonai-tools` package                                          |
| `registered` | Registered via `ToolRegistry` (`register_function`) or a core SDK entry-point plugin |

### Get Tool Info

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai tools info internet_search
```

**Expected Output:**

````
🔧 Tool: internet_search

┌─────────────────────┬────────────────────────────────────────────┐
│ Property            │ Value                                      │
├─────────────────────┼────────────────────────────────────────────┤
│ Name                │ internet_search                            │
│ Category            │ Search                                     │
│ Status              │ ✅ Available                               │
│ Dependencies        │ duckduckgo-search                          │
└─────────────────────┴────────────────────────────────────────────┘

Source: praisonaiagents.tools (built-in)

Description:
  Perform internet searches using DuckDuckGo. Returns a list of
  search results with titles, URLs, and snippets.

Parameters:
  • query (str, required): The search query
  • max_results (int, optional): Maximum results to return (default: 5)

Example Usage:
  ```python
  from praisonaiagents import Agent

  agent = Agent(
      instructions="Search the web for information",
      tools=[internet_search]
  )
  agent.start("Search for AI news")
````

Returns:
List of dictionaries with keys: title, url, snippet

````

**Source labels in `tools info`:**

| Source value | Label shown |
|---|---|
| `builtin` | `Source: praisonaiagents.tools (built-in)` |
| `local` | `Source: Local tools.py` |
| `external` | `Source: praisonai-tools package` |
| `registered` | `Source: Registered/entry-point tool (registry)` |

### Search Tools

```bash
praisonai tools search "web"
````

**Expected Output:**

```
🔍 Searching tools for: "web"

Found 4 matching tools:

  1. crawl4ai
     Category: Web
     Description: Crawl and extract content from web pages

  2. trafilatura
     Category: Web
     Description: Extract main content from web pages

  3. internet_search
     Category: Search
     Description: Search the web using DuckDuckGo

  4. tavily_search
     Category: Search
     Description: AI-powered web search with Tavily
```

Add `--verbose` (or `-v`) to include the description column:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai tools search "web" --verbose
```

When nothing matches, the command prints `No tools matching '<query>'.` followed by the hint `Run 'praisonai tools list' to see all available tools.`

### Validate Tools

Check that a tool is discoverable and will resolve correctly:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai tools validate internet_search
```

Validation uses the same discovery path as `list` and `info`, so a tool that passes validation will also be visible in `tools list` and resolvable at agent run time.

### Diagnostics

`praisonai tools doctor` and `praisonai tools discover` surface every tool the resolver would find — `builtin` + `local` + `external` + `registered` — rather than just the `TOOL_MAPPINGS` subset. As of [PR #2642](https://github.com/MervinPraison/PraisonAI/pull/2642), the doctor reports the full \~151 built-in tools, and `discover` also lists entry-point plugin tools.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai tools doctor      # full resolver-backed diagnostics
praisonai tools discover    # includes the registered bucket
```

The same source-category table (`builtin` / `local` / `external` / `registered`) applies to `tools doctor` and `tools discover` output. See [Tools Doctor](/docs/cli/tools-doctor) and [Tools Discover](/docs/cli/tools-discover).

### Help

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai tools help
```

**Expected Output:**

```
Tools Commands:

  praisonai tools list              - List all available tools
  praisonai tools info <name>       - Get detailed info about a tool
  praisonai tools search <query>    - Search for tools by name/description
  praisonai tools validate <name>   - Validate a tool is discoverable
  praisonai tools help              - Show this help

Using Tools with Agents:
  praisonai "task" --tools "tool1,tool2"   - Use specific tools
  praisonai "task" --tools tools.py        - Load tools from file
```

## Tool Categories

<CardGroup cols={2}>
  <Card title="Search Tools" icon="magnifying-glass">
    * `internet_search`
    * `wikipedia_search`
    * `arxiv_search`
    * `tavily_search`
    * `duckduckgo`
  </Card>

  <Card title="File Tools" icon="file">
    * `read_file`
    * `write_file`
    * `list_files`
    * `csv_read`
    * `json_read`
    * `yaml_read`
  </Card>

  <Card title="Code Tools" icon="code">
    * `execute_code`
    * `shell_command`
    * `calculator`
    * `python_repl`
  </Card>

  <Card title="Data Tools" icon="database">
    * `pandas_query`
    * `duckdb_query`
    * `yfinance`
    * `excel_read`
  </Card>

  <Card title="Web Tools" icon="globe">
    * `crawl4ai`
    * `trafilatura`
    * `newspaper`
    * `spider`
  </Card>

  <Card title="API Tools" icon="plug">
    * `rest_api`
    * `graphql`
    * `webhook`
  </Card>
</CardGroup>

## Using Tools with Prompts

### Built-in Tools by Name

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Single tool
praisonai "Search for Python tutorials" --tools "internet_search"

# Multiple tools
praisonai "Research and calculate" --tools "internet_search,calculator"
```

### Tools from File

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Create tools.py with custom tools
praisonai "Custom task" --tools tools.py
```

**Example tools.py:**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
def my_custom_tool(query: str) -> str:
    """Custom tool description"""
    return f"Result for: {query}"

def another_tool(data: dict) -> dict:
    """Another custom tool"""
    return {"processed": data}
```

## Tool Dependencies

Some tools require additional packages:

| Tool              | Required Package    |
| ----------------- | ------------------- |
| `internet_search` | `duckduckgo-search` |
| `tavily_search`   | `tavily-python`     |
| `crawl4ai`        | `crawl4ai`          |
| `yfinance`        | `yfinance`          |
| `pandas_query`    | `pandas`            |
| `duckdb_query`    | `duckdb`            |

Install missing dependencies:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install duckduckgo-search tavily-python
```

## Creating Custom Tools

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# tools.py
from typing import List, Dict

def search_database(query: str, limit: int = 10) -> List[Dict]:
    """
    Search the internal database.
    
    Args:
        query: Search query string
        limit: Maximum results to return
        
    Returns:
        List of matching records
    """
    # Your implementation
    return results
```

Use with CLI:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "Find customer records" --tools tools.py
```

## Best Practices

<Tip>
  Use `praisonai tools info <name>` to understand a tool's parameters before using it.
</Tip>

<CardGroup cols={2}>
  <Card title="Right Tool">
    Choose tools appropriate for the task
  </Card>

  <Card title="Dependencies">
    Install required packages before using tools
  </Card>

  <Card title="Custom Tools">
    Create custom tools for domain-specific needs
  </Card>

  <Card title="Documentation">
    Add docstrings to custom tools for better agent understanding
  </Card>
</CardGroup>

<Note>
  When a `--tools` name doesn't resolve, PraisonAI prints `Unknown tool 'X'. Run 'praisonai tools list' to see available tools.` If a local `tools.py` is present but `PRAISONAI_ALLOW_LOCAL_TOOLS` is unset, it prints `Skipped 'X': set PRAISONAI_ALLOW_LOCAL_TOOLS=true to load local tools.`
</Note>

## Related

* [Tools Concept](/concepts/tools)
* [Custom Tools](/tools/custom)
* [Tool Development](/tutorials/advanced-tool-development)