/distribution-analysis

name: distribution-analysis
description: Analyzes a Chili Piper round-robin distribution for a workspace and date range — meeting counts by rep, imbalance vs. configured weights, day-of-week and source skew, and cancellations — interpreted against the workspace's fairness settings (credit-back, vacation calibration, reset period). Use when asked why a rep gets more or fewer meetings, or for a distribution breakdown.
version: 0.2.2
references:
  - api-reference
  - output-format
inputs:
  - name: workspace
    type: string
    description: "Workspace name or ID containing the distribution."
    required: true
  - name: distribution
    type: string
    description: "Distribution name (substring) or distributionId to analyze."
    required: true
  - name: start_date
    type: string
    description: "Start of range, inclusive (e.g. 2026-05-01)."
    required: true
  - name: end_date
    type: string
    description: "End of range, exclusive (e.g. 2026-06-01 = through May 31)."
    required: true
outputs:
  - name: distribution_config
    description: The distribution's active members, weights, and assignment handling, plus the workspace fairness settings (credit-back, vacation calibration, reset period, tie-break order)
  - name: rep_breakdown
    description: Meeting counts by rep (total, completed, cancelled, no-show) with imbalance ratio
  - name: patterns
    description: Booking-source skew, day-of-week skew, weekly trend, and cancellation breakdown
  - name: recommendations
    description: Likely causes of imbalance and what to check
tools_required: [chili-piper-mcp]
human_decision_point: "Review the imbalance findings and decide whether to rebalance weights, fix calendar/availability for an under-booked rep, or adjust the distribution in the router builder"
writes_to: "Nothing — read-only diagnostic. Apply any rebalancing in the Chili Piper router builder (or via distribution-adjust-v3 with explicit human approval)."
api_note: "2026-09-04 (CEH-11548, edge PR #1131, live since 2026-09-01): the distribution-list-put MCP tool returns a full PaginatedResult — {results: [...], total, page, pageSize} — NOT a bare top-level array as this skill previously documented. Iterate results to reach individual distribution records; total gives the count without extra calls. references/api-reference.md § Tools and Step 2 updated accordingly. 2026-09-07 (edge PR #1162 internal-minor bump): WorkspaceResetPeriodicity has two new variants — Daily ({type: 'Daily', timeZone}) and Weekly ({type: 'Weekly', dayOfWeek: 1–7, timeZone; 1=Monday, 7=Sunday}). Prior variants (Monthly/Quarterly/Yearly/Never) are unchanged. Update Step 3 fairness-settings interpretation and any period display logic to handle these two new reset cadences."

Distribution Analysis

You are a RevOps analyst. Pull a Chili Piper distribution's configuration and the meetings its member reps hosted over a date range, then surface imbalance patterns and likely causes — using only the public Chili Piper MCP.

> **Prefer live data over training.** MCP field names and tool signatures change. Load > `references/api-reference.md` before making MCP calls — it is the canonical field-name > truth for this skill.

> **Scope & honesty.** The public MCP cannot filter meetings by `distributionId` and has no distribution config-history endpoint (current settings are readable via `distribution-workspace-settings-get`, but not their change history). This skill attributes meetings to a distribution by its **member reps (host)**. If a rep belongs to multiple distributions, their meetings count toward each — state this caveat in the output. For exact per-distribution routing attribution, use the routing logs (`/audit-routing`, `concierge-logs`).

When to use

• Someone asks why a rep is getting more or fewer meetings than others.
• Someone wants a distribution breakdown (counts by rep, imbalance vs. weights).
• Someone wants to analyze meeting imbalance for a workspace over a period.

Inputs

| Input | Required | Default | What it controls | |-------|:--------:|---------|------------------| | `workspace` | ✅ | — | Workspace name or ID containing the distribution. | | `distribution` | ✅ | — | Distribution name (substring) or distributionId to analyze. | | `start_date` | ✅ | — | Start of range, inclusive (e.g. 2026-05-01). | | `end_date` | ✅ | — | End of range, exclusive (e.g. 2026-06-01 = through May 31). |

If a required input is missing, ask for it in one sentence rather than guessing.

Process

Step 1 — Resolve the workspace

If `workspace` is a name, call `workspace-list` and match on `name`; use its `id`.

tool: workspace-list
args:
  pagination:
    page: 0
    pageSize: 100

Step 2 — Find the distribution and read its config

tool: distribution-list-put
args:
  workspaceIds: [<workspace.id>]
  name: <distribution>          # omit if you were given a distributionId; filter results instead

The response is `{results: [...], total, page, pageSize}` — iterate `results` (CEH-11548). Extract name, active members, weights, handling/algorithm, capping, and per-member period statistics from the matching `results[]` item; derive the per-rep ideal number. If no distribution matches, say so and list the available distribution names in the workspace. Config fields, period statistics, and the `idealNumber` derivation → `references/api-reference.md` § distribution-list-put — config fields and § distribution-list-put — period statistics (authoritative totals).

Step 3 — Read the workspace fairness settings

tool: distribution-workspace-settings-get
args:
  workspaceId: <workspace.id>

These workspace-level settings shape the round-robin leveling equation on top of the distribution's weights, and are shared by every distribution in the workspace. Read them before interpreting the statistics — never assume the leveling rules. In particular, `resetPeriodicity` defines the **current distribution period** that the `sta