/margin-analysis

name: "Margin Analysis"
description: >
  Per-client and per-service-line margin computation for an MSP: revenue from
  PSA billing or accounting invoices, cost of goods from Pax8/Sherweb
  wholesale pricing, and estimated labor from PSA time entries × a loaded
  technician rate. Covers the full-margin / gross-margin-only /
  cost-data-unavailable reporting tiers and why a missing cost input is
  flagged rather than interpolated from portfolio averages.
when_to_use: >-
  When ranking clients or service lines by profitability, or investigating
  whether a client is profitable at all. Use when: margin analysis, client
  profitability, which clients make money, unprofitable clients, cost to
  serve, margin by client, margin erosion, service line profitability,
  contract margin, realized rate.

Margin Analysis

Overview

Revenue is visible in every PSA and accounting system; cost is not. MSPs routinely know what they bill a client but not what it actually costs to serve them, because cost has two very different components with very different data quality: **cost of goods** (marketplace subscription costs from Pax8/Sherweb — usually complete and precise) and **cost of labor** (technician time actually spent — usually incomplete, because not every MSP enforces disciplined time entry against every ticket).

This skill computes margin at the client or service-line level using whatever cost data is actually available, and is explicit and conservative about what it could not compute — a margin number built on a guessed labor cost is worse than no margin number, because it will be trusted and acted on.

Margin = Revenue − Cost
Margin % = (Revenue − Cost) / Revenue × 100

Revenue = billed amount from PSA/accounting invoices for the period
Cost    = marketplace wholesale cost (Pax8/Sherweb) + estimated labor cost
          (PSA time entries × loaded technician rate, when available)

Anti-triggers

• **Accounting-platform financial reports** — Profit and Loss, Balance

Sheet, and Aged Receivables are prebuilt reports with their own parameters and response shape; use `xero-reports` or `qbo-reports`. Neither produces per-client or per-service-line margin, which is what this skill assembles.

• **Time entries or billing items as records** — use

`autotask-time-entries` or `autotask-billing`.

Connected Systems

| System | Role | Required? | |--------|------|-----------| | PSA (Autotask/HaloPSA/ConnectWise/Syncro) or accounting (QBO/Xero) | Revenue — billed amount per client/service line | Yes (at least one) | | Pax8 / Sherweb | Cost of goods — marketplace wholesale cost per subscription | Optional — recommended | | PSA time entries (Autotask/HaloPSA/ConnectWise/Syncro) | Cost of labor — hours logged per client, for estimating labor cost | Optional |

Revenue is the only hard requirement. Everything else is a cost input that improves accuracy but is not mandatory — this skill must still produce useful output with only revenue and zero cost data, by explicitly reporting "cost data unavailable" rather than fabricating a margin figure.

Workflow

Step 1: Discover what's connected

Call `conduit__search_tools` and search for `"invoice"`, `"subscription"`, and `"time entr"` to determine which revenue and cost sources are live for this org. Proceed with whatever combination exists.

Step 2: Pull revenue per client

Pull billed amounts for the analysis period from whichever accounting/PSA billing source is connected (`qbo__list_invoices`, `xero__list_invoices`, or the PSA's invoice/billing-item search tool). Sum to a per-client revenue total for the period. Where service-line-level margin is requested rather than whole-client margin, keep revenue broken out by line description/service rather than collapsing to a single total.

Step 3: Pull cost of goods (if connected)

Pull active subscriptions from Pax8/Sherweb (`pax8__list_subscriptions` or the Sherweb equivalent) for the same client, and sum wholesale unit cost × quantity to a per-client cost-of-goods total for the period. This is the most reliable cost input available — treat it as ground truth once fetched.

Step 4: Estimate cost of labor (if time-entry data is connected — treat as an estimate, always)

Pull time entries for the client for the period from the PSA (`autotask__search_time_entries` or the connected PSA's equivalent). Sum logged hours. Multiply by a loaded technician rate to estimate labor cost.

**The loaded rate must come from context, not be invented:**

• If the user or prior context supplies a blended/loaded hourly rate, use it.
• If the PSA exposes a billing rate or cost rate per resource, use that as the

best available proxy and say so.

• If no rate is available from any source, do **not** invent one. Report hours

logged as a fact, mark estimated labor cost as "not computed — no loaded rate available," and exclude it from the margin calculation rather than silently defaulting to an arbitrary number.

Time-entry data is inherently an underestimate of true cost-to-serve when time tracking discipline is inconsistent — note this caveat in the report whenever labor cost is included, so the reader doesn't over-trust a number built on incomplete logging.

Step 5: Compute margin, flagging what's missing

For each client (or service line):

• **Full data (revenue + COGS + labor)** — compute margin and margin %

normally.

• **Revenue + COGS only** — compute a "gross margin (excludes labor)" figure

and label it as such. Do not present it as full margin.

• **Revenue only** — do not compute a margin figure. Report revenue and state

"cost data unavailable — margin cannot be computed" rather than guessing or omitting the client from the report entirely.

Never interpolate a missing cost component from portfolio averages or silently skip a client with incomplete data — both produce a false sense of coverage. Every client in scope appears in the output, with its data-completeness sta