CrewAI Tools Reference¶

The buyer agent provides 13 tools that agents use to interact with sellers, plan audiences, execute bookings, and retrieve performance data. All tools extend CrewAI's BaseTool and expose both synchronous (_run) and asynchronous (_arun) interfaces.

Tool Categories¶

graph LR
    subgraph Audience["Audience Tools"]
        AD[AudienceDiscoveryTool]
        AM[AudienceMatchingTool]
        CE[CoverageEstimationTool]
    end

    subgraph DSP["DSP Tools"]
        DI[DiscoverInventoryTool]
        GP[GetPricingTool]
        RD[RequestDealTool]
    end

    subgraph Execution["Execution Tools"]
        CO[CreateOrderTool]
        CL[CreateLineTool]
        RL[ReserveLineTool]
        BL[BookLineTool]
    end

    subgraph Research["Research Tools"]
        PS[ProductSearchTool]
        AC[AvailsCheckTool]
    end

    subgraph Reporting["Reporting Tools (Coming Soon)"]
        GS[GetStatsTool]
    end

Audience Tools¶

Audience tools use the IAB Tech Lab User Context Protocol (UCP) to discover, match, and estimate audience coverage across seller inventory.

Package: src/ad_buyer/tools/audience/

AudienceDiscoveryTool¶

Discovers available audience signals from a seller endpoint via UCP.

CrewAI name: discover_audience_capabilities

Returns: Capabilities grouped by signal type, each with coverage percentage, available segments, and UCP compatibility status.

from ad_buyer.tools.audience import AudienceDiscoveryTool

tool = AudienceDiscoveryTool()
result = tool._run(
    seller_endpoint="http://seller.example.com:8000/ucp/capabilities",
    signal_types=["contextual", "identity"],
    min_coverage=50.0,
)

AudienceMatchingTool¶

Computes a UCP similarity score between the campaign's target audience and a seller's inventory audience characteristics.

CrewAI name: match_audience_to_inventory

Returns: Match quality (STRONG/MODERATE/WEAK/POOR), UCP similarity score (0--1), matched capabilities, gaps, and suggested alternatives.

from ad_buyer.tools.audience import AudienceMatchingTool

tool = AudienceMatchingTool()
result = tool._run(
    seller_endpoint="http://seller.example.com:8000/ucp/exchange",
    demographics={"age": "25-54", "gender": "all"},
    interests=["sports", "news"],
    geography="US",
)

CoverageEstimationTool¶

Estimates audience reach for a targeting specification across channels.

CrewAI name: estimate_audience_coverage

Returns: Per-channel coverage estimates with impression counts, coverage percentages, confidence levels, and limiting factors.

from ad_buyer.tools.audience import CoverageEstimationTool

tool = CoverageEstimationTool()
result = tool._run(
    targeting={
        "demographics": {"age": "25-54"},
        "interests": ["sports"],
        "geography": "US",
    },
    channel="ctv",
    total_impressions=5_000_000,
)

Coverage factors by targeting type:

Channel modifiers:

DSP Tools¶

DSP tools enable programmatic deal workflows where Deal IDs are obtained from sellers and activated in traditional DSP platforms. All three tools require a UnifiedClient and BuyerContext at initialization.

Package: src/ad_buyer/tools/dsp/

DiscoverInventoryTool¶

Queries sellers for available inventory with identity-based access and tiered pricing.

CrewAI name: discover_inventory

Returns: List of products with tiered pricing based on buyer identity, availability, and targeting capabilities.

from ad_buyer.tools.dsp import DiscoverInventoryTool
from ad_buyer.clients.unified_client import UnifiedClient
from ad_buyer.models.buyer_identity import BuyerContext, BuyerIdentity

client = UnifiedClient(base_url="http://seller.example.com:8000")
buyer_context = BuyerContext(
    identity=BuyerIdentity(seat_id="ttd-123", agency_id="omnicom-456"),
    is_authenticated=True,
)

tool = DiscoverInventoryTool(client=client, buyer_context=buyer_context)
result = tool._run(query="premium CTV sports inventory", max_cpm=30.0)

GetPricingTool¶

Retrieves tier-specific pricing for a product, including volume discounts and deal type options.

CrewAI name: get_pricing

Returns: Full pricing breakdown with base CPM, tier discount, volume discount, final CPM, cost projection, and available deal types.

from ad_buyer.tools.dsp import GetPricingTool

tool = GetPricingTool(client=client, buyer_context=buyer_context)
result = tool._run(
    product_id="prod-ctv-sports-001",
    volume=10_000_000,
    deal_type="PD",
    flight_start="2026-07-01",
    flight_end="2026-09-30",
)

Volume discounts (agency/advertiser tiers only):

RequestDealTool¶

Requests a Deal ID from a seller for programmatic activation in a DSP platform.

CrewAI name: request_deal

Returns: Deal ID, pricing details, and platform-specific activation instructions for The Trade Desk, DV360, Amazon DSP, Xandr, and Yahoo DSP.

from ad_buyer.tools.dsp import RequestDealTool

tool = RequestDealTool(client=client, buyer_context=buyer_context)
result = tool._run(
    product_id="prod-ctv-sports-001",
    deal_type="PD",
    impressions=500_000,
    flight_start="2026-07-01",
    flight_end="2026-09-30",
    target_cpm=22.0,
)

Execution Tools¶

Execution tools manage the OpenDirect booking lifecycle: creating orders, adding line items, reserving inventory, and confirming bookings. All require an OpenDirectClient at initialization.

Package: src/ad_buyer/tools/execution/

CreateOrderTool¶

Creates a new advertising order (IO) in OpenDirect.

CrewAI name: create_advertising_order

Returns: Order ID and status confirmation.

CreateLineTool¶

Creates a line item within an order, defining the actual media purchase.

CrewAI name: create_line_item

Returns: Line ID, status, and estimated cost.

ReserveLineTool¶

Reserves inventory for a line item, transitioning it from Draft to Reserved status.

CrewAI name: reserve_line_item

Returns: Updated line status confirmation. The inventory is temporarily held without final commitment.

BookLineTool¶

Confirms booking for a line item, transitioning from Reserved to Booked.

CrewAI name: book_line_item

Returns: Booking confirmation with guaranteed impressions and total cost.

Booking Lifecycle¶

The four execution tools move line items through the OpenDirect booking states:

CreateOrder → CreateLine → ReserveLine → BookLine
                  ↓             ↓            ↓
                Draft    →  Reserved   →  Booked  →  InFlight  →  Finished

Research Tools¶

Research tools discover and evaluate advertising inventory via OpenDirect APIs. Both require an OpenDirectClient at initialization.

Package: src/ad_buyer/tools/research/

ProductSearchTool¶

Searches for advertising products across publishers.

CrewAI name: search_advertising_products

Returns: Formatted list of matching products with pricing, reach estimates, and targeting capabilities.

AvailsCheckTool¶

Checks real-time availability and pricing for a specific product during a flight window.

CrewAI name: check_inventory_availability

Returns: Available impressions, guaranteed delivery, delivery confidence, estimated CPM, and total cost.

Reporting Tools¶

Package: src/ad_buyer/tools/reporting/

GetStatsTool¶

Retrieves performance statistics for a line item.

CrewAI name: get_line_statistics

Returns: Delivery metrics (impressions, pacing, delivery rate), spend data (amount spent, budget utilization), and performance indicators (effective CPM, VCR, viewability, CTR).

Tool Initialization Patterns¶

Tools are typically initialized within crew factory functions, not directly by application code. Here is how each crew creates its tool sets:

# Research tools -- require OpenDirectClient
from ad_buyer.tools.research import ProductSearchTool, AvailsCheckTool

research_tools = [
    ProductSearchTool(client),
    AvailsCheckTool(client),
]

# Execution tools -- require OpenDirectClient
from ad_buyer.tools.execution import (
    CreateOrderTool, CreateLineTool, ReserveLineTool, BookLineTool,
)

execution_tools = [
    CreateOrderTool(client),
    CreateLineTool(client),
    ReserveLineTool(client),
    BookLineTool(client),
]

# Audience tools -- no client required
from ad_buyer.tools.audience import (
    AudienceDiscoveryTool, AudienceMatchingTool, CoverageEstimationTool,
)

audience_tools = [
    AudienceDiscoveryTool(),
    AudienceMatchingTool(),
    CoverageEstimationTool(),
]

# DSP tools -- require UnifiedClient + BuyerContext
from ad_buyer.tools.dsp import (
    DiscoverInventoryTool, GetPricingTool, RequestDealTool,
)

dsp_tools = [
    DiscoverInventoryTool(client=unified_client, buyer_context=buyer_ctx),
    GetPricingTool(client=unified_client, buyer_context=buyer_ctx),
    RequestDealTool(client=unified_client, buyer_context=buyer_ctx),
]

Related¶

• Agent Hierarchy --- Which agents use which tools
• DSP Deal Flow --- How DSP tools work together in a flow
• Booking Flow --- How execution tools drive the booking lifecycle
• Configuration --- Tool-related settings