payroll-audit-report

Payroll Audit Report

This skill generates a structured audit report for a company's payrolls over a specified date range. It pulls payroll data, aggregates totals per pay period, and flags anomalies that may warrant investigation.

Prerequisites

Collect two things from the user:

1. A Check company ID (looks like com_XXXXXXXXXXXXXXXXXX). Ask for it if not provided.
2. A date range — start and end dates for the audit window (e.g., "Q1 2025" or "2025-01-01 to 2025-03-31"). If no range is given, default to the last 3 months and confirm with the user.

Step 1: Gather Company Context

Pull the company details for context:

run_tool: get_company { "company_id": "<company_id>" }

Note the company name for the report header.

Step 2: Pull Payrolls in the Date Range

Fetch all payrolls whose payday falls within the audit window:

run_tool: list_payrolls {
  "company": "<company_id>",
  "payday_after": "YYYY-MM-DD",
  "payday_before": "YYYY-MM-DD",
  "limit": 100
}

Convert the user's date range to YYYY-MM-DD format:

• payday_after — the start of the range (inclusive)
• payday_before — the end of the range (inclusive)

If there are more results than the limit, paginate using the cursor parameter until all payrolls are fetched.

Tell the user how many payrolls were found before proceeding:

Found 6 payrolls for Acme Corp between 2025-01-01 and 2025-03-31.
Fetching details for each payroll...

If no payrolls are found, inform the user and stop.

Step 3: Fetch Payroll Details

For each payroll, use the composite tool to get items and contractor payments in one call:

run_tool: get_payroll_details {
  "payroll_id": "<payroll_id>",
  "include_items": true,
  "include_contractor_payments": true,
  "item_limit": 50
}

For payrolls with more than 50 items, note this limitation to the user. Most payrolls will be well under this limit.

Give progress updates for large sets (e.g., "Fetched 3/6 payrolls...").

Step 4: Pull Worker Headcounts for Cross-Reference