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

# Different Ways to Create Tools

> Explore all methods for creating tools in PraisonAI

Choose between functions, classes, remote sources, or packages when extending agent capabilities.

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

@tool
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

agent = Agent(name="Toolkit", tools=[add])
agent.start("What is 2 plus 3?")
```

The user picks a tool style, registers it, and confirms the agent selects the right tool.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Tool Methods"
        U[📋 Style] --> A[🔧 Register]
        A --> O[✅ Agent Uses It]
    end

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

    class U input
    class A process
    class O output
```

## How It Works

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

    User->>Agent: Task needing a capability
    Agent->>Tool: Select and call the registered tool
    Tool-->>Agent: Result
    Agent-->>User: Answer using the result
```

***

## How to Create Tools as Functions

<Steps>
  <Step title="Define Simple Function">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    def calculator_tool(expression: str) -> float:
        """Evaluate a mathematical expression.
        
        Args:
            expression: Math expression to evaluate
            
        Returns:
            Result of the calculation
        """
        return eval(expression)
    ```
  </Step>

  <Step title="Use with Agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="calculator",
        tools=[calculator_tool]
    )
    ```
  </Step>
</Steps>

## How to Create Tools as Lambda Functions

<Steps>
  <Step title="Define Lambda Tool">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Simple lambda tool
    uppercase_tool = lambda text: text.upper()
    uppercase_tool.__doc__ = "Convert text to uppercase"
    uppercase_tool.__annotations__ = {"text": str, "return": str}
    ```
  </Step>

  <Step title="Use with Agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    agent = Agent(
        name="formatter",
        tools=[uppercase_tool]
    )
    ```
  </Step>
</Steps>

## How to Create Tools from External Libraries

<Steps>
  <Step title="Wrap Library Function">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import requests

    def http_get_tool(url: str) -> dict:
        """Make HTTP GET request.
        
        Args:
            url: URL to fetch
            
        Returns:
            Response data as dictionary
        """
        response = requests.get(url)
        return {
            "status": response.status_code,
            "content": response.text[:1000]
        }
    ```
  </Step>

  <Step title="Use Wrapped Tool">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    agent = Agent(
        name="http_agent",
        tools=[http_get_tool]
    )
    ```
  </Step>
</Steps>

## How to Create Tools in tools.py File

<Steps>
  <Step title="Create tools.py">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # tools.py

    def file_reader(path: str) -> str:
        """Read file contents.
        
        Args:
            path: Path to file
            
        Returns:
            File contents
        """
        with open(path, 'r') as f:
            return f.read()

    def file_writer(path: str, content: str) -> bool:
        """Write content to file.
        
        Args:
            path: Path to file
            content: Content to write
            
        Returns:
            Success status
        """
        with open(path, 'w') as f:
            f.write(content)
        return True
    ```
  </Step>

  <Step title="Reference in Template">
    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # agents.yaml
    roles:
      file_agent:
        tools:
          - file_reader
          - file_writer
    ```
  </Step>
</Steps>

## How to Create Tools in a Package

<Steps>
  <Step title="Create Package Structure">
    ```
    my_tools/
    ├── __init__.py
    ├── search.py
    └── database.py
    ```
  </Step>

  <Step title="Define Tools in Module">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # my_tools/search.py

    def web_search(query: str) -> list:
        """Search the web.
        
        Args:
            query: Search query
            
        Returns:
            List of results
        """
        return [{"title": "Result", "url": "https://example.com"}]
    ```
  </Step>

  <Step title="Export in __init__.py">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # my_tools/__init__.py
    from .search import web_search
    from .database import db_query

    __all__ = ["web_search", "db_query"]
    ```
  </Step>

  <Step title="Use as tools_source">
    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # TEMPLATE.yaml
    requires:
      tools_sources:
        - my_tools
    ```
  </Step>
</Steps>

## How to Create Tools with Decorators

<Steps>
  <Step title="Use Tool Decorator">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import tool

    @tool
    def decorated_tool(query: str) -> str:
        """A decorated tool function.
        
        Args:
            query: Input query
            
        Returns:
            Processed result
        """
        return f"Processed: {query}"
    ```
  </Step>

  <Step title="Use with Agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    agent = Agent(
        name="decorated_agent",
        tools=[decorated_tool]
    )
    ```
  </Step>
</Steps>

## How to Add Tools via CLI

<Steps>
  <Step title="Add Package Tools">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tools add pandas
    ```
  </Step>

  <Step title="Add Local File">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tools add ./my_tools.py
    ```
  </Step>

  <Step title="Add from GitHub">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tools add github:user/repo/tools
    ```
  </Step>

  <Step title="Verify Added Tools">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tools list
    ```
  </Step>
</Steps>

## How to Create Tools with Choice Parameters

<Steps>
  <Step title="Use Literal for Fixed Options">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from typing import Literal
    from praisonaiagents import Agent, tool

    @tool
    def format_text(text: str, style: Literal["bold", "italic", "underline"]) -> str:
        """Format text with specified style."""
        if style == "bold":
            return f"**{text}**"
        elif style == "italic":
            return f"*{text}*"
        else:
            return f"__{text}__"

    agent = Agent(
        instructions="You format text",
        tools=[format_text]
    )

    agent.start("Make this text bold")
    ```
  </Step>
</Steps>

See the [Tool Parameter Types](/docs/tools/parameter-types) page for complete guide on using Optional, Union, Literal, Enum, List, and Dict types.

## Tool Creation Methods Comparison

| Method        | Best For            | Complexity |
| ------------- | ------------------- | ---------- |
| Function      | Simple tools        | Low        |
| Lambda        | One-liners          | Low        |
| Class         | Stateful tools      | Medium     |
| Package       | Reusable tools      | Medium     |
| Decorator     | Enhanced tools      | Low        |
| External wrap | Library integration | Medium     |
| CLI add       | Quick setup         | Low        |

## Best Practices

<AccordionGroup>
  <Accordion title="Start with a plain function and @tool">
    The function-plus-decorator path has the lowest complexity and covers most tools — reach for classes only when you need shared state.
  </Accordion>

  <Accordion title="Use classes for stateful tools">
    When a tool holds a connection or cache, a class keeps that state tidy; pass the bound methods to the agent's `tools` list.
  </Accordion>

  <Accordion title="Wrap external libraries thinly">
    Adapt a library call into a typed, docstringed function so the model gets a clean schema without the library's full surface.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Create Custom Tools" icon="plus" href="/docs/guides/tools/create-custom-tools">
    Detailed walkthrough per tool style
  </Card>

  <Card title="Remote Tools from GitHub" icon="github" href="/docs/guides/tools/remote-tools-github">
    Load tools from remote sources
  </Card>
</CardGroup>