Building a Custom Tool for a CrewAI Agent

A CrewAI tool is a named, described, schema-bound function an agent can call while working a task.

Custom tools wrap your APIs, databases, and internal services so specialists act in the real world instead of only writing prose.

Summary

Expose a clear name and description, define Pydantic input (and optional output) schemas, implement _run (sync or async), attach the tool only to agents that need it, and fail with readable errors the model can recover from.

Recipe

1. Pick the smallest capability that unblocks the role (one endpoint, not the whole platform).
2. Write a description that states when to use it and when not to.
3. Define args_schema with Field descriptions the model will read.
4. Implement _run (or use @tool on a function) with timeouts, auth from env, and structured errors.
5. Optionally return a Pydantic model for typed outputs; override format_output_for_agent if the agent should see Markdown instead of JSON.
6. Attach the tool to the matching agent only.
7. Run a verbose task that must call the tool; confirm arguments and caching behavior.
8. Add cache rules only after you know which results are safe to reuse.

Working Example

from typing import Type
from pydantic import BaseModel, Field
from crewai import Agent, Task, Crew, Process
from crewai.tools import BaseTool
 
 
class InventoryInput(BaseModel):
    sku: str = Field(..., description="Product SKU, for example SKU-123")
 
 
class InventoryResult(BaseModel):
    sku: str
    quantity: int
    needs_reorder: bool
 
 
class InventoryCheckTool(BaseTool):
    name: str = "inventory_check"
    description: str = (
        "Check on-hand quantity for a product SKU. "
        "Use when the task needs stock levels. "
        "Do not use for pricing or customer PII."
    )
    args_schema: Type[BaseModel] = InventoryInput
 
    def _run(self, sku: str) -> InventoryResult:
        # Replace with a real API call + timeout
        stock = {"SKU-123": 14, "SKU-456": 0}
        if sku not in stock:
            # Readable errors help the agent recover or ask for a better SKU
            return InventoryResult(sku=sku, quantity=0, needs_reorder=True)
        qty = stock[sku]
        return InventoryResult(sku=sku, quantity=qty, needs_reorder=qty < 5)
 
 
inventory_tool = InventoryCheckTool()
 
ops = Agent(
    role="Inventory Ops Analyst",
    goal="Report stock status accurately using inventory tools",
    backstory="You never invent quantities. You only report tool results.",
    tools=[inventory_tool],
    verbose=True,
)
 
task = Task(
    description="Check stock for {sku} and say whether to reorder.",
    expected_output="One short paragraph with sku, quantity, and reorder recommendation.",
    agent=ops,
)
 
crew = Crew(agents=[ops], tasks=[task], process=Process.sequential, verbose=True)
print(crew.kickoff(inputs={"sku": "SKU-123"}).raw)

Decorator form for quick functions:

from crewai.tools import tool
 
@tool("multiply")
def multiply(first_number: int, second_number: int) -> int:
    """Multiply two integers. Use only for arithmetic checks."""
    return first_number * second_number

Deep Dive

What the agent actually sees

The model chooses tools from name + description + argument schema. If the description is vague ("does stuff with data"), the agent will call it randomly or never.

Good descriptions include:

• Primary use case
• Required inputs
• Side effects (writes, emails, charges)
• Hard non-goals

BaseTool vs @tool

Typed outputs

Returning a Pydantic model gives agents stable field names (quantity, needs_reorder). Direct Python tool.run(...) still receives the real object. Agents typically receive JSON unless you customize format_output_for_agent.

Caching

Tools support result caching to skip identical re-calls. Override cache_function when only some results are safe to cache (for example pure math yes, live inventory no).

Security

• Read secrets from the environment inside _run, never from user-controlled tool args.
• Enforce least privilege: the tool's credentials should not be a god-mode admin key.
• Validate and canonicalize inputs (IDs, URLs, SQL) before execution.
• Prefer dedicated sandboxes (E2B, Modal, etc.) for code execution rather than deprecated in-process interpreters when running untrusted code (verify current guidance at build).

Built-in tools first

Before writing custom code, check crewai_tools (search, files, web, vector search, cloud, etc.). Custom tools should cover your domain gaps.

Gotchas

1. Name collisions or cute names. Prefer stable snake_case verbs the model can reselect.
2. Empty descriptions. The agent cannot infer intent from Python alone.
3. Over-broad tools. run_sql(query: str) invites injection and chaos; expose narrow operations.
4. Swallowing exceptions. Return structured error strings or raise clear errors; silent None causes loops.
5. Attaching every tool to every agent. Destroys role specialization and increases prompt bloat.
6. Caching mutable data. Stale inventory or permissions bugs are worse than an extra API call.
7. Blocking forever. Always set HTTP/client timeouts.
8. Forgetting that tool output is untrusted content. Never let retrieved text redefine system policy.

Alternatives

FAQs

Related

Related: CrewAI Basics

Related: Defining Agent Roles, Goals, and Backstories

Related: The CrewAI Mental Model: Roles, Tasks, and Crews

Related: Debugging a Crew That Won't Converge on an Answer

Related: CrewAI Best Practices

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.