get_products

Searches the publisher’s advertising product catalog using AI-powered retrieval, returning products that match a natural language brief and optional structured filters.

Description

The get_products tool is the primary entry point for product discovery. It accepts a natural language brief describing what the buyer is looking for (e.g., “premium video inventory targeting sports fans in the US”) and uses AI/RAG (Retrieval-Augmented Generation) to find matching products from the publisher’s catalog.

Results include pricing options, available creative formats, estimated exposure volumes, supported channels, and geographic availability. When a brand_manifest is provided, the agent can further tailor recommendations to the brand’s category, audience, and compliance requirements.

Response times are typically a few seconds due to the AI-powered search pipeline.

Parameters

Name Type Required Description Default
brief str Yes Natural language description of desired advertising products. The AI search engine interprets this to find relevant matches. –
brand_manifest BrandManifest No Brand metadata including category, audience profile, and compliance requirements. Enables personalized product recommendations. None
adcp_version str No AdCP protocol version for response formatting. "1.0.0"
filters ProductFilters No Structured filters to narrow results (see below). None
push_notification_config PushNotificationConfig No Configuration for async push notifications when results are ready. None
context ContextObject No Additional context about the buying agent’s session and preferences. None

ProductFilters

The filters parameter accepts a ProductFilters object with the following fields:

Name Type Description
channels list[str] Filter by channel (e.g., ["display", "video"])
countries list[str] Filter by country code (ISO 3166-1 alpha-2)
format_ids list[str] Filter by creative format identifiers
min_budget float Minimum budget threshold
max_budget float Maximum budget threshold

BrandManifest

The brand_manifest parameter accepts a BrandManifest object that describes the advertiser:

Name Type Description
brand_name str Name of the advertising brand
category str Industry category (e.g., “automotive”, “retail”)
audience AudienceProfile Target audience demographics and interests
compliance ComplianceRequirements Regulatory and brand safety requirements

Response

Returns a GetProductsResponse object containing a list of matching products:

Field Type Description
products list[Product] Matching products ranked by relevance
total_results int Total number of matching products
search_metadata SearchMetadata Information about the search execution

Each Product in the list contains:

Field Type Description
product_id str Unique product identifier
name str Human-readable product name
description str Detailed product description
pricing_options list[PricingOption] Available pricing models (CPM, CPC, flat rate, etc.)
format_ids list[str] Compatible creative format identifiers
estimated_exposures ExposureEstimate Estimated impression/exposure volumes
channels list[str] Delivery channels (display, video, audio, native)
countries list[str] Geographic availability (ISO 3166-1 alpha-2 codes)

Error Codes

Error Code Description
validation_error Invalid parameters (e.g., empty brief)
internal_error AI search pipeline failure

Example

from mcp import ClientSession

async with ClientSession(transport) as session:
    await session.initialize()

    # Simple natural language search
    result = await session.call_tool(
        "get_products",
        arguments={
            "brief": "premium video ads targeting tech professionals in the US"
        },
    )
    products = result.content
    for product in products["products"]:
        print(f"{product['name']}: {product['pricing_options']}")

    # Search with brand context and filters
    result = await session.call_tool(
        "get_products",
        arguments={
            "brief": "high-impact display placements for luxury automotive",
            "brand_manifest": {
                "brand_name": "Luxe Motors",
                "category": "automotive",
            },
            "filters": {
                "channels": ["display"],
                "countries": ["US", "GB"],
            },
        },
    )

Example response:

{
  "products": [
    {
      "product_id": "prod_abc123",
      "name": "Premium Video - Tech Audience",
      "description": "Pre-roll and mid-roll video inventory across tech publisher network",
      "pricing_options": [
        {"model": "CPM", "amount": 25.00, "currency": "USD"}
      ],
      "format_ids": ["video_16x9_preroll", "video_16x9_midroll"],
      "estimated_exposures": {
        "min_impressions": 100000,
        "max_impressions": 500000,
        "period": "monthly"
      },
      "channels": ["video"],
      "countries": ["US"]
    }
  ],
  "total_results": 1
}

Protocol Specification

The get_products tool implements the AdCP get_products task. See the AdCP Specification for the full protocol definition including BrandManifest schema and product response format.