Tools

Discover and manage available tools for agents

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

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, the diagnostics commands walk the full resolver source list instead of a TOOL_MAPPINGS subset. See Tool Resolution for the full resolution order.

Quick Start

# List all available tools
praisonai tools list

# Get info about a specific tool
praisonai tools info internet_search

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 and Strict Tools Mode.

praisonai tools list

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

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

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:

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:

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, the doctor reports the full ~151 built-in tools, and discover also lists entry-point plugin tools.

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 and Tools Discover.

Help

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

Search Tools

• internet_search
• wikipedia_search
• arxiv_search
• tavily_search
• duckduckgo

File Tools

• read_file
• write_file
• list_files
• csv_read
• json_read
• yaml_read

Code Tools

• execute_code
• shell_command
• calculator
• python_repl

Data Tools

• pandas_query
• duckdb_query
• yfinance
• excel_read

Web Tools

• crawl4ai
• trafilatura
• newspaper
• spider

API Tools

• rest_api
• graphql
• webhook

Using Tools with Prompts

Built-in Tools by Name

# Single tool
praisonai "Search for Python tutorials" --tools "internet_search"

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

Tools from File

# Create tools.py with custom tools
praisonai "Custom task" --tools tools.py

Example tools.py:

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:

pip install duckduckgo-search tavily-python

Creating Custom Tools

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

praisonai "Find customer records" --tools tools.py

Best Practices

Use praisonai tools info <name> to understand a tool’s parameters before using it.

Right Tool

Choose tools appropriate for the task

Dependencies

Install required packages before using tools

Custom Tools

Create custom tools for domain-specific needs

Documentation

Add docstrings to custom tools for better agent understanding

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.

Related

• Tools Concept
• Custom Tools
• Tool Development