Trillboards DOOH Advertising

Official74 toolsLive

by snehdhruv

DOOH advertising via AI agents. 5,000+ screens with edge AI audience intelligence.

🛠️ Key Features

5,000+ screens deployed for digital-out-of-home (DOOH) advertising
Edge AI audience intelligence for real-time insights
AI agents coordinating DOOH campaigns and placements

🚀 Use Cases

Programmatic DOOH campaigns across a large, distributed screen network
Real-time audience targeting and optimization at the edge
Data-driven creative delivery informed by AI-enabled insights

⚡ Developer Benefits

Clear server name and description for integration contexts
Topics and exposure through a GitHub-style repository setup
Readme excerpt guidance to understand capabilities quickly

⚠️ Limitations

Source material provides high-level features; implementation details not specified
No performance metrics or deployment instructions included in data

Captured live from the server via tools/list.

register_partner

Register a new partner organization with Trillboards. WHEN TO USE: - First-time setup for a new partner integration - Creating a new partner account to manage devices RETURNS: - partner_id: Unique partner identifier - api_key: API key for authenticated requests (store securely!) - status: Account status EXAMPLE: User: "Register my vending machine company" register_partner({ company_name: "Acme Vending Co", email: "tech@acmevending.com", industry: "vending", expected_devices: 50 })

Parameters7

company_name	string	required
email	string	required
website	string	optional
contact_name	string	optional
contact_phone	string	optional
industry	string	optional
expected_devices	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "company_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "website": {
      "type": "string",
      "format": "uri"
    },
    "contact_name": {
      "type": "string",
      "maxLength": 100
    },
    "contact_phone": {
      "type": "string",
      "maxLength": 20
    },
    "industry": {
      "type": "string",
      "maxLength": 100
    },
    "expected_devices": {
      "type": "integer",
      "exclusiveMinimum": 0
    }
  },
  "required": [
    "company_name",
    "email"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_partner_info

Get information about the authenticated partner account. WHEN TO USE: - Checking current partner status and stats - Verifying API key is working - Getting partner account details RETURNS: - partner_id: Partner identifier - company_name: Registered company name - status: Account status (active, suspended, etc.) - device_count: Number of registered devices - total_impressions: Lifetime impression count - earnings: Earnings summary EXAMPLE: User: "What's my partner account status?" get_partner_info({})

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

register_device

Register or update a device in the partner's network. WHEN TO USE: - Adding a new screen/kiosk/vending machine to the network - Updating device location or configuration - Re-registering a device after maintenance RETURNS: - device_id: Your internal device ID (echoed back) - trillboards_device_id: Internal Trillboards device ID - fingerprint: Device fingerprint (e.g., "P_abc123") - embed_url: URL to load in the device's WebView - status: Device status EXAMPLE: User: "Register a vending machine in NYC" register_device({ device_id: "vending-001-nyc", name: "NYC Office Lobby Vending", device_type: "vending_machine", location: { lat: 40.7128, lng: -74.0060, city: "New York", state: "NY", venue_type: "office" } })

Parameters6

device_id	string	required
name	string	optional
device_type	string	optional
location	object	optional
specs	object	optional
metadata	object	optional

Raw schema

{
  "type": "object",
  "properties": {
    "device_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "name": {
      "type": "string",
      "maxLength": 200
    },
    "device_type": {
      "type": "string",
      "enum": [
        "vending_machine",
        "kiosk",
        "tablet",
        "display",
        "digital_signage",
        "other"
      ]
    },
    "location": {
      "type": "object",
      "properties": {
        "lat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "lng": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "address": {
          "type": "string",
          "maxLength": 200
        },
        "city": {
          "type": "string",
          "maxLength": 100
        },
        "state": {
          "type": "string",
          "maxLength": 100
        },
        "country": {
          "type": "string",
          "maxLength": 100
        },
        "zip": {
          "type": "string",
          "maxLength": 20
        },
        "venue_type": {
          "type": "string",
          "maxLength": 100
        }
      },
      "additionalProperties": false
    },
    "specs": {
      "type": "object",
      "properties": {
        "screen_width": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "screen_height": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "orientation": {
          "type": "string",
          "enum": [
            "landscape",
            "portrait"
          ]
        },
        "os": {
          "type": "string",
          "maxLength": 100
        },
        "browser": {
          "type": "string",
          "maxLength": 100
        },
        "model": {
          "type": "string",
          "maxLength": 100
        }
      },
      "additionalProperties": false
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "device_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_devices

List all devices registered to the partner account. WHEN TO USE: - Getting an overview of all connected devices - Finding devices by status (online/offline) - Auditing the device fleet RETURNS: - devices: Array of device objects - total: Total device count - online_count: Number of online devices - offline_count: Number of offline devices EXAMPLE: User: "Show me all my online devices" list_devices({ status: "online", limit: 50 })

Parameters4

status	string	optional
device_type	string	optional
limit	integer	optional
offset	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "all",
        "online",
        "offline"
      ]
    },
    "device_type": {
      "type": "string",
      "enum": [
        "vending_machine",
        "kiosk",
        "tablet",
        "display",
        "digital_signage",
        "other"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "type": "integer",
      "minimum": 0
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_device

Get detailed information about a specific device. WHEN TO USE: - Checking status of a single device - Getting device configuration details - Debugging device issues RETURNS: - device_id: Your internal device ID - trillboards_device_id: Internal Trillboards ID - fingerprint: Device fingerprint - name: Device name - status: online/offline - last_seen: Last heartbeat timestamp - location: Location details - specs: Device specifications - stats: Impression and earnings stats EXAMPLE: User: "Get details for vending machine 001" get_device({ device_id: "vending-001-nyc" })

Parameters1

device_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "device_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    }
  },
  "required": [
    "device_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_device

Soft-delete a device from the partner account. WHEN TO USE: - Removing a device that's been decommissioned - Cleaning up test devices - Removing a device that's been relocated to another partner RETURNS: - success: Boolean indicating success - device_id: The deleted device ID - message: Confirmation message EXAMPLE: User: "Remove the old lobby kiosk" delete_device({ device_id: "lobby-kiosk-old" })

Parameters1

device_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "device_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    }
  },
  "required": [
    "device_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_device_ads

Get current ads scheduled for a device (for testing). WHEN TO USE: - Testing device ad delivery - Debugging which ads are being shown - Verifying ad targeting is working RETURNS: - ads: Array of advertisement objects - default_stream: Default content when no ads - schedule: Current ad schedule EXAMPLE: User: "What ads are showing on device P_abc123?" get_device_ads({ fingerprint: "P_abc123" })

Parameters1

fingerprint

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "fingerprint": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    }
  },
  "required": [
    "fingerprint"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

record_impression

Record a single ad impression from a device. WHEN TO USE: - Reporting that an ad was displayed on a device - Recording impression with detailed metadata - Single impression events (for batch, use batch_impressions) RETURNS: - success: Boolean indicating success - impression_id: Unique impression identifier - earnings: Earnings credited for this impression EXAMPLE: User: "Record an impression for ad 507f1f77bcf86cd799439011" record_impression({ fingerprint: "P_abc123", ad_id: "507f1f77bcf86cd799439011", duration_seconds: 15 })

Parameters5

fingerprint	string	required
ad_id	string	required
duration_seconds	number	optional
timestamp	string	optional
metadata	object	optional

Raw schema

{
  "type": "object",
  "properties": {
    "fingerprint": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "ad_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{24}$"
    },
    "duration_seconds": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 3600
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "fingerprint",
    "ad_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

batch_impressions

Record multiple impressions in a single request (up to 100). WHEN TO USE: - Bulk reporting impressions from offline period - Efficient batch processing of impressions - When device was offline and needs to sync RETURNS: - success: Boolean indicating success - processed: Number of impressions processed - failed: Number of failed impressions - total_earnings: Total earnings credited - errors: Any error details for failed impressions EXAMPLE: User: "Sync the last hour of impressions" batch_impressions({ impressions: [ { fingerprint: "P_abc123", ad_id: "507f1f77bcf86cd799439011", duration_seconds: 15 }, { fingerprint: "P_abc123", ad_id: "507f1f77bcf86cd799439012", duration_seconds: 10 } ] })

Parameters1

impressions

array

required

Raw schema

{
  "type": "object",
  "properties": {
    "impressions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fingerprint": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "ad_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{24}$"
          },
          "duration_seconds": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 3600
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "fingerprint",
          "ad_id"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 100
    }
  },
  "required": [
    "impressions"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

device_heartbeat

Send a heartbeat signal from a device to report its status. WHEN TO USE: - Regular device health monitoring (every 30-60 seconds) - Reporting current playback status - Reporting errors or issues RETURNS: - success: Boolean indicating success - device_status: Current device status in system - next_heartbeat_seconds: Recommended interval for next heartbeat EXAMPLE: User: "Send heartbeat for device P_abc123" device_heartbeat({ fingerprint: "P_abc123", status: "playing", current_ad_id: "507f1f77bcf86cd799439011", uptime_seconds: 3600 })

Parameters5

fingerprint	string	required
status	string	optional
current_ad_id	string	optional
uptime_seconds	integer	optional
error_message	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "fingerprint": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "status": {
      "type": "string",
      "enum": [
        "online",
        "playing",
        "idle",
        "error"
      ]
    },
    "current_ad_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{24}$"
    },
    "uptime_seconds": {
      "type": "integer",
      "minimum": 0
    },
    "error_message": {
      "type": "string",
      "maxLength": 500
    }
  },
  "required": [
    "fingerprint"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_analytics

Get analytics data for the partner account. WHEN TO USE: - Viewing overall performance metrics - Analyzing device performance - Generating reports on impressions and earnings - Comparing performance over time periods RETURNS: - summary: Overall stats (impressions, earnings, active_devices) - time_series: Data points over time - top_devices: Best performing devices - breakdown: Data grouped by requested dimension EXAMPLE: User: "Show me last week's analytics by device" get_analytics({ start_date: "2026-01-01", end_date: "2026-01-07", group_by: "device" }) User: "Get monthly performance breakdown" get_analytics({ start_date: "2025-12-01", end_date: "2025-12-31", group_by: "day" })

Parameters4

start_date	string	optional
end_date	string	optional
group_by	string	optional
device_id	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "group_by": {
      "type": "string",
      "enum": [
        "day",
        "week",
        "month",
        "device"
      ]
    },
    "device_id": {
      "type": "string",
      "maxLength": 100
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_webhook

Create a new webhook subscription for real-time events. WHEN TO USE: - Setting up real-time notifications for device events - Integrating with external systems - Monitoring ad playback and impressions AVAILABLE EVENTS: - device.online: When a device comes online - device.offline: When a device goes offline - impression.recorded: When an impression is logged - campaign.allocated: When a campaign is allocated to a device - payout.processed: When a payout is processed - programmatic.ad_started: When a programmatic ad begins playing - programmatic.ad_ended: When a programmatic ad finishes playing - programmatic.no_fill: When a programmatic ad request gets no fill - programmatic.error: When a programmatic ad request errors RETURNS: - webhook_id: Unique webhook identifier - url: The webhook endpoint URL - events: Subscribed events - secret: HMAC signing secret (if provided) - status: enabled/disabled EXAMPLE: User: "Set up a webhook for device status changes" create_webhook({ url: "https://api.mycompany.com/trillboards/webhooks", events: ["device.online", "device.offline", "programmatic.error"], secret: "my-signing-secret-123" })

Parameters4

url	string	required
events	array	required
secret	string	optional
description	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "device.online",
          "device.offline",
          "impression.recorded",
          "campaign.allocated",
          "payout.processed",
          "programmatic.ad_started",
          "programmatic.ad_ended",
          "programmatic.no_fill",
          "programmatic.error",
          "sensing.threshold_crossed",
          "audience.spike",
          "audience.venue_busy",
          "audience.purchase_intent",
          "audience.demographics_update",
          "venue.traffic_summary",
          "screen_group.created",
          "screen_group.updated",
          "screen_group.deleted",
          "screen_group.member.added",
          "screen_group.member.removed",
          "screen_group.content_policy.updated",
          "screen_group.sensing_config.updated",
          "fleet_command.completed",
          "fleet_command.failed"
        ]
      },
      "minItems": 1,
      "maxItems": 10
    },
    "secret": {
      "type": "string",
      "maxLength": 100
    },
    "description": {
      "type": "string",
      "maxLength": 500
    }
  },
  "required": [
    "url",
    "events"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_webhooks

List all webhook subscriptions for the partner account. WHEN TO USE: - Viewing all configured webhooks - Auditing webhook subscriptions - Finding a webhook to update or delete RETURNS: - webhooks: Array of webhook objects with: - webhook_id: Unique identifier - url: Endpoint URL - events: Subscribed events - enabled: Whether webhook is active - created_at: Creation timestamp - last_delivery: Last successful delivery time EXAMPLE: User: "Show me all my webhooks" list_webhooks({})

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

update_webhook

Update an existing webhook subscription. WHEN TO USE: - Changing the webhook endpoint URL - Adding or removing subscribed events - Enabling or disabling a webhook - Updating the webhook description RETURNS: - webhook_id: The updated webhook ID - url: Updated endpoint URL - events: Updated event subscriptions - enabled: Updated enabled status - updated_at: Update timestamp EXAMPLE: User: "Disable the webhook for maintenance" update_webhook({ webhook_id: "wh_mmmpdbvj_8b7c5a59296d", enabled: false }) User: "Add impression events to my webhook" update_webhook({ webhook_id: "wh_mmmpdbvj_8b7c5a59296d", events: ["device.online", "device.offline", "impression.recorded"] })

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

delete_webhook

Delete a webhook subscription. WHEN TO USE: - Removing a webhook that's no longer needed - Cleaning up old integrations - Removing test webhooks RETURNS: - success: Boolean indicating success - webhook_id: The deleted webhook ID - message: Confirmation message EXAMPLE: User: "Delete the old webhook" delete_webhook({ webhook_id: "wh_mmmpdbvj_8b7c5a59296d" })

Parameters1

webhook_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "pattern": "^(wh_[a-z0-9]+_[a-f0-9]+|[a-f0-9]{24})$"
    }
  },
  "required": [
    "webhook_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

test_webhook

Send a test event to a webhook endpoint. WHEN TO USE: - Verifying webhook endpoint is working - Testing integration during development - Debugging webhook delivery issues RETURNS: - success: Boolean indicating delivery success - response_code: HTTP response code from endpoint - response_time_ms: Response time in milliseconds - error: Error message if delivery failed EXAMPLE: User: "Test my webhook with a device.online event" test_webhook({ webhook_id: "wh_mmmpdbvj_8b7c5a59296d", event: "device.online" })

Parameters2

webhook_id	string	required
event	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "pattern": "^(wh_[a-z0-9]+_[a-f0-9]+|[a-f0-9]{24})$"
    },
    "event": {
      "type": "string",
      "enum": [
        "device.online",
        "device.offline",
        "impression.recorded",
        "campaign.allocated",
        "payout.processed",
        "programmatic.ad_started",
        "programmatic.ad_ended",
        "programmatic.no_fill",
        "programmatic.error",
        "sensing.threshold_crossed",
        "audience.spike",
        "audience.venue_busy",
        "audience.purchase_intent",
        "audience.demographics_update",
        "venue.traffic_summary",
        "screen_group.created",
        "screen_group.updated",
        "screen_group.deleted",
        "screen_group.member.added",
        "screen_group.member.removed",
        "screen_group.content_policy.updated",
        "screen_group.sensing_config.updated",
        "fleet_command.completed",
        "fleet_command.failed"
      ]
    }
  },
  "required": [
    "webhook_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_webhook_deliveries

Get delivery history for a webhook. WHEN TO USE: - Debugging failed webhook deliveries - Auditing webhook activity - Checking delivery success rates RETURNS: - deliveries: Array of delivery records with: - delivery_id: Unique delivery ID - event: Event type - status: success/failed - response_code: HTTP response code - response_time_ms: Response time - attempted_at: Attempt timestamp - error: Error message (if failed) - total: Total delivery count - success_rate: Percentage of successful deliveries EXAMPLE: User: "Show me failed deliveries for this webhook" get_webhook_deliveries({ webhook_id: "wh_mmmpdbvj_8b7c5a59296d", status: "failed", limit: 20 })

Parameters3

webhook_id	string	required
limit	integer	optional
status	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "pattern": "^(wh_[a-z0-9]+_[a-f0-9]+|[a-f0-9]{24})$"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "status": {
      "type": "string",
      "enum": [
        "all",
        "success",
        "failed"
      ]
    }
  },
  "required": [
    "webhook_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

discover_inventory

Discover available DOOH screens across the exchange network. WHEN TO USE: - Finding screens by venue type (retail, transit, office, etc.) - Finding screens in a specific city/state or within a radius - Finding screens with a specific audience profile (high income, professionals, etc.) - Getting an overview of available inventory with live audience data RETURNS: - screens: Array of screen objects with location, venue type, online status, and live audience data - total: Total matching screens - online_count: Number of currently online screens Each screen includes real-time audience data when available: - face_count, attention_score, income_level, mood, lifestyle - purchase_intent, crowd_density, ad_receptivity, dwell_time EXAMPLE: User: "Find retail screens in New York with high-income audience" discover_inventory({ venue_types: ["retail"], location: { city: "New York", state: "NY" }, audience_profile: { income: "high" }, limit: 20 })

Parameters4

venue_types	array	optional
location	object	optional
audience_profile	object	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "venue_types": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 50
      },
      "maxItems": 20
    },
    "location": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "maxLength": 100
        },
        "state": {
          "type": "string",
          "maxLength": 100
        },
        "lat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "lng": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "radius_km": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 500
        }
      },
      "additionalProperties": false
    },
    "audience_profile": {
      "type": "object",
      "properties": {
        "income": {
          "type": "string",
          "enum": [
            "high",
            "upper_mid",
            "mid",
            "lower_mid",
            "low"
          ]
        },
        "lifestyle": {
          "type": "string",
          "maxLength": 50
        },
        "min_attention": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      },
      "additionalProperties": false
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_live_audience

Get real-time audience data for a specific screen. WHEN TO USE: - Checking current audience at a screen before buying - Monitoring audience during a live campaign - Getting detailed audience signals (attention, mood, purchase intent, demographics) RETURNS real-time data from edge AI sensors (refreshed every 10 seconds): - face_count: Number of people currently viewing - attention_score: How attentively the audience is watching (0-1) - income_level: Estimated income bracket (from Gemini Vision) - mood: Current audience mood - lifestyle: Primary lifestyle segment - purchase_intent: Purchase intent level - crowd_density: Estimated venue occupancy - ad_receptivity: How receptive the audience is to ads (0-1) - emotional_engagement: Emotional engagement score (0-1) - group_composition: Solo/couples/families/friends/work groups - signals_age_ms: How fresh the data is in milliseconds EXAMPLE: User: "What's the current audience at screen 507f1f77bcf86cd799439011?" get_live_audience({ screen_id: "507f1f77bcf86cd799439011" })

Parameters1

screen_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "screen_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    }
  },
  "required": [
    "screen_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_audience_forecast

Predict what the audience will look like at a screen at a specific time. WHEN TO USE: - Planning campaigns for specific time slots - Estimating audience composition before buying - Comparing audience at different times of day Uses historical audience data to predict typical audience patterns. RETURNS: - predicted_face_count: Expected number of viewers - predicted_attention: Expected attention score - typical_income: Most common income level at that time - typical_lifestyle: Most common lifestyle segment at that time - confidence: Prediction confidence (0-1, based on sample count) - sample_count: Number of historical data points used EXAMPLE: User: "What's the typical audience at this screen on Monday at 3pm?" get_audience_forecast({ screen_id: "507f1f77bcf86cd799439011", hour: 15, day: 1, lookback_days: 30 })

Parameters4

screen_id	string	required
hour	integer	required
day	integer	required
lookback_days	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "screen_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "hour": {
      "type": "integer",
      "minimum": 0,
      "maximum": 23
    },
    "day": {
      "type": "integer",
      "minimum": 0,
      "maximum": 6
    },
    "lookback_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365
    }
  },
  "required": [
    "screen_id",
    "hour",
    "day"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_campaign

Create a new advertising campaign targeting DOOH screens. WHEN TO USE: - Setting up a new ad campaign on available screens - Targeting specific venues, locations, or audience profiles - Allocating budget for programmatic DOOH buys RETURNS: - campaign_id: Unique campaign identifier (UUID) - name, status, budget, screen_count, dates Campaign starts in "draft" status. Use update_campaign to set status to "active". EXAMPLE: User: "Create a campaign targeting retail screens in NYC at $5 CPM" create_campaign({ name: "NYC Retail Q1", budget_cpm: 5.0, daily_budget_usd: 100, venue_types: ["retail"], targeting: { geo: { city: "New York", state: "NY" } }, creative_url: "https://cdn.example.com/ad.mp4", start_date: "2026-03-01", end_date: "2026-03-31" })

Parameters12

name	string	required
budget_cpm	number	optional
daily_budget_usd	number	optional
total_budget_usd	number	optional
screen_ids	array	optional
venue_types	array	optional
targeting	object	optional
creative_url	string	optional
creative_type	string	optional
creative_duration	integer	optional
start_date	string	optional
end_date	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "budget_cpm": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000
    },
    "daily_budget_usd": {
      "type": "number",
      "minimum": 0,
      "maximum": 100000
    },
    "total_budget_usd": {
      "type": "number",
      "minimum": 0,
      "maximum": 10000000
    },
    "screen_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 50
      },
      "maxItems": 500
    },
    "venue_types": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 50
      },
      "maxItems": 20
    },
    "targeting": {
      "type": "object",
      "properties": {
        "geo": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "maxLength": 100
            },
            "state": {
              "type": "string",
              "maxLength": 100
            },
            "country": {
              "type": "string",
              "maxLength": 100
            },
            "lat": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            },
            "lng": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            },
            "radius_km": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 500
            }
          },
          "additionalProperties": false
        },
        "audience_profile": {
          "type": "object",
          "properties": {
            "income": {
              "type": "string"
            },
            "lifestyle": {
              "type": "string"
            },
            "min_attention": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          "additionalProperties": false
        },
        "schedule": {
          "type": "object",
          "properties": {
            "days": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": 0,
                "maximum": 6
              }
            },
            "hours": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": 0,
                "maximum": 23
              }
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "creative_url": {
      "type": "string",
      "format": "uri"
    },
    "creative_type": {
      "type": "string",
      "enum": [
        "video",
        "image",
        "vast"
      ]
    },
    "creative_duration": {
      "type": "integer",
      "minimum": 1,
      "maximum": 120
    },
    "start_date": {
      "type": "string"
    },
    "end_date": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_campaign_performance

Get detailed performance metrics for a campaign. WHEN TO USE: - Monitoring active campaign performance - Reviewing completed campaign results - Getting per-screen impression breakdowns RETURNS: - campaign_id, name, status, budget, dates - performance: impressions, spend_estimate_usd, avg_cpm, unique_screens, avg_latency_ms - screen_breakdown: per-screen impressions and CPM EXAMPLE: User: "How is my NYC retail campaign performing?" get_campaign_performance({ campaign_id: "550e8400-e29b-41d4-a716-446655440000" })

Parameters1

campaign_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_network_stats

Get network-wide statistics across all partner screens. WHEN TO USE: - Getting a high-level overview of network performance - Checking how many screens are online - Reviewing total impressions and revenue estimates RETURNS: - total_screens, online_screens - impressions, total_auctions - revenue_estimate_usd, avg_cpm, fill_rate EXAMPLE: User: "How is my network performing this week?" get_network_stats({ time_range: "7d" })

Parameters1

time_range

string

optional

Raw schema

{
  "type": "object",
  "properties": {
    "time_range": {
      "type": "string",
      "enum": [
        "today",
        "7d",
        "30d"
      ]
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_signals

[AdCP Signals] Get real-time audience signals from DOOH screens. This is an AdCP (Ad Context Protocol) compliant tool. It returns deterministic audience signals captured by edge AI (vision + audio + speech) on available screens. WHEN TO USE: - Discovering available audience signals before buying inventory - Evaluating audience composition at specific venues or locations - Building targeting segments based on real-time audience data Unlike probabilistic data, these signals are DETERMINISTIC — captured by on-device cameras and microphones, analyzed by ML Kit and Gemini Vision. RETURNS: - signals: Array of per-screen signal objects with demographics, venue, behavior, geo - metadata: total_screens, matching_screens, screens_with_live_data EXAMPLE: User: "What audience signals are available at retail locations?" get_signals({ signal_spec: { signal_types: ["demographics", "behavior"], filters: { venue_type: "retail" } } })

Parameters1

signal_spec

object

optional

Raw schema

{
  "type": "object",
  "properties": {
    "signal_spec": {
      "type": "object",
      "properties": {
        "signal_types": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "demographics",
              "venue",
              "geo",
              "behavior"
            ]
          }
        },
        "filters": {
          "type": "object",
          "properties": {
            "venue_type": {
              "type": "string",
              "maxLength": 50
            },
            "city": {
              "type": "string",
              "maxLength": 100
            },
            "state": {
              "type": "string",
              "maxLength": 100
            },
            "income": {
              "type": "string"
            },
            "lifestyle": {
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

activate_signal

[AdCP Signals] Activate an audience signal for DSP targeting. Generates IAB Audience Taxonomy 1.1 segment parameters that DSPs can use in bid requests. Returns an activation_key token for referencing this signal activation. WHEN TO USE: - Converting audience signals into actionable targeting parameters - Generating IAB segment IDs for programmatic bid requests - Creating reusable targeting configurations RETURNS: - activation_key: Token for referencing this activation (24h expiry) - targeting: { iab_segments, iab_taxonomy_version, custom_params } - screen_count, provider, data_source, methodology EXAMPLE: User: "Activate high-income professional targeting on my retail screens" activate_signal({ signal_type: "audience", parameters: { income: "high", lifestyle: "professional" }, screen_ids: ["507f1f77bcf86cd799439011"] })

Parameters4

signal_type	string	required
parameters	object	required
screen_ids	array	optional
destinations	array	optional

Raw schema

{
  "type": "object",
  "properties": {
    "signal_type": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "parameters": {
      "type": "object",
      "properties": {
        "income": {
          "type": "string",
          "enum": [
            "high",
            "upper_mid",
            "mid",
            "lower_mid",
            "low"
          ]
        },
        "lifestyle": {
          "type": "string"
        },
        "purchase_intent": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low"
          ]
        }
      },
      "additionalProperties": false
    },
    "screen_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 50
      },
      "maxItems": 500
    },
    "destinations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "dsp",
              "dmp",
              "data_clean_room"
            ]
          },
          "platform": {
            "type": "string"
          },
          "seat_id": {
            "type": "string"
          }
        },
        "additionalProperties": true
      }
    }
  },
  "required": [
    "signal_type",
    "parameters"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_adcp_capabilities

[AdCP] Get the seller agent's AdCP capabilities and supported protocols. Returns the full capability declaration for this AdCP DOOH seller agent. This tool does NOT require authentication. WHEN TO USE: - Discovering what protocols the seller agent supports (Signals, Media Buy) - Understanding available audience signals and data methodology - Getting MCP endpoint and discovery URLs RETURNS: - supported_protocols: ['signals', 'media_buy'] - inventory: DOOH format details, network size - audience_data: signal list, methodology, refresh rate - pricing: model, currency, floor CPM - discovery: well_known_url, mcp_endpoint

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_products

[AdCP Media Buy] Get available DOOH advertising products and packages. Returns DOOH screen packages organized by venue type, location, and audience profile, with real-time pricing based on current demand and audience quality. WHEN TO USE: - Browsing available inventory before creating a campaign - Comparing pricing across venue types and locations - Understanding what's available in a specific market RETURNS: - products: Array of product packages with pricing, reach, and audience data - Each product includes: name, venue_type, screen_count, pricing, avg_audience EXAMPLE: User: "What DOOH products are available in NYC?" get_products({ market: "New York", venue_types: ["retail", "transit"] })

Parameters6

buying_mode	string	optional
brief	string	optional
filters	object	optional
market	string	optional
venue_types	array	optional
audience_profile	object	optional

Raw schema

{
  "type": "object",
  "properties": {
    "buying_mode": {
      "type": "string",
      "enum": [
        "brief",
        "wholesale",
        "refine"
      ]
    },
    "brief": {
      "type": "string"
    },
    "filters": {
      "type": "object",
      "properties": {
        "channels": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "countries": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "venue_types": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 50
          },
          "maxItems": 20
        },
        "format_types": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "delivery_type": {
          "type": "string"
        },
        "budget_range": {
          "type": "object",
          "properties": {
            "min": {
              "type": "number"
            },
            "max": {
              "type": "number"
            },
            "currency": {
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": true
    },
    "market": {
      "type": "string",
      "maxLength": 100
    },
    "venue_types": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 50
      },
      "maxItems": 20
    },
    "audience_profile": {
      "type": "object",
      "properties": {
        "income": {
          "type": "string"
        },
        "lifestyle": {
          "type": "string"
        },
        "min_attention": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_media_buy

[AdCP Media Buy] Create a media buy (campaign) from an AdCP buy specification. Creates a campaign that targets DOOH screens based on the provided specification. Returns a media_buy_id for tracking and a creative_deadline for asset submission. WHEN TO USE: - Executing a programmatic DOOH buy via an AI agent - Creating campaigns from DSP trading desk agents - Automated media buying workflows RETURNS: - media_buy_id: Unique identifier for this media buy - campaign_id: Internal campaign identifier - creative_deadline: Deadline for creative asset submission - targeting_summary: What was targeted - budget_summary: Budget allocation details EXAMPLE: User: "Buy retail screens in NYC at $5 CPM for next week" create_media_buy({ name: "NYC Retail Week 12", buy_spec: { venue_types: ["retail"], geo: { city: "New York", state: "NY" }, budget: { daily_usd: 500, bid_cpm: 5.0 }, schedule: { start_date: "2026-03-16", end_date: "2026-03-22" } }, creative: { url: "https://cdn.example.com/creative.mp4", type: "video", duration_seconds: 15 }, buyer_ref: "agency-order-12345" })

Parameters8

name	string	required
packages	array	optional
brand	object	optional
start_time	string	optional
end_time	string	optional
buy_spec	object	optional
creative	object	optional
buyer_ref	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "packages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string"
          },
          "pricing_option_id": {
            "type": "string"
          },
          "budget": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "number"
              },
              "currency": {
                "type": "string"
              }
            },
            "additionalProperties": true
          },
          "targeting_overlay": {
            "type": "object",
            "additionalProperties": {}
          }
        },
        "additionalProperties": true
      }
    },
    "brand": {
      "type": "object",
      "properties": {
        "domain": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "start_time": {
      "type": "string"
    },
    "end_time": {
      "type": "string"
    },
    "buy_spec": {
      "type": "object",
      "properties": {
        "venue_types": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "screen_ids": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "geo": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "state": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "lat": {
              "type": "number"
            },
            "lng": {
              "type": "number"
            },
            "radius_km": {
              "type": "number"
            }
          },
          "additionalProperties": false
        },
        "audience_profile": {
          "type": "object",
          "additionalProperties": {}
        },
        "budget": {
          "type": "object",
          "properties": {
            "daily_usd": {
              "type": "number"
            },
            "total_usd": {
              "type": "number"
            },
            "bid_cpm": {
              "type": "number"
            }
          },
          "additionalProperties": false
        },
        "schedule": {
          "type": "object",
          "properties": {
            "start_date": {
              "type": "string"
            },
            "end_date": {
              "type": "string"
            },
            "days": {
              "type": "array",
              "items": {
                "type": "number"
              }
            },
            "hours": {
              "type": "array",
              "items": {
                "type": "number"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "creative": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "video",
            "image",
            "vast"
          ]
        },
        "duration_seconds": {
          "type": "number"
        }
      },
      "additionalProperties": false
    },
    "buyer_ref": {
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

update_media_buy

[AdCP Media Buy] Update an existing media buy (campaign). Modify budget, targeting, schedule, or status of an existing media buy. WHEN TO USE: - Adjusting campaign budget mid-flight - Pausing or resuming a campaign - Changing targeting parameters - Extending campaign dates EXAMPLE: update_media_buy({ media_buy_id: "mbuy_abc123", updates: { status: "paused", budget: { daily_usd: 300 } } })

Parameters2

media_buy_id	string	required
updates	object	required

Raw schema

{
  "type": "object",
  "properties": {
    "media_buy_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "updates": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "paused",
            "cancelled"
          ]
        },
        "budget": {
          "type": "object",
          "properties": {
            "daily_usd": {
              "type": "number"
            },
            "total_usd": {
              "type": "number"
            },
            "bid_cpm": {
              "type": "number"
            }
          },
          "additionalProperties": false
        },
        "targeting": {
          "type": "object",
          "additionalProperties": {}
        },
        "screen_ids": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "start_date": {
          "type": "string"
        },
        "end_date": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "media_buy_id",
    "updates"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

sync_creatives

[AdCP Media Buy] Validate and sync creative assets for a media buy. Validates creative assets (resolution, duration, format) against screen specifications. Returns compatibility status for each screen in the campaign. WHEN TO USE: - Submitting creative assets before campaign launch - Checking if a creative meets screen requirements - Validating VAST tags EXAMPLE: sync_creatives({ media_buy_id: "mbuy_abc123", creatives: [{ url: "https://cdn.example.com/ad.mp4", type: "video", width: 1920, height: 1080, duration_seconds: 15, file_size_mb: 12 }] })

Parameters2

media_buy_id	string	required
creatives	array	required

Raw schema

{
  "type": "object",
  "properties": {
    "media_buy_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "creatives": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "type": {
            "type": "string",
            "enum": [
              "video",
              "image",
              "vast"
            ]
          },
          "format_id": {
            "type": "string"
          },
          "width": {
            "type": "number"
          },
          "height": {
            "type": "number"
          },
          "duration_seconds": {
            "type": "number"
          },
          "file_size_mb": {
            "type": "number"
          }
        },
        "required": [
          "url",
          "type"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 10
    }
  },
  "required": [
    "media_buy_id",
    "creatives"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_media_buy_delivery

[AdCP Media Buy] Get delivery/performance report for a media buy. Returns campaign performance with breakdowns by screen, venue, hour, and audience segment. WHEN TO USE: - Monitoring campaign delivery in real-time - Getting performance breakdowns for optimization - Reporting on campaign results RETURNS: - delivery: impressions, spend, avg_cpm, unique_screens, fill_rate - breakdowns: by_screen, by_venue, by_hour (top performers) EXAMPLE: get_media_buy_delivery({ media_buy_id: "mbuy_abc123" })

Parameters3

media_buy_id	string	required
dimensions	array	optional
breakdown_by	array	optional

Raw schema

{
  "type": "object",
  "properties": {
    "media_buy_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "dimensions": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "screen",
          "venue",
          "hour",
          "audience_segment",
          "creative",
          "day"
        ]
      }
    },
    "breakdown_by": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "screen",
          "venue",
          "hour",
          "audience_segment"
        ]
      }
    }
  },
  "required": [
    "media_buy_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

provide_performance_feedback

[AdCP Media Buy] Provide optimization signals from buyer agent. Accepts feedback from buyer agents for floor price adjustment and inventory optimization. Enables closed-loop optimization between buyer and seller agents. WHEN TO USE: - Sending bid response feedback to optimize future pricing - Providing conversion data for bid price calibration - Adjusting floor prices based on demand signals EXAMPLE: provide_performance_feedback({ media_buy_id: "mbuy_abc123", feedback: { type: "bid_response", avg_bid_price_cpm: 6.5, fill_rate_percent: 72, preferred_hours: [8, 9, 10, 17, 18], quality_score: 0.85 } })

Parameters2

media_buy_id	string	required
feedback	object	required

Raw schema

{
  "type": "object",
  "properties": {
    "media_buy_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "feedback": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "bid_response",
            "conversion",
            "quality",
            "pacing"
          ]
        },
        "avg_bid_price_cpm": {
          "type": "number"
        },
        "fill_rate_percent": {
          "type": "number"
        },
        "preferred_hours": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 0,
            "maximum": 23
          }
        },
        "quality_score": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "media_buy_id",
    "feedback"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

log_event

[AdCP Media Buy] Record a conversion or attribution event. Records conversion events for post-campaign attribution analysis. Events are deduplicated by event_id + event_type combination. WHEN TO USE: - Recording offline conversions (store visits, purchases) - Tracking post-view attribution events - Logging custom KPI events EXAMPLE: log_event({ media_buy_id: "mbuy_abc123", event: { event_id: "conv_12345", event_type: "store_visit", value_cents: 5000, screen_id: "507f1f77bcf86cd799439011", metadata: { store: "NYC-001", dwell_minutes: 12 } } })

Parameters2

media_buy_id	string	required
event	object	required

Raw schema

{
  "type": "object",
  "properties": {
    "media_buy_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "event": {
      "type": "object",
      "properties": {
        "event_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "event_type": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "event_source": {
          "type": "string"
        },
        "value_cents": {
          "type": "number"
        },
        "screen_id": {
          "type": "string"
        },
        "timestamp": {
          "type": "string"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {}
        }
      },
      "required": [
        "event_id",
        "event_type"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "media_buy_id",
    "event"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_pricing

Get machine-readable pricing for all Trillboards products. Returns graduated usage-based pricing, free tier thresholds, and committed-use discount tiers. No authentication required — use this to evaluate costs before integrating.

Parameters1

product

string

optional

Raw schema

{
  "type": "object",
  "properties": {
    "product": {
      "type": "string",
      "enum": [
        "data_api",
        "proof_of_play",
        "attribution",
        "data_marketplace",
        "partner_platform",
        "programmatic",
        "fein_edge_ai"
      ]
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_usage_summary

Get your current billing period usage summary with per-product breakdown and costs. Shows free tier consumption, paid usage, and total cost.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

setup_billing

Set up pay-per-use billing with a Stripe payment method. Required after exceeding free tier limits. Pass a Stripe payment method token (pm_xxx) obtained from Stripe.js or Stripe Elements.

Parameters1

payment_method_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "payment_method_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "payment_method_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

purchase_credits

Purchase committed-use credits at a discount. Three tiers: tier_500 ($500 → $625 credit, 25% bonus), tier_2000 ($2,000 → $3,100 credit, 55% bonus), tier_5000 ($5,000 → $10,000 credit, 100% bonus). Requires an active payment method.

Parameters1

tier

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "tier": {
      "type": "string",
      "enum": [
        "tier_500",
        "tier_2000",
        "tier_5000"
      ]
    }
  },
  "required": [
    "tier"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_billing_status

Check current billing status including whether billing is set up, credit balance, Stripe customer ID, and payment method status. Use this to determine if billing setup is needed before making paid API calls.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_campaign_attribution

Get comprehensive attribution summary for a DOOH campaign. WHEN TO USE: - Measuring overall campaign effectiveness (reach, footfall, sales lift) - Getting a high-level view of campaign attribution metrics - Checking statistical significance of attribution results RETURNS: - reach: uniqueDevices, totalImpressions, avgFrequency - footfall: exposedVisitors, controlVisitors, incrementalLiftPct, incrementalVisits - cost: totalMediaCost, costPerUniqueReach, costPerIncrementalVisit - quality: avgMatchConfidence, statisticalSignificance, isSignificant - dataFreshness: latestOutcomeAt, provisionalCount, finalizedCount Returns null if no attribution data exists for the campaign.

Parameters1

campaign_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_attribution_timeseries

Get daily attribution timeseries for a campaign. WHEN TO USE: - Tracking attribution trends over time - Identifying which days had the strongest lift - Building attribution dashboards with daily granularity RETURNS: Array of daily data points, each with: - date, uniqueDevices, totalExposures, avgFrequency - exposedVisitors, controlVisitors, liftPct, incrementalVisits - costPerVisit, totalMediaCost, isSignificant EXAMPLE: get_attribution_timeseries({ campaign_id: "camp_abc123", start_date: "2026-03-01", end_date: "2026-03-10" })

Parameters3

campaign_id	string	required
start_date	string	optional
end_date	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_attention_metrics

Get edge AI attention metrics for a campaign (FEIN-powered). This is what makes DOOH attribution better than digital: Trillboards MEASURES viewability via FEIN edge AI instead of estimating it. WHEN TO USE: - Measuring actual human attention to ads (not just impressions) - Comparing attention-adjusted CPM (aCPM) vs standard CPM - Getting face count, dwell time, and emotion engagement data RETURNS: - impressions: total, uniqueDevices - attention: avgScore (0-1), medianScore, p90Score, avgDwellSeconds, avgFaceCount, qualifiedPct - economics: standardCpm, attentionCpm (aCPM), costPerAttentiveReach - emotion: avgEngagement (0-1), positiveEmotionPct aCPM = total_media_cost / (SUM(attention_score * face_count) / 1000)

Parameters1

campaign_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_creative_attention

Get per-creative attention breakdown for a campaign. WHEN TO USE: - A/B testing creative variants by attention score - Identifying which creative drives the most engagement - Comparing aCPM across creative assets RETURNS: Array of creatives ranked by attention score, each with: - creativeId, totalImpressions, uniqueDevices - avgAttentionScore (0-1), avgDwellSeconds, avgFaceCount - attentionCpm, avgEmotionEngagement, positiveEmotionPct, attentionQualifiedPct

Parameters1

campaign_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_multi_touch_attribution

Get multi-touch attribution model results for a campaign. Supported models: time_decay, position_based, attention_weighted. WHEN TO USE: - Understanding how DOOH fits into the full marketing funnel - Seeing credit allocation across DOOH, mobile, web, and store channels - Quantifying DOOH's contribution to conversions RETURNS: - totalChains: number of multi-touch journeys found - avgTouchpoints: average touchpoints per chain - channelAttribution: { dooh, mobile, web, store } (each 0-1, sums to 1) - conversions: total conversion events - totalConversionValue: sum of conversion values (cents) - avgConfidence: average match confidence across chains Returns null if no multi-touch chains exist.

Parameters1

campaign_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_cross_channel_journey

Get cross-channel customer journey data (Sankey flow) for a campaign. Shows how users flow between channels: DOOH -> mobile -> web -> store. WHEN TO USE: - Visualizing the customer journey across DOOH and digital channels - Understanding channel transition patterns - Building Sankey diagrams of marketing funnels RETURNS: - flows: Array of { source, target, count } transitions between channels - channels: Array of { channel, touchpoints, uniqueDevices } distribution

Parameters1

campaign_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_incrementality

Get incrementality/lift test results for a campaign. Uses Bayesian (Beta-Binomial with 10K Monte Carlo samples) and frequentist (chi-square with Yates correction) methods for causal measurement. WHEN TO USE: - Proving causal DOOH advertising effectiveness - Getting both Bayesian and frequentist significance measures - Seeing treatment vs control group visit rates and lift RETURNS: Array of experiments, each with: - experimentId, type (geo_holdout/ghost_ads/psm), status - treatmentDmas, controlDmas - latestResult: treatment/control rates, lift%, incrementalVisits, pValue, posteriorProbPositive, expectedUplift, credibleInterval Returns empty array if no experiments exist for this campaign.

Parameters1

campaign_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_experiment

Create an incrementality experiment for a campaign. Sets up a geo-holdout, ghost ads, or propensity score matching experiment to causally measure DOOH advertising lift. WHEN TO USE: - Setting up a new A/B test before or during a campaign - Defining treatment and control DMAs for geo-holdout tests - Configuring experiment parameters (holdout %, MDE, power) RETURNS: The created experiment object with experiment_id, status, and all parameters. EXAMPLE: create_experiment({ campaign_id: "camp_abc123", experiment_type: "geo_holdout", treatment_dmas: ["501", "504"], control_dmas: ["503", "505"], holdout_pct: 0.15, target_mde: 0.10 })

Parameters8

campaign_id	string	required
experiment_type	string	required
treatment_dmas	array	optional
control_dmas	array	optional
holdout_pct	number	optional
target_mde	number	optional
target_power	number	optional
target_alpha	number	optional

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "experiment_type": {
      "type": "string",
      "enum": [
        "geo_holdout",
        "ghost_ads",
        "psm"
      ]
    },
    "treatment_dmas": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 20
      },
      "maxItems": 200
    },
    "control_dmas": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 20
      },
      "maxItems": 200
    },
    "holdout_pct": {
      "type": "number",
      "minimum": 0.05,
      "maximum": 0.5
    },
    "target_mde": {
      "type": "number",
      "minimum": 0.01,
      "maximum": 1
    },
    "target_power": {
      "type": "number",
      "minimum": 0.5,
      "maximum": 0.99
    },
    "target_alpha": {
      "type": "number",
      "minimum": 0.001,
      "maximum": 0.1
    }
  },
  "required": [
    "campaign_id",
    "experiment_type"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_creative_attribution

Get attribution performance by individual creative variant. Links creative execution to attribution outcomes: which creative variant drove the most store visits? WHEN TO USE: - Comparing creative A/B/C test performance on attribution outcomes - Finding the optimal creative x venue_type x daypart x weather combination - Identifying the creative with the highest visit rate RETURNS: Array of creatives ranked by store visits, each with: - creativeId, variant, totalVisits, avgVisitRate - attention: avgScore, avgDwell, avgEmotion, dominantEmotion - avgLiftPct, avgCostPerVisit - bestContext: { venueType, daypart, weather } - dateRange: { first, last, daysMeasured }

Parameters1

campaign_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_roas

Get Return on Ad Spend (ROAS) with transaction attribution data. Closes the ROAS loop: matches purchase events to DOOH exposures with time-decay weighting, and computes attributed revenue and incremental ROAS. WHEN TO USE: - Measuring revenue directly attributable to DOOH advertising - Getting ROAS and incremental ROAS (iROAS) figures - Seeing sales lift between exposed and control groups RETURNS: - transactions: total, uniquePurchasers, totalRevenueCents, avgBasketCents - attribution: attributedTransactions, attributedRevenueCents, totalMediaCostCents, roas, iroas - salesLift: exposedPurchasers, controlPurchasers, incrementalTransactions, incrementalRevenueCents, salesLiftPct, posteriorProbPositive - timing: avgHoursToPurchase, medianHoursToPurchase Returns null if no transaction data exists.

Parameters1

campaign_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

export_cohort

Export exposed audience cohort to a DSP for retargeting. Pushes MAID hashes from the campaign's exposed cohort to the specified DSP (The Trade Desk, DV360, or Meta). Creates or reuses a DSP segment. WHEN TO USE: - Activating DOOH-exposed audiences for retargeting on digital channels - Pushing cohorts to TTD, DV360, or Meta Custom Audiences - Measuring cross-channel retargeting lift RETURNS: - status: 'synced', 'no_cohort', 'credentials_missing', or 'empty_cohort' - destination: the DSP name - segmentId: internal segment ID - externalSegmentId: DSP-side segment ID - maidCount: number of MAIDs uploaded - accepted: number accepted by DSP Supported destinations: ttd, dv360, meta, cadent, mediaocean EXAMPLE: export_cohort({ campaign_id: "camp_abc123", destination: "ttd" })

Parameters2

campaign_id	string	required
destination	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "destination": {
      "type": "string",
      "enum": [
        "ttd",
        "dv360",
        "meta",
        "cadent",
        "mediaocean"
      ]
    }
  },
  "required": [
    "campaign_id",
    "destination"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_audience_lookalike

Find screens with similar audience profiles using pgvector similarity. Uses 64-dimensional audience vectors with HNSW cosine similarity index to find screens whose audience demographics, attention, and behavioral patterns match a target screen. WHEN TO USE: - Expanding campaign reach to screens with similar audiences - Finding new inventory that matches a high-performing screen - Building lookalike audience segments for targeting RETURNS: Array of similar screens ranked by cosine similarity, each with: - screen_id, similarity (0-1), metadata (face_count, attention, income, lifestyle), last_seen EXAMPLE: get_audience_lookalike({ screen_id: "scr_abc123", limit: 10, min_similarity: 0.8 })

Parameters5

screen_id	string	required
limit	integer	optional
min_similarity	number	optional
country	string	optional
venue_type	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "screen_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "min_similarity": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "country": {
      "type": "string",
      "maxLength": 100
    },
    "venue_type": {
      "type": "string",
      "maxLength": 100
    }
  },
  "required": [
    "screen_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

semantic_audience_search

Search screens by natural language scene description using pgvector. Uses 768-dimensional Gemini embeddings on scene descriptions from FEIN edge AI to find screens matching a natural language query. WHEN TO USE: - Finding screens by audience context ("families eating lunch in a food court") - Contextual ad placement based on real-time scene understanding - Discovering inventory matching a specific audience scenario RETURNS: Array of matching screens ranked by semantic similarity, each with: - screen_id, mongo_screen_id, scene_description, contextual_relevance, similarity, created_at EXAMPLE: semantic_audience_search({ query: "young professionals in a coffee shop looking at phones", limit: 10 })

Parameters4

query	string	required
limit	integer	optional
since	string	optional
min_similarity	number	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "since": {
      "type": "string",
      "pattern": "^\\d+[hd]$"
    },
    "min_similarity": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_campaign_heatmap

Get geographic exposure heatmap data for a campaign. Returns lat/lng clusters with exposure counts and device reach, useful for visualizing where ads were shown on a map. WHEN TO USE: - Visualizing campaign geographic coverage - Identifying hotspots of ad exposure - Analyzing geographic distribution of attributed foot traffic RETURNS: Array of geographic clusters (max 500), each with: - lat, lng (rounded to 3 decimal places) - uniqueDevices, totalExposures - avgConfidence (match confidence score)

Parameters1

campaign_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "campaign_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

verify_proof_of_play

Verify cryptographic proof of ad delivery or get campaign proofs. Requires either campaign_id or proof_payload (at least one must be provided). Two modes: 1. Verify a proof: pass proof_payload with signature fields to verify 2. Get proofs: pass campaign_id to get Ed25519-signed proofs for a campaign Uses Ed25519 signatures (v2) that can be independently verified by third parties using the Trillboards public key. WHEN TO USE: - Verifying that ads were actually delivered to screens - Exporting cryptographically signed proof records for auditors - Getting proof-of-play data for campaign transparency reports RETURNS (verify mode): - valid: boolean, reason: string if invalid, version: 'v1' or 'v2' RETURNS (get proofs mode): - campaignId, totalImpressions, proofsReturned - proofs: Array of signed impression proofs - pagination: { limit, hasMore, nextCursor } - signatureVersion, publicKeyUrl EXAMPLE (verify): verify_proof_of_play({ proof_payload: { signature: "ed25519=abc123...", timestamp: "2026-03-10T15:30:00Z", adId: "ad_123", impressionId: "imp_456", screenId: "scr_789", deviceId: "dev_012" } }) EXAMPLE (get proofs): verify_proof_of_play({ campaign_id: "camp_abc123", start_date: "2026-03-01", end_date: "2026-03-10" })

Parameters6

campaign_id	string	optional
proof_payload	object	optional
start_date	string	optional
end_date	string	optional
limit	integer	optional
cursor	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "maxLength": 128
    },
    "proof_payload": {
      "type": "object",
      "properties": {
        "signature": {
          "type": "string"
        },
        "signatureVersion": {
          "type": "string"
        },
        "timestamp": {
          "type": "string"
        },
        "adId": {
          "type": "string"
        },
        "impressionId": {
          "type": "string"
        },
        "screenId": {
          "type": "string"
        },
        "deviceId": {
          "type": "string"
        }
      },
      "required": [
        "signature",
        "timestamp"
      ],
      "additionalProperties": false
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "end_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    },
    "cursor": {
      "type": "string",
      "maxLength": 200
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

query_observations

Query the universal observation stream using natural language or structured filters. Returns multi-modal sensing data (audience, vehicle, environment, commerce) from physical-world observations across the screen network. WHEN TO USE: - Exploring raw observation data from edge AI sensors on screens - Filtering observations by venue type, device, time range, or geography - Getting audience, vehicle, environment, or commerce observation data - Answering natural language questions about what screens are sensing RETURNS: - data: Array of observation objects with device, venue, payload, confidence, model versions - metadata: { observation_count, time_range, coverage_pct, model_versions } - suggested_next_queries: Contextual follow-up queries Each observation includes: - observation_id, device_id, screen_mongo_id, venue_type - observed_at: Timestamp of the observation - observation_family: audience | vehicle | environment | commerce - payload: JSONB with model outputs (face_count, emotion, vehicle_count, etc.) - confidence: Model confidence score (0-1) - evidence_grade: Quality grade of the observation - model_versions: Which ML models produced this data EXAMPLE: User: "Show me audience observations at QSR venues in the last hour" query_observations({ query: "audience observations at QSR venues", filters: { observation_family: ["audience"], venue_type: ["restaurant_qsr"], time_range: { start: "2026-03-16T14:00:00Z", end: "2026-03-16T15:00:00Z" } }, limit: 50 }) User: "What are screens sensing right now?" query_observations({ query: "latest observations from all screens", limit: 20 })

Parameters3

query	string	required
filters	object	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "filters": {
      "type": "object",
      "properties": {
        "observation_family": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 50
          },
          "maxItems": 10
        },
        "venue_type": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 50
          },
          "maxItems": 20
        },
        "device_id": {
          "type": "string",
          "maxLength": 100
        },
        "screen_id": {
          "type": "string",
          "maxLength": 100
        },
        "time_range": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "geohash": {
          "type": "string",
          "maxLength": 12
        }
      },
      "additionalProperties": false
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

semantic_search_observations

Search observations by semantic similarity. Find moments that match a description like "lunch rush at fast casual restaurants" using vector embeddings. Uses 768-dimensional Gemini embeddings on observation payloads to find promoted observations matching a natural language query via pgvector cosine similarity search. WHEN TO USE: - Finding observations that match a conceptual description - Discovering contextual moments across the screen network - Searching for audience situations ("families waiting in line", "professionals on coffee break") - Finding commerce patterns ("high purchase intent near checkout") RETURNS: - data: Array of matching observations ranked by semantic similarity, each with: - observation_id, device_id, venue_type, observation_family - observed_at, payload, confidence, evidence_grade - similarity: Cosine similarity score (0-1, higher = more relevant) - metadata: { result_count, query_embedding_model, search_scope } - suggested_next_queries: Related semantic queries to explore EXAMPLE: User: "Find lunch rush moments at fast casual restaurants" semantic_search_observations({ query: "lunch rush at fast casual restaurants with high foot traffic", filters: { venue_type: ["restaurant_qsr"] }, limit: 20 }) User: "Find moments with high emotional engagement" semantic_search_observations({ query: "audience showing strong positive emotional reactions", filters: { observation_family: ["audience"] }, limit: 10 })

Parameters3

query	string	required
filters	object	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "filters": {
      "type": "object",
      "properties": {
        "venue_type": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 50
          },
          "maxItems": 20
        },
        "observation_family": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 50
          },
          "maxItems": 10
        },
        "time_range": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

anomaly_detect

Detect anomalies in observation patterns. Alert when metrics deviate significantly from trailing averages. Computes trailing mean and standard deviation for a given metric from the observation_stream, then identifies observations that fall beyond the configured sigma threshold (z-score based anomaly detection). WHEN TO USE: - Monitoring for unusual audience patterns (sudden spikes or drops in face count) - Detecting equipment anomalies (confidence drops indicating sensor issues) - Identifying unusual commerce or vehicle patterns - Finding outlier moments that may indicate events, incidents, or opportunities RETURNS: - anomalies: Array of anomalous observations with: - observation_id, device_id, venue_type, observed_at - metric_value: The observed value - z_score: How many standard deviations from the mean - direction: 'above' or 'below' the mean - payload: Full observation payload for context - baseline: { mean, stddev, sample_count, lookback_hours } - suggested_next_queries: Follow-up queries to investigate anomalies EXAMPLE: User: "Are there any unusual audience patterns at retail venues?" anomaly_detect({ metric: "face_count", venue_type: "retail", lookback_hours: 24, threshold_sigma: 2.0 }) User: "Detect anomalies in vehicle counts at this screen" anomaly_detect({ metric: "vehicle_count", screen_id: "507f1f77bcf86cd799439011", lookback_hours: 48, threshold_sigma: 2.5 })

Parameters5

metric	string	required
screen_id	string	optional
venue_type	string	optional
lookback_hours	number	optional
threshold_sigma	number	optional

Raw schema

{
  "type": "object",
  "properties": {
    "metric": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "screen_id": {
      "type": "string",
      "maxLength": 100
    },
    "venue_type": {
      "type": "string",
      "maxLength": 100
    },
    "lookback_hours": {
      "type": "number",
      "minimum": 1,
      "maximum": 168
    },
    "threshold_sigma": {
      "type": "number",
      "minimum": 1,
      "maximum": 5
    }
  },
  "required": [
    "metric"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

cross_signal_correlate

Discover correlations between different signal types. Example: relationship between ad fill rate and audience attention for QSR venues. Queries the cross_signal_insights table for pre-computed correlations, or computes ad-hoc correlations from the observation_stream when no pre-computed insight exists. WHEN TO USE: - Understanding relationships between different sensing signals - Finding which audience behaviors correlate with business outcomes - Discovering hidden patterns (e.g., crowd_energy vs purchase_intent) - Validating hypotheses about audience-venue-time relationships RETURNS: - data: Correlation analysis with: - signal_a, signal_b: The two signals being correlated - correlation_r: Pearson correlation coefficient (-1 to +1) - correlation_r2: R-squared (proportion of variance explained) - p_value: Statistical significance - sample_count: Number of data points used - effect_size: Cohen's d effect size - confidence_interval_lower, confidence_interval_upper: 95% CI bounds - insight_summary: Human-readable interpretation - metadata: { computation_method, window, filters_applied } - suggested_next_queries: Related correlation analyses to explore EXAMPLE: User: "Is there a correlation between audience attention and ad fill rate at QSR venues?" cross_signal_correlate({ signal_a: "attention_score", signal_b: "ad_fill_rate", filters: { venue_type: "restaurant_qsr" } }) User: "How does crowd energy relate to purchase intent during lunch hours?" cross_signal_correlate({ signal_a: "crowd_energy", signal_b: "purchase_intent", filters: { daypart: "lunch" } })

Parameters3

signal_a	string	required
signal_b	string	required
filters	object	optional

Raw schema

{
  "type": "object",
  "properties": {
    "signal_a": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "signal_b": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "filters": {
      "type": "object",
      "properties": {
        "venue_type": {
          "type": "string",
          "maxLength": 100
        },
        "daypart": {
          "type": "string",
          "enum": [
            "morning",
            "lunch",
            "afternoon",
            "evening",
            "night"
          ]
        },
        "dma_code": {
          "type": "string",
          "maxLength": 20
        },
        "time_range": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "signal_a",
    "signal_b"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

configure_sensing

Configure what a screen should sense using natural language. Generates and optionally pushes a sensing profile to the device. Uses Gemini AI to interpret a natural language sensing intent and generate a sensing profile that maps to available on-device ML models (BlazeFace, AgeGender, FER+, MoveNet, YAMNet, WhisperTiny, EfficientDet, YOLOv8-nano). WHEN TO USE: - Setting up a new screen to sense specific things (faces, vehicles, emotions, etc.) - Changing what a screen detects based on venue type or business needs - Configuring custom sensing for special events or campaigns - Translating business intent into ML model configuration RETURNS: - data: The generated sensing profile with: - profile_name, profile_type, description - models: Array of ML model IDs to activate - classes: COCO classes to detect (for object detection models) - thresholds: Confidence and alert thresholds - observation_families: What types of observations will be produced - capture_interval_ms, report_interval_ms: Timing configuration - estimated_fps_impact: CPU cost estimate - data_fields_produced: All data fields the profile will generate - reasoning: Why these models/classes were chosen - deployment_status: 'generated' | 'pushed' | 'push_failed' - metadata: { screen_id, auto_deploy, profile_id } - suggested_next_queries: Follow-up actions EXAMPLE: User: "Set up the lobby screen to detect foot traffic and emotions" configure_sensing({ screen_id: "507f1f77bcf86cd799439011", intent: "Detect foot traffic patterns, count people, and measure emotional reactions to displayed content", auto_deploy: false }) User: "Configure this drive-through screen for vehicle counting" configure_sensing({ screen_id: "507f1f77bcf86cd799439011", intent: "Count vehicles in drive-through lane, detect vehicle types, measure queue length", auto_deploy: true })

Parameters3

screen_id	string	required
intent	string	required
auto_deploy	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "screen_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "intent": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000
    },
    "auto_deploy": {
      "type": "boolean"
    }
  },
  "required": [
    "screen_id",
    "intent"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

export_dataset

Export observation data as a structured dataset. Supports filtering by time, geography, venue type, and observation family. Applies k-anonymity (k=5) to protect individual privacy. Queries the relevant table based on the selected dataset type, applies filters, enforces k-anonymity by suppressing groups with fewer than 5 observations, and returns structured data. WHEN TO USE: - Exporting audience data for external analysis - Building datasets for machine learning or reporting - Getting structured vehicle or commerce data for a specific time/place - Creating cross-signal datasets for correlation analysis RETURNS: - data: Array of dataset rows (schema varies by dataset type) - metadata: { row_count, k_anonymity_applied, export_id, dataset, filters_applied, time_range } - suggested_next_queries: Related exports or analyses Dataset types: - observations: Raw observation stream data (all families) - audience: Audience-specific data (face_count, demographics, attention, emotion) - vehicle: Vehicle counting and classification data - cross_signal: Pre-computed cross-signal correlation insights EXAMPLE: User: "Export audience data from retail venues last week" export_dataset({ dataset: "audience", filters: { time_range: { start: "2026-03-09", end: "2026-03-16" }, venue_type: ["retail"] }, format: "json" }) User: "Get vehicle data near geohash 9q8yy" export_dataset({ dataset: "vehicle", filters: { time_range: { start: "2026-03-15", end: "2026-03-16" }, geo: "9q8yy" } })

Parameters3

dataset	string	required
filters	object	required
format	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "dataset": {
      "type": "string",
      "enum": [
        "observations",
        "audience",
        "vehicle",
        "cross_signal"
      ]
    },
    "filters": {
      "type": "object",
      "properties": {
        "time_range": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "venue_type": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 50
          },
          "maxItems": 20
        },
        "geo": {
          "type": "string",
          "maxLength": 12
        },
        "observation_family": {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 50
          },
          "maxItems": 10
        }
      },
      "additionalProperties": false
    },
    "format": {
      "type": "string",
      "enum": [
        "json"
      ]
    }
  },
  "required": [
    "dataset",
    "filters"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

predictive_query

Generate predictive insights from observation patterns. Predict whether a venue is likely to see increased foot traffic based on current patterns. Uses historical observation_stream data to compute trend analysis via linear regression on time-bucketed metrics. Generates predictions with confidence intervals based on the observed trend, variance, and sample size. WHEN TO USE: - Predicting future audience patterns at a venue or screen - Forecasting foot traffic trends for campaign planning - Understanding whether metrics are trending up, down, or stable - Making data-driven decisions about inventory and pricing RETURNS: - prediction: The predicted trend and expected values - trend: 'increasing' | 'decreasing' | 'stable' - current_avg: Current average metric value - predicted_avg: Predicted average over the time horizon - change_pct: Expected percentage change - confidence_interval: { lower, upper } bounds - confidence: Overall prediction confidence (0-1) - supporting_data: Recent data points that inform the prediction - data_points: Array of { bucket, avg_value, sample_count } - total_observations: Total observations analyzed - methodology: Description of the prediction approach - suggested_next_queries: Follow-up queries to refine the prediction EXAMPLE: User: "Will this QSR venue see more foot traffic next week?" predictive_query({ question: "Will foot traffic increase at QSR venues?", venue_type: "restaurant_qsr", time_horizon: "7d" }) User: "Predict audience attention trends for this screen" predictive_query({ question: "What will audience attention look like?", screen_id: "507f1f77bcf86cd799439011", time_horizon: "3d" })

Parameters4

question	string	required
venue_type	string	optional
screen_id	string	optional
time_horizon	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "venue_type": {
      "type": "string",
      "maxLength": 100
    },
    "screen_id": {
      "type": "string",
      "maxLength": 100
    },
    "time_horizon": {
      "type": "string",
      "pattern": "^\\d+d$"
    }
  },
  "required": [
    "question"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_social_attention

Query social attention contagion metrics from the observation stream. Returns windows where attention propagated between viewers (social amplification factor > 1). Social attention data is produced by the AttentionGraphBuilder running on CTV edge devices, which models viewer attention as a directed graph and detects when one viewer looking at the screen triggers nearby viewers to also look (attention contagion / social amplification). WHEN TO USE: - Finding moments where social proof drove collective engagement - Identifying which venues or dayparts exhibit highest attention contagion - Understanding cascading attention patterns (cascade depth) - Correlating social amplification with ad effectiveness (VAS) RETURNS: - data: Array of observation_stream rows with socialAttention payload - payload.socialAttention.socialAmplificationFactor (SAF): ratio of actual-to-expected group attention (>1 = contagion detected) - payload.socialAttention.cascadeDepth: max depth of attention propagation chain - payload.socialAttention.viralAttentionScore: composite metric combining SAF and cascade depth - payload.socialAttention.contagionWindowMs: time window over which cascade occurred - payload.socialAttention.triggerViewerIndex: which viewer initiated the cascade - metadata: { result_count, time_range, min_saf_filter } - suggested_next_queries: Follow-up queries EXAMPLE: User: "Show me moments where attention went viral in bar venues" get_social_attention({ min_saf: 2.0, venue_type: "bar" }) User: "Find the strongest social amplification events this week" get_social_attention({ min_saf: 3.0, time_range: { start: "2026-03-09T00:00:00Z", end: "2026-03-16T00:00:00Z" } })

Parameters5

screen_id	string	optional
min_saf	number	optional
venue_type	string	optional
time_range	object	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "screen_id": {
      "type": "string",
      "maxLength": 100
    },
    "min_saf": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "venue_type": {
      "type": "string",
      "maxLength": 100
    },
    "time_range": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string"
        },
        "end": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

find_similar_moments

Find historically similar audience moments across the screen network using embedding similarity search. Input a natural-language description of the target moment. Moment embeddings are 768-D vectors generated from multi-modal observation data (visual, audio, environmental, social) via the MomentEmbeddingService. This tool embeds your query text and finds the closest real-world moments via pgvector cosine similarity. WHEN TO USE: - Searching for historical moments similar to a target scenario - Finding "moments like this one" across different venues/times - Discovering when similar audience compositions or behaviors occurred - Planning ad placements based on past similar contexts RETURNS: - data: Array of matching observations with similarity scores - observation_id, observed_at, venue_type, device_id, screen_mongo_id - payload: full observation data - evidence_grade: quality of observation - similarity: cosine similarity score (0-1, higher = more similar) - metadata: { result_count, embedding_model, min_similarity_threshold } - suggested_next_queries: Follow-up queries EXAMPLE: User: "Find moments with high engagement in evening restaurants with families" find_similar_moments({ query: "evening restaurant venue with families present, high emotional engagement and attention" }) User: "When did we see young adults highly engaged at transit screens?" find_similar_moments({ query: "transit venue morning commute young adults high attention" })

Parameters4

query	string	required
venue_type	string	optional
limit	integer	optional
min_similarity	number	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000
    },
    "venue_type": {
      "type": "string",
      "maxLength": 100
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "min_similarity": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

predict_moment_quality

Predict the VAS (Viewability Attention Score) a specific creative would achieve at a given moment, based on historical data and causal modeling. Uses the CausalPredictionService which: 1. Embeds the moment description to find historically similar moments 2. If >= 5 similar moments exist with the same creative, uses weighted-average prediction 3. If insufficient data, falls back to Gemini generative prediction 4. Always decomposes the prediction into causal factors WHEN TO USE: - Evaluating whether a creative will perform well in a specific context - A/B testing creative placement hypotheses before committing budget - Understanding which causal factors drive VAS for a creative - Comparing expected performance across different moment types RETURNS: - prediction: { predictedVAS (0-1), confidence (0-1), method ('historical'|'model'), sampleSize } - causal_factors: { audienceMatch, contextMatch, attentionState, socialPotential } (each 0-1) - metadata: { creative_id, moment_description } - suggested_next_queries: Follow-up queries EXAMPLE: User: "How would a coffee ad perform at a transit station during morning rush?" predict_moment_quality({ moment_description: "transit venue, morning commute, 12 viewers, high attention, mostly 25-34 age range", creative_id: "coffee-brand-morning-30s" })

Parameters2

moment_description	string	required
creative_id	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "moment_description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000
    },
    "creative_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "moment_description",
    "creative_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

recommend_creative

Given a moment description, rank candidate creatives by predicted VAS performance. Evaluates each creative candidate against the described moment context using historical similarity and causal prediction. Returns a ranked list sorted by predicted VAS score, with confidence levels for each prediction. WHEN TO USE: - Choosing which creative to show at a specific moment/venue - Comparing multiple creatives for a campaign across different contexts - Optimizing creative rotation for maximum VAS - Pre-campaign creative selection based on audience and venue RETURNS: - rankings: Array sorted by predicted VAS (descending) - creativeId, predictedVAS (0-1), confidence (0-1), rank (1-N) - metadata: { candidate_count, moment_description } - suggested_next_queries: Follow-up queries EXAMPLE: User: "Which of these 3 creatives will perform best at a gym in the evening?" recommend_creative({ moment_description: "gym venue, evening, 6 viewers, high attention, mostly male 18-34", creative_ids: ["fitness-brand-30s", "energy-drink-15s", "tech-gadget-20s"] })

Parameters2

moment_description	string	required
creative_ids	array	required

Raw schema

{
  "type": "object",
  "properties": {
    "moment_description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000
    },
    "creative_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "minItems": 1,
      "maxItems": 20
    }
  },
  "required": [
    "moment_description",
    "creative_ids"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_social_contagion_summary

Aggregate social attention metrics across screens and time periods. Shows which venues and dayparts have the highest social amplification. Queries observation_stream for social attention data and aggregates by the requested dimension (venue, daypart, or screen), computing average SAF, average cascade depth, average viral attention score, and event count. WHEN TO USE: - Understanding which venues generate the most social amplification - Comparing daypart effectiveness for social contagion - Identifying top-performing screens for attention cascading - Planning campaigns that leverage social proof RETURNS: - data: Array of aggregated rows, sorted by avg SAF descending - group_key: the dimension value (venue type, daypart, or screen ID) - avg_saf: average social amplification factor - avg_cascade_depth: average attention cascade depth - avg_viral_attention_score: average viral attention score - event_count: number of social attention events in the group - metadata: { group_by, time_range, total_events } - suggested_next_queries: Follow-up queries EXAMPLE: User: "Which venues have the highest social amplification this week?" get_social_contagion_summary({ group_by: "venue", time_range: { start: "2026-03-09", end: "2026-03-16" } }) User: "Show me social attention by daypart over the last 7 days" get_social_contagion_summary({ group_by: "daypart" })

Parameters2

time_range	object	optional
group_by	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "time_range": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string"
        },
        "end": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "group_by": {
      "type": "string",
      "enum": [
        "venue",
        "daypart",
        "screen"
      ]
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_dataset_stats

Get statistics about available causal training data: total tuples, unique creatives, venue diversity, date range. Queries observation_stream for rows that have both a creative ID and a VAS outcome recorded, giving a picture of how much training data is available for the causal prediction engine. WHEN TO USE: - Checking if enough data exists for reliable causal predictions - Understanding the diversity of training data (creatives, venues, time range) - Monitoring causal dataset health and growth - Planning data collection strategies RETURNS: - data: Dataset statistics - total_tuples: number of context-action-outcome records - unique_creatives: number of distinct creatives with VAS data - unique_venue_types: number of distinct venue types represented - date_range: { start, end } of available data - observations_per_creative: { min, max, mean, median } distribution - metadata: { query_window_days } - suggested_next_queries: Follow-up queries EXAMPLE: User: "How much causal training data do we have?" get_dataset_stats({})

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_content_performance

Get performance metrics for a video across the Trillboards DOOH network. WHEN TO USE: - Checking how a specific video performs across screens (plays, attention, audience size) - Analyzing which venue types and dayparts a video resonates best in - Finding the top-performing screens for a piece of content - Comparing content performance over different time windows RETURNS: - videoId, title, totalPlays, uniqueScreens - avgAttention (0-1), avgAudienceSize, avgDwellMs - venueDistribution: Array of { venue_type, plays } - daypartDistribution: Array of { daypart, plays } - topScreens: Top 10 screens by play count with attention scores - period: { start, end } date range EXAMPLE: User: "How is video dQw4w9WgXcQ performing on retail screens?" get_content_performance({ video_id: "dQw4w9WgXcQ", venue_type: "retail", days: 30 }) User: "Show me the last 7 days of performance for this video" get_content_performance({ video_id: "abc123xyz", days: 7 })

Parameters3

video_id	string	required
days	integer	optional
venue_type	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "video_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 90
    },
    "venue_type": {
      "type": "string",
      "maxLength": 100
    }
  },
  "required": [
    "video_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_content

Semantic search over content library using natural language queries and 768-D pgvector embeddings. WHEN TO USE: - Finding content by description or theme ("upbeat music videos", "cooking shows") - Discovering content similar to a concept or mood - Searching the content library without knowing exact titles or IDs - Content discovery for programmatic content scheduling RETURNS: - data: Array of matching content with similarity scores - videoId, title, contentCategory, description, durationSeconds - reviewStatus (approved/pending/rejected) - similarity (0-1, cosine similarity against query embedding) - meta: { count, query, limit, minSimilarity } EXAMPLE: User: "Find fitness and workout content" search_content({ query: "fitness workout exercise gym", limit: 10, min_similarity: 0.6 }) User: "Search for calming nature content suitable for medical offices" search_content({ query: "calming nature scenes peaceful landscapes meditation", min_similarity: 0.5 })

Parameters3

query	string	required
limit	integer	optional
min_similarity	number	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 3,
      "maxLength": 500
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "min_similarity": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_content_recommendations

Get best-performing content recommendations for a venue type and optional time context. WHEN TO USE: - Deciding what content to schedule at a specific venue type - Finding content that drives the highest audience engagement at a location - Optimizing content rotation by daypart (morning, afternoon, evening, overnight) - Content programming decisions based on performance data RETURNS: - data: Array of recommended content ranked by performance score - videoId, title, contentCategory, durationSeconds - totalPlays, uniqueScreens - avgAttention (0-1), avgDwellMs - performanceScore (composite of attention, replay density, dwell time) - meta: { count, venue_type, daypart, limit } Performance score formula: attention(40%) + replay_density(30%) + dwell_time(30%) EXAMPLE: User: "What content works best in bars during the evening?" get_content_recommendations({ venue_type: "bar", daypart: "evening", limit: 10 }) User: "Best performing content for transit screens" get_content_recommendations({ venue_type: "transit", limit: 20 })

Parameters3

venue_type	string	required
daypart	string	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "venue_type": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "daypart": {
      "type": "string",
      "enum": [
        "morning",
        "afternoon",
        "evening",
        "overnight"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "venue_type"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_endpoints

List every registered Trillboards API operation. WHEN TO USE: - First call in an agent session to learn what the API offers. - Filter to agent_safe=true to list only side-effect-free endpoints. - Narrow to a single surface (data-api, sdk-api, device-api, sensing-api, partner-api-generated, dsp-api-generated). RETURNS: - operations: Array of { surface, method, path, operation_id, summary, description, agent_safe, idempotent, cost_tier, tags, doc_url, example_request } - total_operations: Total count. - surfaces: Known surface identifiers. EXAMPLE: Agent: "What read-only endpoints can I call?" list_endpoints({ agent_safe: true })

Parameters3

surface	string	optional
agent_safe	boolean	optional
idempotent	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "surface": {
      "type": "string",
      "maxLength": 64
    },
    "agent_safe": {
      "type": "boolean"
    },
    "idempotent": {
      "type": "boolean"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

describe_endpoint

Describe a single API operation including its parameters, response shape, and error codes. WHEN TO USE: - Inspecting an endpoint's full contract before calling it. - Discovering which error codes an endpoint can return and how to recover. RETURNS: - operation: Full discovery record for the endpoint. - parameters: Raw OpenAPI parameter definitions. - request_body: Body schema (when applicable). - responses: Map of status code → description/schema. - linked_error_codes: Error catalog entries the endpoint can emit. EXAMPLE: Agent: "How do I call the screen audience endpoint?" describe_endpoint({ path: "/v1/data/screens/{screenId}/audience", method: "GET" })

Parameters2

path	string	required
method	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "method": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16
    }
  },
  "required": [
    "path",
    "method"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

validate_request

Validate a proposed request payload against the registered Zod schema for an operation, returning the exact canonical error envelope the HTTP surface would emit. WHEN TO USE: - Before calling a write endpoint, to catch payload bugs locally. - Debugging 400 validation_error responses. RETURNS: - valid: true when the payload would pass Zod validation. - When invalid, the canonical { error: { type, code, message, param, doc_url, details[] } } envelope is included under `error`. EXAMPLE: validate_request({ path: "/v1/data/query", method: "POST", payload: { dataset: "inference_outcomes", limit: 9999 } })

Parameters3

path	string	required
method	string	required
payload	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "method": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16
    },
    "payload": {}
  },
  "required": [
    "path",
    "method"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_error_codes

List every error code in the Trillboards API error catalog. WHEN TO USE: - Understanding what error codes the API can return. - Building a client-side error handler that covers all cases. - Looking up error types, HTTP statuses, and documentation URLs. RETURNS: - object: "list" - data: Array of { code, type, http_status, description, doc_url } - total: Total number of error codes. Equivalent to GET /v1/errors but executed in-process (no HTTP round-trip). EXAMPLE: Agent: "What error codes can the API return?" list_error_codes()

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

query_changelog

Query the Trillboards API changelog for recent changes, breaking changes, deprecations, and fixes. WHEN TO USE: - Check what has changed in the API before upgrading an integration. - Find breaking changes since a specific date. - Discover new features added to a specific API surface. PARAMETERS: - since (YYYY-MM-DD, optional): Only entries dated on or after this date. Unreleased entries are always included. - type (string, optional): Filter by change category. Accepts: "breaking" → changed + removed entries "additive" → added entries "deprecation" → deprecated entries "fix" → fixed entries Can be comma-separated: "breaking,deprecation" RETURNS: - object: "list" - data: Array of { version, date, type, surface, description } - total: Number of matching entries. EXAMPLE: Agent: "What broke since April 1st?" query_changelog({ since: "2026-04-01", type: "breaking" })

Parameters2

since	string	optional
type	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "since": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "type": {
      "type": "string",
      "maxLength": 100
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Install

Tools (74)

register_partnerget_partner_inforegister_devicelist_devicesget_devicedelete_deviceget_device_adsrecord_impression

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://api.trillboards.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "trillboards-dooh": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.trillboards.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.