{
  "id": "get_publisher_tq_report",
  "mcp_tool": "get_publisher_tq_report",
  "status": "approved",
  "source_system": "cake",
  "environment": [
    "staging",
    "prod"
  ],
  "sharded": true,
  "shard_schema": "lucos_ro_members",
  "shard_view_prefix": "lucos_ro_tq",
  "connections": {
    "admin": "cake_admin_ro",
    "whale": "cake_whale_ro"
  },
  "objects": [
    "lucos_ro_members.lucos_ro_tq_*",
    "Admin.lucos_ro_affiliate_directory"
  ],
  "parameters": {
    "publisher": {
      "type": "string",
      "required": true
    },
    "group_by": {
      "type": "enum",
      "required": false,
      "default": "bucket",
      "values": [
        "bucket",
        "dimension",
        "day"
      ]
    },
    "date_from": {
      "type": "date",
      "required": false
    },
    "date_to": {
      "type": "date",
      "required": false
    },
    "limit": {
      "type": "int",
      "required": false,
      "default": 50
    }
  },
  "constraints": {
    "max_window_days": 92,
    "default_window_days": 30,
    "max_rows": 500,
    "timeout_ms": 60000
  },
  "allow_fields": [
    "date",
    "dimension",
    "bucket",
    "clicks",
    "pct",
    "reasons",
    "total_clicks",
    "clean_clicks",
    "low_risk",
    "medium_risk",
    "high_risk",
    "clean_pct",
    "high_risk_pct"
  ],
  "deny_fields": [
    "click_ip",
    "search_ip",
    "user_agent",
    "referrer",
    "search_terms",
    "rev_share"
  ],
  "post_processing": [
    "Answers members.admedia.com TQ Detail Report (reports/tq_detail_report, affiliate_model.php getAffClearTrustStats line 1838), which reads whale cleartrust_raw_date_pubisher_YYYYMMDD keyed on pub_id.",
    "group_by=bucket is the DEFAULT and is what the portal renders: the four fixed buckets Clean / High Risk / Medium Risk / Low Risk for the publisher over the whole range (affiliate_model.php:1933), each with its clicks, its pct and the dimensions behind it. dimension and day remain available for the per-dimension breakdown.",
    "REPRODUCES A PORTAL QUIRK: for the dimensions 'Data Center', 'Error Domains' and 'virtual machine' the portal swaps the clean and high_risk columns (affiliate_model.php:1856, :1859), so those dimensions count as clean. The swap is applied in the tool, not the view, so it is testable and visible. The Clean bucket's reason list is the high-risk reasons whose name is one of those three (:1889-1893).",
    "REPRODUCES A PORTAL QUIRK: every percentage divides by the publisher's RANGE-WIDE total_clicks, in bucket and dimension modes alike, and the guard is on the numerator - a zero numerator prints 0, never null (affiliate_model.php:1932, :1938). Row percentages therefore do not sum to 100 within a row.",
    "REPRODUCES A PORTAL BUG: the per-dimension reason counts are deduped. The portal's per-day subqueries (affiliate_model.php:1861-1863) carry no date column and are joined with UNION, not UNION ALL, so two days with an identical (pub_id, dimension, count) triple collapse into one row before the outer SUM (:1884, :1897, :1906) and the report undercounts. Reproduced per risk column independently. `<col> > 0` on each subquery decides which dimensions appear in each list.",
    "REPRODUCES A PORTAL BUG: a single missing day blanks the whole report. The portal unions every date in the window into one statement with no table-existence check (affiliate_model.php:1851-1865), so one missing day table fails the statement and the page renders empty. If any day in the window has no shard view this tool returns an empty result rather than a partial one, and shard_coverage.missing says which days caused it."
  ],
  "notes": "ClearTrust traffic-quality detail for one publisher: the portal's four risk buckets (default) or a per-dimension / per-day breakdown. Publisher is mandatory. Distinct from get_ivt_report, which is cake click-level IVT on Shorty."
}