Tools - PraisonAI

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 five source categories — builtin, local, external, registered, or mcp — reflecting the exact source that resolve() would use at run time (and, for mcp, the servers your agent will connect to live). The resolver-backed buckets (builtin / local / external / registered) also power 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
praisonai tools list --source mcp

Expected Output:

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

  internet_search       [builtin]
  wikipedia_search      [builtin]
  my_custom_tool        [local]
  my_plugin_tool        [registered]
  read                  [mcp]
  write                 [mcp]
  read (filesystem-b)   [mcp]

--------------------------------------------------
Total: 7 tools
Built-in: 2 | Local: 1 | External: 0 | Registered: 1 | MCP: 3

Unavailable MCP servers:
  • research-server: timed out after 8s
  • old-fs: connection failed

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
`mcp`	Tools exposed by MCP servers configured under `mcp.servers.*` in the active config; discovered live on each `tools list` invocation

When two servers expose a tool with the same name, the listing disambiguates the second one as name (server) so both stay visible.

The --source help text accepts builtin, local, external, registered, mcp.

List MCP tools

MCP tools appear when you configure a server under mcp.servers.* in your config.

# agents.yaml — enable an MCP server
mcp:
  servers:
    filesystem:
      command: "npx -y @modelcontextprotocol/server-filesystem /tmp"
      enabled: true

# See every tool this agent will actually be able to call —
# built-ins, your local tools.py, and live MCP server tools together.
praisonai tools list

The names shown under the mcp source are the exact names an agent dispatches at run time — copy any of them into --tools "name1,name2" and they resolve.

# Show only MCP-discovered tools
praisonai tools list --source mcp

tools list discovers MCP tools live: it reads the same mcp.servers.* config the run path uses, connects to each server, and enforces an 8-second per-server timeout (_MCP_DISCOVERY_TIMEOUT_S) so one slow server never stalls the listing. Discovery is lazy — it runs only for the default view or --source mcp — and fail-soft: a broken server never crashes the command.

When no MCP servers are configured, --source mcp prints an empty table with MCP: 0 — zero network cost.

Unavailable MCP servers

When a server is unreachable, it appears in an Unavailable MCP servers: section with the reason — never a silent omission.

Unavailable MCP servers:
  • research-server: timed out after 8s
  • old-fs: connection failed

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.

praisonai tools doctor and praisonai tools discover do not enumerate MCP tools — that surface stays local to praisonai tools list for cost reasons. Use praisonai tools list --source mcp to inspect MCP tools.

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.

​Quick Start

​Commands

​List Tools

​List MCP tools

​Unavailable MCP servers

​Get Tool Info

​Validate Tools

​Diagnostics

​Help

​Tool Categories

Search Tools

File Tools

Code Tools

Data Tools

Web Tools

API Tools

​Using Tools with Prompts

​Built-in Tools by Name

​Tools from File

​Tool Dependencies

​Creating Custom Tools

​Best Practices

Right Tool

Dependencies

Custom Tools

Documentation

​Related

Quick Start

Commands

List Tools

List MCP tools

Unavailable MCP servers

Get Tool Info

Validate Tools

Diagnostics

Help

Tool Categories

Using Tools with Prompts

Built-in Tools by Name

Tools from File

Tool Dependencies

Creating Custom Tools

Best Practices

Related