worker-census-report

Worker Census Report

This skill generates a complete census of all employees and contractors for a company. It pulls full worker details and presents a structured report suitable for benefits enrollment, compliance audits, and annual reviews.

Prerequisites

Collect from the user:

1. A Check company ID (looks like com_XXXXXXXXXXXXXXXXXX). Ask for it if not provided.
2. Optional filters — ask the user:
   • Worker types: employees only, contractors only, or both (default: both)
   • Status filter: active only, terminated only, or all (default: all)

Step 1: Gather Company Context

Pull the company details:

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

Note the company name for the report header.

Step 2: Build Workplace Lookup

Fetch all workplaces to map workplace IDs to addresses:

run_tool: list_workplaces { "company": "<company_id>", "limit": 500 }

Build a lookup table: { workplace_id: { name, line1, city, state, postal_code } }.

If any workplace entry lacks address details, fetch it individually:

run_tool: get_workplace { "workplace_id": "<workplace_id>" }

Step 3: Fetch Employees

Skip this step if the user requested contractors only.

3a. List all employees

run_tool: list_employees { "company": "<company_id>", "limit": 100 }

If the response includes a next cursor, paginate:

run_tool: list_employees { "company": "<company_id>", "limit": 100, "cursor": "<cursor>" }

Continue until all employees are fetched. Report progress for large companies: "Fetched 100/247 employees..."

3b. Get full details for each employee

The list endpoint returns summary data. For full details (residence, SSN last 4, etc.), fetch each employee individually:

run_tool: get_employee { "employee_id": "<employee_id>" }

Process these in batches and give progress updates (e.g., "Fetching employee details: 25/50...").

3c. Apply status filter

If the user requested active only, filter out employees with a termination_date. If terminated only, keep only those with a termination_date.