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

> Overview of PraisonAI's built-in tools for data search, analysis, and web scraping capabilities

Give an Agent a tool and it can search, fetch, and act — pass any Python function or built-in tool through `tools=[...]`.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.tools import duckduckgo

agent = Agent(instructions="Research AI news", tools=[duckduckgo])
agent.start("Find the latest AI news today")
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Tool Use"
        User[📋 User] --> Agent[🤖 Agent]
        Agent --> Tool[🔧 Tool]
        Tool --> Result[✅ Result]
    end

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class User,Agent input
    class Tool process
    class Result output
```

## Quick Start

<Steps>
  <Step title="Write a tool function">
    A tool is any typed Python function with a docstring:

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

    def internet_search_tool(query: str) -> List[Dict]:
        """Search the internet for the given query."""
        from duckduckgo_search import DDGS
        return [
            {"title": r.get("title", ""), "url": r.get("href", ""), "snippet": r.get("body", "")}
            for r in DDGS().text(keywords=query, max_results=5)
        ]
    ```
  </Step>

  <Step title="Give it to an Agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(instructions="Research assistant", tools=[internet_search_tool])
    agent.start("AI job trends in 2024")
    ```
  </Step>
</Steps>

<div className="relative w-full aspect-video">
  <iframe className="absolute top-0 left-0 w-full h-full" src="https://www.youtube.com/embed/XaQRgRpV7jo" title="YouTube video player" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />
</div>

## Inbuild Tools

* CodeDocsSearchTool
* CSVSearchTool
* DirectorySearchTool
* DirectoryReadTool
* DOCXSearchTool
* FileReadTool
* GithubSearchTool
* SerperDevTool
* TXTSearchTool
* JSONSearchTool
* MDXSearchTool
* PDFSearchTool
* PGSearchTool
* RagTool
* ScrapeElementFromWebsiteTool
* ScrapeWebsiteTool
* SeleniumScrapingTool
* WebsiteSearchTool
* XMLSearchTool
* YoutubeChannelSearchTool
* YoutubeVideoSearchTool

<Note>
  Need parameter limits that change at runtime? See [Dynamic Tool Schemas](/features/dynamic-tool-schemas) to make your tools reflect current configuration.
</Note>

## Example Usage

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: crewai
topic: research about the causes of lung disease
agents:  # Canonical: use 'agents' instead of 'roles'
  research_analyst:
    instructions: Experienced in analyzing scientific data related to respiratory health.  # Canonical: use 'instructions' instead of 'backstory'
    goal: Analyze data on lung diseases
    role: Research Analyst
    tasks:
      data_analysis:
        description: Gather and analyze data on the causes and risk factors of lung diseases.
        expected_output: Report detailing key findings on lung disease causes.
    tools:
    - WebsiteSearchTool
```

## How It Works

The Agent decides when to call a tool, runs the function, and feeds the result back into the model to complete its answer.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Tool

    User->>Agent: Request needing external data
    Agent->>Tool: Call tool with arguments
    Tool-->>Agent: Tool result
    Agent-->>User: Answer using the tool result
```

## How Tool Names Are Resolved

Pass a tool as a string like `tools=["internet_search"]` and the core SDK resolves it through a three-step chain, first match wins.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[🔤 tool name string] --> B{Registry?}
    B -->|hit| Z[✅ callable]
    B -->|miss| C{TOOL_MAPPINGS?}
    C -->|hit| Z
    C -->|miss| D{praisonai-tools installed?}
    D -->|hit| Z
    D -->|miss| W[⚠️ warning, skipped]

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef step fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff
    classDef warn fill:#F59E0B,stroke:#7C90A0,color:#fff

    class A input
    class B,C,D step
    class Z result
    class W warn
```

| Step | Source                    | Who owns it                                              | When it wins                           |
| ---- | ------------------------- | -------------------------------------------------------- | -------------------------------------- |
| 1    | Tool registry             | Tools you register via `praisonaiagents.tools.registry`  | You explicitly registered the name     |
| 2    | `TOOL_MAPPINGS`           | Built-in lazy tools shipped with `praisonaiagents.tools` | The name is a built-in tool            |
| 3    | `praisonai-tools` package | External integrations (`pip install praisonai-tools`)    | The name lives in the optional package |

An unresolved name is **skipped with a warning** — it never aborts agent construction:

```text theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
WARNING praisonaiagents.tools.resolver: Tool 'my_tool' not found (registry, TOOL_MAPPINGS, praisonai-tools)
```

<Note>
  Graceful skip means a typo or a tool from an uninstalled package no longer crashes your agent — the run continues with the tools that did resolve. Install the missing package (or fix the name) and the next run picks it up.
</Note>

<Tip>
  Resolve names yourself to check before a run:

  ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  from praisonaiagents.tools.resolver import resolve_tool_name

  tool = resolve_tool_name("internet_search")
  print(tool is not None)   # True when it resolved through any of the three steps
  ```
</Tip>

## Best Practices

<AccordionGroup>
  <Accordion title="Type your tool functions">
    Add type hints and a one-line docstring to every tool. The Agent uses these to build the tool schema the model sees.
  </Accordion>

  <Accordion title="Keep tools focused">
    Give each tool one clear job. Small, single-purpose tools are easier for the model to call correctly.
  </Accordion>

  <Accordion title="Prefer built-in tools first">
    Import ready-made tools from `praisonaiagents.tools` before writing your own — for example `from praisonaiagents.tools import duckduckgo`.
  </Accordion>

  <Accordion title="Return simple, structured data">
    Return lists of dicts or plain strings so the model can read the result. Avoid returning large objects or binary blobs.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Quick Start" icon="bolt" href="/docs/quickstart">
    Build your first agent with a tool.
  </Card>

  <Card title="Models" icon="brain" href="/docs/models">
    Choose the model that calls your tools.
  </Card>
</CardGroup>