Praison AI

Tools

Discover and manage available tools for agents

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

Quick Start

bash
# List all available tools
praisonai tools list
List available tools example
bash
# Get info about a specific tool
praisonai tools info internet_search

!Discover and Manage Available Tools

!Trust All Tools

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.

bash
praisonai tools list

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

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

SourceWhat it means
builtinShipped with praisonaiagents.tools — no extra install needed
localLoaded from your local tools.py file
externalFrom the optional praisonai-tools package
registeredRegistered via ToolRegistry (register_function) or a core SDK entry-point plugin
mcpTools 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.

List MCP tools

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

yaml
# agents.yaml — enable an MCP server
mcp:
  servers:
    filesystem:
      command: "npx -y @modelcontextprotocol/server-filesystem /tmp"
      enabled: true
bash
# 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.

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

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

bash
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
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 every tool referenced in an agents YAML will resolve (defaults to agents.yaml):

bash
praisonai tools validate agents.yaml

Both agent-level and task-level tools: entries are checked:

yaml
agents:
  researcher:
    tools:
      - internet_search      # agent-level
    tasks:
      find_sources:
        tools:
          - tavily_search    # task-level

A tool is accepted if any of these can supply it:

  • Built-in tools (praisonaiagents.tools)
  • Registered tools and entry-point plugins
  • The praisonai-tools package
  • Local tools.py or tools/ directory
  • @tool functions in .praisonai/tools/*.py

Local sources (tools.py, tools/, .praisonai/tools/) only count when PRAISONAI_ALLOW_LOCAL_TOOLS=true is set — the same opt-in praisonai run requires. See Local Tools Loading.

Validation uses the same discovery path as list and info, and the same local sources as praisonai run, so a config that passes validation resolves at agent run time. Unresolved names are listed and the command exits with code 1.

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.

bash
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

bash
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 <yaml>   - Validate every tool in an agents YAML
  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

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

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

Tools from File

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

Example tools.py:

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

ToolRequired Package
internet_searchduckduckgo-search
tavily_searchtavily-python
crawl4aicrawl4ai
yfinanceyfinance
pandas_querypandas
duckdb_queryduckdb

Install missing dependencies:

bash
pip install duckduckgo-search tavily-python

Creating Custom Tools

python
# 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
praisonai "Find customer records" --tools tools.py

Best Practices

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

Related