BaseTool: Reference Guide

What is BaseTool?

BaseTool is the object-oriented tool surface in CrewAI: you declare name and description as class attributes so the LLM sees a stable tool catalog entry, define args_schema as a Pydantic model for structured inputs, and implement _run for synchronous execution with optional _arun for asyncio-native backends. The framework wraps exceptions, feeds results back into the agent loop, and respects caching when enabled on the owning Agent.

Reach for BaseTool instead of the @tool decorator when you need persistent state (database pools, OAuth sessions), inheritance to share behavior across several tools, or custom validation hooks that are awkward to express as a single function. Keep descriptions short but intention-revealing — the model chooses tools based on this text more than on the class name.

Security-wise, BaseTool runs in the same process as your crew. Treat _run like a network-facing handler: validate paths, enforce authz, and never let the model supply raw SQL without parameterization. Combine with @before_tool_call_crew hooks for global gates when multiple tools share policy.

When to Use

Stateful integrations, shared base classes for a family of tools, or anything that fits OOP better than @tool.

Use Cases

• • Internal APIs
• • Custom data sources
• • Compound tools with shared setup

Key Features

• ✓ Pydantic args_schema
• ✓ Sync + async bodies
• ✓ Reusable across agents

When NOT to Use

Notes

Import

from crewai.tools import BaseTool

Key Parameters

Code Examples

from pydantic import BaseModel, Field
from crewai.tools import BaseTool

class TickInput(BaseModel):
    delta: int = Field(default=1, ge=1, le=10)

class CounterTool(BaseTool):
    name = 'counter'
    description = 'Increment an in-memory counter'
    args_schema = TickInput

    def __init__(self):
        super().__init__()
        self._value = 0

    def _run(self, delta: int) -> str:
        self._value += delta
        return f'value={self._value}'

import requests
from pydantic import BaseModel, HttpUrl
from crewai.tools import BaseTool

class FetchInput(BaseModel):
    url: HttpUrl

class HttpGetTool(BaseTool):
    name = 'http_get'
    description = 'Fetch text from an allowlisted HTTPS URL'
    args_schema = FetchInput

    def _run(self, url: HttpUrl) -> str:
        if not str(url).startswith('https://api.internal/'):
            raise ValueError('URL not allowlisted')
        return requests.get(str(url), timeout=10).text[:8000]

from pydantic import BaseModel, Field
from crewai import Agent
from crewai.tools import BaseTool

class StepInput(BaseModel):
    delta: int = Field(default=1, ge=1, le=5)

class StepTool(BaseTool):
    name = 'step_counter'
    description = 'Increment an internal counter by delta'
    args_schema = StepInput
    _value = 0

    def _run(self, delta: int) -> str:
        StepTool._value += delta
        return f'value={StepTool._value}'

agent = Agent(
    role='Demo',
    goal='Call the counter',
    backstory='You only use tools when asked.',
    tools=[StepTool()],
)

Common Mistakes

BaseTool FAQ