find_top_zones
Identify high-performing advertising zones for campaign optimization by analyzing conversion data, ROI metrics, and performance thresholds to build effective whitelists.
Instructions
Find best performing zones. Useful for whitelist candidates.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| campaign_id | Yes | Campaign ID | |
| min_conversions | No | Minimum conversions (default: 1) | |
| min_roi | No | Minimum ROI percentage (default: 0) | |
| limit | No | Max results (default: 20) | |
| date_from | No | Start date | |
| date_to | No | End date |
Implementation Reference
- src/propellerads_mcp/server.py:748-785 (handler)The logic for the 'find_top_zones' tool handler, which fetches zone statistics, calculates metrics, filters by conversion and ROI thresholds, and formats the output.
elif name == "find_top_zones": zones = client.get_zone_statistics( campaign_id=args["campaign_id"], date_from=args.get("date_from"), date_to=args.get("date_to"), ) min_conv = args.get("min_conversions", 1) min_roi = args.get("min_roi", 0) limit = args.get("limit", 20) enriched = [calculate_metrics(z) for z in zones] top_zones = [ z for z in enriched if (z.get("conversions", 0) or 0) >= min_conv and (z.get("roi", 0) or 0) >= min_roi ] top_zones.sort(key=lambda x: x.get("roi", 0), reverse=True) if not top_zones: return f"No zones found matching criteria (min conversions: {min_conv}, min ROI: {min_roi}%)." lines = [f"# Top Performing Zones (Campaign {args['campaign_id']})\n\n"] lines.append("| Zone ID | Conversions | Spend | Revenue | ROI |\n") lines.append("|---------|-------------|-------|---------|-----|\n") for z in top_zones[:limit]: lines.append( f"| {z.get('zone_id')} | " f"{z.get('conversions', 0)} | " f"{format_currency(z.get('spend', z.get('cost', 0)))} | " f"{format_currency(z.get('revenue', 0))} | " f"{format_percentage(z.get('roi'))} |\n" ) zone_ids = [z.get("zone_id") for z in top_zones[:limit] if z.get("zone_id")] lines.append(f"\nZone IDs for whitelist: `{zone_ids}`") return "".join(lines) - src/propellerads_mcp/server.py:344-362 (registration)The definition and registration of the 'find_top_zones' tool, including its input schema.
Tool( name="find_top_zones", description="Find best performing zones. Useful for whitelist candidates.", inputSchema={ "type": "object", "properties": { "campaign_id": {"type": "integer", "description": "Campaign ID"}, "min_conversions": { "type": "integer", "description": "Minimum conversions (default: 1)", }, "min_roi": { "type": "number", "description": "Minimum ROI percentage (default: 0)", }, "limit": {"type": "integer", "description": "Max results (default: 20)"}, "date_from": {"type": "string", "description": "Start date"}, "date_to": {"type": "string", "description": "End date"}, },