Tool Reference

Schemas, parameters, and examples for each tool exposed by the AIARCO MCP Server.

broadcast_signal

Send behavioral signals extracted from conversations to the AIARCO Ads Engine. Signals describe user interests, purchase intent, brand affinities, and other behavioral patterns that enable contextual ad matching.

Input Schema

{
  "signals": [Signal],     // required — array of 1-10 signals
  "userId": "string",      // optional — unique user identifier
  "sessionId": "string",   // optional — current session identifier
  "groupingId": "string"   // optional — correlation ID for signal groups
}

Limits

1–10 signals per call
500 characters max per subject field
10 items max per relatedSubjects array

Signal Fields

Required

Field	Type	Description
`category`	`enum`	Signal category (see table below)

Optional

Field	Type	Description
`confidence`	`float`	Confidence score, 0.0–1.0 (default: 1.0)
`subject`	`string`	Primary subject (e.g. “noise-canceling headphones”)
`relatedSubjects`	`string[]`	Related topics or products
`sentiment`	`string`	`positive`, `negative`, or `neutral`
`attributes`	`object`	Additional key-value pairs (e.g. `{"budget": "under $300"}`)
`extractionReason`	`string`	Why this signal was extracted from the conversation

Signal Categories

Category	When to Use	Example Subject
`interest`	User shows curiosity about a topic	”electric vehicles”
`evaluation`	Actively comparing products or services	”MacBook Pro vs Dell XPS”
`problem`	Experiencing an issue a product could solve	”back pain from office chair”
`purchase_intent`	Clear intent to buy something	”wireless headphones under $350”
`price_sensitivity`	Focus on pricing, deals, or budgets	”cheapest flight to Tokyo”
`brand_affinity`	Preference or loyalty to a specific brand	”Sony”
`user_context`	Personal context relevant to targeting	”works from home”
`business_context`	Professional or business needs	”SaaS startup scaling”
`recommendation_request`	Explicitly asking for recommendations	”best CRM for small teams”

Example — Simple Signal

{
  "signals": [
    {
      "category": "interest",
      "subject": "sustainable fashion",
      "confidence": 0.7
    }
  ]
}

Example — Detailed Signal

{
  "signals": [
    {
      "category": "purchase_intent",
      "confidence": 0.9,
      "subject": "wireless noise-canceling headphones",
      "sentiment": "positive",
      "relatedSubjects": ["Sony WH-1000XM5", "Bose QC Ultra"],
      "attributes": {
        "budget": "under $350",
        "use_case": "commuting"
      },
      "extractionReason": "User asked to compare headphones for daily commute"
    }
  ],
  "sessionId": "sess_xyz789"
}

Example — Multiple Signals

{
  "signals": [
    {
      "category": "purchase_intent",
      "confidence": 0.85,
      "subject": "running shoes"
    },
    {
      "category": "brand_affinity",
      "confidence": 0.7,
      "subject": "Nike",
      "sentiment": "positive"
    },
    {
      "category": "price_sensitivity",
      "confidence": 0.6,
      "subject": "running shoes under $150"
    }
  ]
}

Response

{
  "status": "ok",
  "signalCount": 1,
  "message": "Successfully broadcast 1 signal(s)"
}

Confidence Score Guidelines

Range	Meaning	When to Use
`0.9–1.0`	Very High	Explicit statement (“I want to buy…”)
`0.7–0.89`	High	Strong implication from context
`0.5–0.69`	Medium	Reasonable inference
`0.3–0.49`	Low	Weak signal, possibly tangential
`0.0–0.29`	Very Low	Speculative, background context only

get_offers

Retrieve contextual ad offers from the AIARCO Ads Engine. Offers are matched based on a search query and any signals previously broadcast. Returns personalized offers with title, content, CTA, click URL, brand info, and pricing.

Input Schema

{
  "query": "string",       // required — search query or context
  "limit": 1,             // optional — number of offers, 1-8
  "context": "string",    // optional — additional matching context
  "placement": "string",  // optional — placement identifier
  "locale": "en",         // optional — locale code
  "device": "desktop",    // optional — device type
  "geo": "string",        // optional — country code
  "signals": [SignalItem] // optional — inline signals
}

Example

{
  "query": "best wireless headphones under $350",
  "limit": 2,
  "signals": [
    {
      "category": "purchase_intent",
      "confidence": 0.9,
      "subject": "wireless headphones"
    }
  ]
}

Response

{
  "status": "ok",
  "offers": [
    {
      "id": "offer_abc123",
      "title": "Sony WH-1000XM5",
      "content": "Industry-leading noise cancellation with 30-hour battery life.",
      "cta": "Shop Now",
      "clickUrl": "https://ads-api.aiarco.com/click/offer_abc123",
      "brand": {
        "name": "Sony",
        "iconUrl": "https://..."
      },
      "price": {
        "amount": 298.0,
        "currency": "USD",
        "original": 349.99,
        "discount": "15% off"
      }
    }
  ],
  "impression_id": "imp_xyz789",
  "tracking": {
    "click_url": "https://ads-api.aiarco.com/api/v1/clicks/imp_xyz789",
    "view_url": "https://ads-api.aiarco.com/api/v1/impressions/imp_xyz789/view"
  }
}

Save the impression_id — you’ll need it for track_impressions.

track_impressions

Report ad impression viewability back to the Ads Engine. Call this after offers from get_offers have been displayed to the user. This completes the signal → offer → impression tracking loop.

Input Schema

{
  "ids": ["string"] // required — array of impression IDs
}

Example

{
  "ids": ["imp_xyz789", "imp_abc456"]
}

Response

{
  "status": "ok",
  "tracked": 2,
  "message": "Successfully tracked 2 impression(s)"
}

Typical Integration Flow

A complete interaction follows this pattern:

User sends message

AI assistant processes the conversation naturally.

Extract signals

AI identifies behavioral signals (interests, intent, brands).

broadcast_signal

Send extracted signals to AIARCO for contextual matching.

get_offers

Retrieve personalized offers based on signals and query.

Display offers

Present offers naturally within the conversation.

track_impressions

Report that offers were viewed to complete the loop.

Best Practices

Be specific with subjects — “wireless noise-canceling headphones” is better than “headphones”
Use accurate confidence scores — Reserve 0.9+ for explicit statements; use 0.5–0.7 for inferences
Send multiple signal categories — A single message often contains interest + brand affinity + purchase intent
Always track impressions — This is essential for accurate reporting and revenue attribution
Include context in get_offers — The more context you provide, the better the offer matching

Getting Started

Publishers

Integration

Signals & Tracking

MCP Server

Reference

Tool Reference

broadcast_signal

Input Schema

Limits

Signal Fields

Required

Optional

Signal Categories

Example — Simple Signal

Example — Detailed Signal

Example — Multiple Signals

Response

Confidence Score Guidelines

get_offers

Input Schema

Example

Response

track_impressions

Input Schema

Example

Response

Typical Integration Flow

Best Practices

Getting Started

Publishers

Integration

Signals & Tracking

MCP Server

Reference

​broadcast_signal

​Input Schema

​Limits

​Signal Fields

​Required

​Optional

​Signal Categories

​Example — Simple Signal

​Example — Detailed Signal

​Example — Multiple Signals

​Response

​Confidence Score Guidelines

​get_offers

​Input Schema

​Example

​Response

​track_impressions

​Input Schema

​Example

​Response

​Typical Integration Flow

​Best Practices

broadcast_signal

Input Schema

Limits

Signal Fields

Required

Optional

Signal Categories

Example — Simple Signal

Example — Detailed Signal

Example — Multiple Signals

Response

Confidence Score Guidelines

get_offers

Input Schema

Example

Response

track_impressions

Input Schema

Example

Response

Typical Integration Flow

Best Practices