Agents are only as powerful as the tools they can access. In this lesson, we learn how to build and expose Custom Tools (Python functions) to your agent swarms, allowing them to perform real-world actions like database lookups, API calls, and local file manipulation.

The Tooling Interface

A custom tool requires 3 components:

1. The Logic: The raw Python function.
2. The Metadata: A description telling the agent when and how to use the tool.
3. The Error Handling: Ensuring the agent can recover if the tool fails.

from crewai_tools import tool
import requests

@tool("psi_auditor")
def psi_auditor(url: str) -> str:
    """Performs a Google PageSpeed Insights audit and returns the LCP score."""
    api_url = f"https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url={url}&category=PERFORMANCE"
    response = requests.get(api_url).json()
    lcp = response['lighthouseResult']['audits']['largest-contentful-paint']['displayValue']
    return f"Technical Audit for {url}: LCP is {lcp}."

The agent doesn't see your code; it only sees the Docstring. If your description is vague (e.g., "Fetches data"), the agent will use it incorrectly. A high-status description is precise: "Use this tool ONLY when you need to identify the Largest Contentful Paint (LCP) for a specific website URL."

Tool Error Handling Pattern

from crewai_tools import tool
import requests

@tool("safe_psi_auditor")
def safe_psi_auditor(url: str) -> str:
    """Performs a Google PageSpeed Insights audit and returns LCP score.
    Use this tool when you need to assess website performance for a lead.
    Input: Full URL (e.g., https://example.com). Output: Performance score
    and LCP value, or structured error if the URL is unreachable."""

    try:
        if not url.startswith("http"):
            return "ERROR: INVALID_URL — URL must start with http:// or https://"

        api_url = f"https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url={url}&category=PERFORMANCE"
        response = requests.get(api_url, timeout=10)

        if response.status_code != 200:
            return f"ERROR: PSI_API_FAILURE — Status {response.status_code}"

        data = response.json()
        score = data['lighthouseResult']['categories']['performance']['score'] * 100
        lcp = data['lighthouseResult']['audits']['largest-contentful-paint']['displayValue']

        return f"Performance: {score}/100. LCP: {lcp}. Priority: {'HIGH' if score < 60 else 'MEDIUM' if score < 80 else 'LOW'}"

    except requests.Timeout:
        return "ERROR: TIMEOUT — Site may be down or very slow. Skip this lead."
    except KeyError:
        return "ERROR: PARSE_FAILURE — PSI returned unexpected format."
    except Exception as e:
        return f"ERROR: UNKNOWN — {str(e)}"

Each error message tells the agent what happened AND what to do next. This is how production tools are written.

Pakistan Project: The WhatsApp Lead Qualifier Tool

Pakistani businesses live on WhatsApp. Build a custom tool for your agent:

@tool("whatsapp_lead_qualifier")
def qualify_lead_whatsapp(phone: str, business_name: str) -> str:
    """Checks if a Pakistani business has an active WhatsApp Business account
    and returns their profile status. Use this tool when you need to verify
    if a lead can be reached via WhatsApp before sending a pitch."""

    # Format PK number
    clean_phone = phone.replace(" ", "").replace("-", "")
    if clean_phone.startswith("0"):
        clean_phone = "+92" + clean_phone[1:]

    # Check via WATI or WhatsApp Business API
    # Returns: "ACTIVE" / "PERSONAL" / "NOT_FOUND"
    return f"WhatsApp status for {business_name} ({clean_phone}): ACTIVE"

Why this tool is gold: In Pakistan, email open rates are 15-20%. WhatsApp open rates are 90%+. An agent that can check WhatsApp status before deciding the outreach channel will always outperform one that defaults to email.

The Tool Docstring Decision Matrix

The docstring is the tool's entire interface with the agent. Poor docstrings are the #1 cause of tool misuse in production systems.

Rule: Every docstring should answer 3 questions:

1. When SHOULD the agent use this tool?
2. What input does it expect?
3. What will the output look like?

Visual Reference

Custom Tool Architecture

┌─────────────────────────────────────┐
│ AGENT ORCHESTRATOR                  │
│ (CrewAI / AutoGen)                  │
└────────────┬────────────────────────┘
             │
    ┌────────┴────────┐
    │                 │
    ↓                 ↓
┌──────────┐     ┌──────────────────┐
│ Reasoning│     │ Tool Registry    │
│ Engine   │     │ ┌──────────────┐ │
└──────────┘     │ │@tool("psi")  │ │
                 │ │@tool("whatsapp")
                 │ │@tool("csv")  │ │
                 │ └──────────────┘ │
                 │                  │
                 │ Agent selects:   │
                 │ "I need whatsapp │
                 │  _lead_qualifier"│
                 └────────┬─────────┘
                          │
                          ↓
                   ┌─────────────────┐
                   │ Python Function │
                   │ (Actual Logic)  │
                   └────────┬────────┘
                            │
                            ↓
                   Return result to Agent

Pakistan Case Study: The 3-Tool Agency Bot

Sana built a CrewAI agent for her Karachi digital agency. Her agent had access to 3 custom tools: a PSI auditor (website speed), a WhatsApp status checker, and a CRM writer (SQLite).

Her agent's decision logic:

Agent directive:
"For each lead in the list:
1. Run PSI audit — if score < 60: mark as HIGH priority
2. Check WhatsApp status — if ACTIVE: add to whatsapp_queue, else email_queue
3. Write lead to CRM with all data filled in
4. If HIGH priority + WhatsApp ACTIVE: flag for SAME-DAY outreach"

What happened when she ran it on 50 leads:

• PSI Auditor called 50 times → 31 scored under 60
• WhatsApp checker called 31 times → 22 had active WhatsApp Business
• CRM Writer called 50 times → 50 rows written correctly
• 22 high-priority WhatsApp leads flagged for same-day outreach

Time taken by agent: 4 minutes Time taken manually: 6-8 hours

Her WhatsApp tool's docstring (the one that made the difference):

"""Use this tool ONLY when you need to verify if a Pakistani business
phone number has an active WhatsApp Business account BEFORE deciding
the outreach channel. Input: Pakistani phone number (with or without
country code). Output: 'ACTIVE', 'PERSONAL', or 'NOT_FOUND'."""

Without the "ONLY when" clause, the agent kept calling it on every lead unnecessarily. After adding it: the agent correctly called it only after PSI audit confirmed high priority.

Financial impact: Sana closed 4 new clients in the first month running this system. At PKR 25,000/client/month, that's PKR 100,000 in new monthly recurring revenue — built on a system she coded in one evening.

Building a Tool Library: Pakistani Agency Starter Kit

For a Karachi-based digital agency, these 5 custom tools cover 80% of your outreach research needs:

Total build time: 5-6 hours. Time saved per 100 leads: 15-20 hours. Break-even: after the first outreach run.

Exercise 1: Build a Python function that takes a JSON string and returns the character count. Add a proper docstring describing when agents should use it. Register it with a dummy agent prompt. Ask the agent: "Count the characters in this JSON: {'name': 'Ali', 'city': 'Karachi'}." Verify it chooses your tool instead of guessing.

Exercise 2: Create a simple "discount calculator" tool: takes base_price (PKR) and discount_percent, returns the final price. Add a docstring with "Use this ONLY when calculating final price after discount for Pakistani business leads." Test with: "If a restaurant charges PKR 5,000/month and we offer 20% discount, what is the new price?"

Exercise 3: Build the CRM Writer tool from the homework section. Test it by running a 5-lead dataset through a CrewAI agent: (1) Agent reads leads from list, (2) Agent writes each to CSV, (3) Verify the CSV output is correctly formatted. This is the foundation of every automated outreach system.

Key Takeaways

• Custom tools transform agents from reasoning machines into action machines. An agent with tools can read databases, send messages, check APIs, and write files.
• The docstring is the tool's interface to the agent. A vague docstring leads to wrong tool selection. Write docstrings as precise decision rules: "Use this ONLY when X."
• Error handling inside tools prevents agent failure cascades. A tool that returns a structured error message keeps the agent running; one that raises an exception stops the whole crew.
• WhatsApp tooling is the highest-leverage custom tool for Pakistan. Email open rates are 15-20%; WhatsApp is 90%+. Agents that can verify WhatsApp status before choosing an outreach channel dramatically outperform email-only systems.
• Build your tool library incrementally: start with 2-3 core tools, run real campaigns, add tools to handle gaps you discover in production.
• The "ONLY when" pattern in docstrings is the single biggest improvement you can make to agent tool selection accuracy — add it to every tool you build.

Build a custom tool that takes a {lead_phone, lead_name, city, score} object and appends it to a local CSV file formatted for the WhatsApp Outreach Bot. Register this tool with a CrewAI agent and verify the agent can write to the CSV autonomously. Test with 10 fictional Karachi restaurant leads and confirm the output CSV is correctly structured.