adcp-signals

name	adcp-signals
description	Execute AdCP Signals Protocol operations with signal agents - discover audience signals using natural language and activate them on DSPs or sales agents. Use when users want to find targeting data, activate audience segments, or work with signal providers.

AdCP Signals Protocol

This skill enables you to execute the AdCP Signals Protocol with signal agents. Use the standard MCP tools (get_signals, activate_signal) exposed by the connected agent.

Buyer-side basics — idempotency replay, oneOf variants, async status:'submitted' polling, error recovery from adcp_error.issues[] — live in skills/call-adcp-agent/SKILL.md. This skill covers per-task semantics only.

Overview

The Signals Protocol provides 2 standardized tasks for discovering and activating targeting data:

Task	Purpose	Response Time
get_signals	Discover signals using natural language	~60s
activate_signal	Activate a signal on a platform/agent	Minutes-Hours

Typical Workflow

1. Discover signals: get_signals with a natural language description of targeting needs
2. Review options: Evaluate signals by coverage, pricing, and deployment status
3. Activate if needed: activate_signal for signals not yet live on your platform
4. Use in campaigns: Reference the activation key in your media buy targeting

---

Task Reference

get_signals

Discover signals based on natural language description, with deployment status across platforms.

Request:

{
  "signal_spec": "High-income households interested in luxury goods",
  "destinations": [
    {
      "type": "platform",
      "platform": "the-trade-desk",
      "account": "agency-123"
    }
  ],
  "countries": ["US"],
  "filters": {
    "max_cpm": 5.0,
    "catalog_types": ["marketplace"]
  },
  "max_results": 5
}

Key fields:

• signal_spec (string, conditional): Natural language description of desired signals. Required unless signal_ids is provided.
• destinations (array, optional): Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. Each item: type, platform/agent_url, optional account.
• countries (array, optional): ISO 3166-1 alpha-2 country codes where signals will be used
• filters (object, optional): Filter by catalog_types, data_providers, max_cpm, min_coverage_percentage
• max_results (number, optional): Limit number of results

Deployment types:

// DSP platform
{ "type": "platform", "platform": "the-trade-desk", "account": "agency-123" }

// Sales agent
{ "type": "agent", "agent_url": "https://salesagent.example.com" }

Response contains:

• signals: Array of matching signals with:
  • signal_agent_segment_id: Use this in activate_signal
  • name, description: Human-readable signal info
  • data_provider: Source of the signal data
  • coverage_percentage: Reach relative to agent's population
  • deployments: Status per platform with is_live, activation_key, estimated_activation_duration_minutes
  • pricing: CPM and currency

---

activate_signal

Activate a signal for use on a specific platform or agent.

Request:

{
  "signal_agent_segment_id": "luxury_auto_intenders",
  "deployments": [
    {
      "type": "platform",
      "platform": "the-trade-desk",
      "account": "agency-123-ttd"
    }
  ]
}

Key fields:

• signal_agent_segment_id (string, required): From get_signals response
• deployments (array, required): Target deployment(s) with type, platform/agent_url, and optional account

Response contains:

• deployments: Array with activation results per target
  • activation_key: The key to use for targeting (segment ID or key-value pair)
  • deployed_at: ISO timestamp when activation completed
  • estimated_activation_duration_minutes: Time remaining if async
• errors: Any warnings or errors encountered

---

Key Concepts

Deployment Targets

Signals can be activated on two types of targets:

DSP Platforms:

{
  "type": "platform",
  "platform": "the-trade-desk",
  "account": "agency-123"
}

Sales Agents:

{
  "type": "agent",
  "agent_url": "https://wonderstruck.salesagents.com"
}

Activation Keys

When signals are live, the response includes an activation key for targeting:

Segment ID format (typical for DSPs):

{
  "type": "segment_id",
  "segment_id": "ttd_segment_12345"
}

Key-Value format (typical for sales agents):

{
  "type": "key_value",
  "key": "audience_segment",
  "value": "luxury_auto_intenders"
}

Signal Types

• marketplace: Licensed from data providers (CPM pricing)
• custom: Built for specific principal accounts
• owned: Private signals from your own data (no cost)

Coverage Percentage

Indicates signal reach relative to the agent's population:

• 99%: Very broad signal (matches most identifiers)
• 50%: Medium signal
• 1%: Very niche signal

Asynchronous Operations

Signal activation may take time. Check the response:

• is_live: true + activation_key: Ready to use immediately
• is_live: false + estimated_activation_duration_minutes: Activation in progress

Poll or use webhooks to check completion status.

---

Error Handling

Common error codes:

• SIGNAL_AGENT_SEGMENT_NOT_FOUND: Invalid signal_agent_segment_id
• ACTIVATION_FAILED: Could not activate signal
• ALREADY_ACTIVATED: Signal already active on target
• DEPLOYMENT_UNAUTHORIZED: Not authorized for platform/account
• AGENT_NOT_FOUND: Private agent not visible to this principal
• AGENT_ACCESS_DENIED: Not authorized for this signal agent

Error responses include:

{
  "errors": [
    {
      "code": "DEPLOYMENT_UNAUTHORIZED",
      "message": "Account not authorized for this data provider",
      "field": "deployment.account",
      "suggestion": "Contact your account manager to enable access"
    }
  ]
}