<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/5.1-tool-integration -->

# Tool Integration

- api.md
- src/praisonai-agents/praisonaiagents/agent/agent.py
- src/praisonai-agents/praisonaiagents/llm/llm.py

## Purpose and Scope

This document covers the core tool integration system in PraisonAI, including the `@tool` decorator, `BaseTool` class, `FunctionTool` wrapper, and `ToolRegistry` for discovering and managing tools. It explains how tools are registered, validated, and executed by agents.

For information about creating pip-installable tool packages and auto-discovery mechanisms, see [Custom Tools and Plugins](/MervinPraison/PraisonAI/5.4-custom-tools-and-plugins). For integrating external tools via Model Context Protocol, see [MCP Protocol](/MervinPraison/PraisonAI/5.2-mcp-protocol). For agent-to-agent tool exposure, see [A2A Protocol](/MervinPraison/PraisonAI/5.3-a2a-protocol).

## Tool System Architecture

The tool system provides three primary interfaces for creating tools: function decoration with `@tool`, subclassing `BaseTool`, and direct `FunctionTool` wrapping. All tools are registered in a centralized `ToolRegistry` that handles discovery, validation, and retrieval.

### Tool Integration Overview

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/__init__.py63-67](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L63-L67) [src/praisonai-agents/praisonaiagents/tools/](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/tools/)

### Tool Execution Flow

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py) [src/praisonai-agents/praisonaiagents/tools/registry.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/tools/registry.py)

## Core Components

### @tool Decorator

The `@tool` decorator is the simplest method for converting Python functions into agent tools. It automatically extracts function signatures, docstrings, and type hints to generate tool schemas for LLMs.

**File Location:** [src/praisonai-agents/praisonaiagents/tools/decorator.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/tools/decorator.py)

**Usage Pattern:**

```

```

**Decorator Behavior:**

- Wraps function in FunctionTool instance
- Extracts parameter names, types, and defaults from signature
- Uses docstring for tool description
- Automatically registers with ToolRegistry
- Preserves function metadata (name, module, etc.)

**Sources:** [README.md2774-2799](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2774-L2799) [src/praisonai-agents/praisonaiagents/__init__.py65](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L65-L65)

### BaseTool Class

`BaseTool` is the abstract base class for tools requiring more control over initialization, state management, or complex execution logic. Subclasses must implement the `run()` method.

**File Location:** [src/praisonai-agents/praisonaiagents/tools/base.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/tools/base.py)

**Class Structure:**

```

```

**Required Attributes:**

- name (str): Tool identifier used by LLMs
- description (str): Human-readable description of tool purpose
- run(**kwargs) (method): Tool execution logic

**Optional Attributes:**

- parameters (dict): JSON Schema for parameters (auto-generated from run() signature if not provided)

**Usage Pattern:**

```

```

**Sources:** [README.md2800-2817](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2800-L2817) [src/praisonai-agents/praisonaiagents/__init__.py64](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L64-L64)

### FunctionTool

`FunctionTool` is a `BaseTool` subclass that wraps regular Python functions. It is automatically created by the `@tool` decorator but can also be instantiated directly for programmatic tool creation.

**File Location:** [src/praisonai-agents/praisonaiagents/tools/decorator.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/tools/decorator.py)

**Automatic vs Manual Creation:**

**Manual FunctionTool Usage:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/__init__.py65](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L65-L65)

### ToolRegistry

The `ToolRegistry` is a singleton registry that manages all available tools. It provides methods for registering, retrieving, and listing tools globally across the application.

**File Location:** [src/praisonai-agents/praisonaiagents/tools/registry.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/tools/registry.py)

**Registry Architecture:**

```

```

**Public API:**

**Usage Pattern:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/__init__.py66](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L66-L66) [src/praisonai-agents/praisonaiagents/tools/registry.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/tools/registry.py)

## Tool Discovery and Registration

Tools are discovered and registered through multiple mechanisms, creating a flexible system that supports both built-in and user-defined tools.

### Registration Mechanisms

```

```

**Registration Order:**

1. Import-time Registration : @tool decorator registers function when module is imported
2. Entry Point Discovery : Plugins with praisonaiagents.tools entry point are auto-discovered
3. Manual Registration : Explicit calls to register_tool() during initialization
4. Agent Parameter Resolution : Tools referenced by name in Agent(tools=[...]) are resolved from registry

**Agent Tool Parameter Types:**

**Sources:** [README.md1441-1449](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1441-L1449) [src/praisonai-agents/praisonaiagents/tools/registry.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/tools/registry.py)

### Tool Name Resolution

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agent/agent.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py)

## Tool Validation

Before execution, all tool calls are validated to ensure type correctness and parameter completeness. The validation system uses the `validate_tool()` function and returns structured `ToolResult` objects.

### Validation Flow

```

```

**Validation Components:**

**ToolResult Structure:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/__init__.py64](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L64-L64) [src/praisonai-agents/praisonaiagents/tools/base.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/tools/base.py)

## Built-in Tools

PraisonAI includes 100+ built-in tools covering web search, data analysis, file operations, and external service integrations. Tools are organized into categories based on functionality.

### Tool Categories

### Tools CLI Commands

The `praisonai tools` CLI provides commands for discovering and inspecting available tools:

```

```

**Sources:** [README.md1957-1975](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1957-L1975) [README.md394](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L394-L394)

### Tool Discovery CLI

```

```

**Sources:** [README.md1957-1975](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1957-L1975)

### Using Built-in Tools with Agents

```

```

**Sources:** [README.md394](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L394-L394)

## Tool Integration with LLM Providers

Tools are automatically formatted into provider-specific schemas based on the LLM being used. The framework handles differences between OpenAI, Anthropic, Google, and other providers' tool calling formats.

### Provider-Specific Tool Schemas

```

```

**Provider Compatibility:**

**Ollama Special Handling:**

Ollama requires special tool format conversion and retry logic. The framework automatically:

- Converts tool schemas to Ollama-compatible format
- Implements retry loops for tool parsing failures
- Provides fallback mechanisms for unsupported features

**Sources:** [src/praisonai-agents/praisonaiagents/agent/llm.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/llm.py)

### Tool Execution Context

Tools receive context about the agent and current execution state through special parameters:

**Context Injection Example:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/tools/decorator.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/tools/decorator.py)

## Tools Table Reference

The complete reference of available built-in tools:

For the complete list of 100+ tools, use:

```

```

**Sources:** [README.md114](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L114-L114) [README.md1957-1975](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1957-L1975)
