get_zone_performance
Retrieve zone-level performance statistics to identify top-performing placements and optimize whitelist/blacklist decisions for ad campaigns.
Instructions
Get performance statistics grouped by zone/placement. Useful for whitelist/blacklist optimization.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | No | Filter by campaign ID | |
| date_from | No | Start date (YYYY-MM-DD) | |
| date_to | No | End date (YYYY-MM-DD) | |
| limit | No | Max number of zones to return (default: 100) | |
| sort_by | No | Sort by: spend, conversions, roi, ctr |
Implementation Reference
- src/propellerads_mcp/server.py:642-674 (handler)The `get_zone_performance` tool handler, which retrieves zone statistics from the client, calculates performance metrics, and formats the output as a Markdown table.
elif name == "get_zone_performance": zones = client.get_zone_statistics( campaign_id=args.get("campaign_id"), date_from=args.get("date_from"), date_to=args.get("date_to"), limit=args.get("limit", 100), ) if not zones: return "No zone statistics found." enriched = [calculate_metrics(z) for z in zones] # Sort if requested sort_by = args.get("sort_by", "spend") enriched.sort(key=lambda x: x.get(sort_by, 0), reverse=True) lines = ["# Zone Performance\n\n"] lines.append("| Zone ID | Impressions | Clicks | CTR | Conv | Spend | ROI |\n") lines.append("|---------|-------------|--------|-----|------|-------|-----|\n") for z in enriched[:args.get("limit", 100)]: lines.append( f"| {z.get('zone_id', 'N/A')} | " f"{z.get('impressions', 0):,} | " f"{z.get('clicks', 0):,} | " f"{format_percentage(z.get('ctr'))} | " f"{z.get('conversions', 0)} | " f"{format_currency(z.get('spend', z.get('cost', 0)))} | " f"{format_percentage(z.get('roi'))} |\n" ) return "".join(lines) - The `Tool` registration for `get_zone_performance`, defining the tool name, description, and input schema.
name="get_zone_performance", description="Get performance statistics grouped by zone/placement. Useful for whitelist/blacklist optimization.", inputSchema={ "type": "object", "properties": { "campaign_id": { "type": "integer", "description": "Filter by campaign ID", }, "date_from": {"type": "string", "description": "Start date (YYYY-MM-DD)"}, "date_to": {"type": "string", "description": "End date (YYYY-MM-DD)"}, "limit": { "type": "integer", "description": "Max number of zones to return (default: 100)", }, "sort_by": { "type": "string", "description": "Sort by: spend, conversions, roi, ctr", "enum": ["spend", "conversions", "roi", "ctr"], }, }, }, ),