Worker Census Report

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.

Step 4: Fetch Contractors

Skip this step if the user requested employees only.

4a. List all contractors

run_tool: list_contractors { "company": "<company_id>" }

Paginate if needed using the cursor parameter.

4b. Get full details for each contractor

run_tool: get_contractor { "contractor_id": "<contractor_id>" }

Give progress updates for large sets.

4c. Apply status filter

Same filtering logic as employees — use termination_date to determine active vs terminated status.

Step 5: Present the Report

Report Header

Worker Census Report
Company: Acme Corp (com_XXXXXXXXXXXXXXXXXX)
Generated: YYYY-MM-DD
Filter: All workers (active + terminated)

Summary Statistics

Total workers:       52
  Employees:         45 (40 active, 5 terminated)
  Contractors:        7 (6 active, 1 terminated)
Workplaces:           3

Employee Table

Present a markdown table with one row per employee:

| Name            | ID          | Status     | SSN Last 4 | DOB        | Start Date | Term Date  | Email                  | Residence                          | Workplace              |
|-----------------|-------------|------------|------------|------------|------------|------------|------------------------|------------------------------------|------------------------|
| Smith, Jane     | emp_xxxxx   | Active     | 1234       | 1990-05-15 | 2023-01-10 | —          | [email protected]       | 123 Main St, SF, CA 94105          | HQ - 456 Market St     |
| Doe, John       | emp_yyyyy   | Terminated | 5678       | 1985-11-22 | 2022-06-01 | 2024-12-15 | [email protected]       | 789 Oak Ave, Oakland, CA 94612     | HQ - 456 Market St     |
| ...             |             |            |            |            |            |            |                        |                                    |                        |

Sort by last name, then first name.

For the Residence column, format as: line1, city, state postal_code. Include line2 if present (e.g., "123 Main St Apt 4, SF, CA 94105").

For the Workplace column, use the workplace address from the lookup table. If an employee has multiple workplaces, list the primary workplace. If no workplace is assigned, show "—".

Contractor Table

Same structure, but use the contractor's address field instead of residence:

| Name            | ID          | Status | SSN Last 4 | DOB        | Start Date | Term Date  | Email                  | Address                            |
|-----------------|-------------|--------|------------|------------|------------|------------|------------------------|------------------------------------|
| Freelance, Fred | ctr_xxxxx   | Active | 9012       | 1988-03-10 | 2024-01-15 | —          | [email protected]     | 321 Pine St, LA, CA 90001          |
| ...             |             |        |            |            |            |            |                        |                                    |

Fields with Missing Data

If any worker is missing fields (no SSN, no DOB, no address, etc.), show "—" in that cell and include a summary at the end:

Data Gaps:
- 3 employees missing email addresses
- 1 contractor missing home address
- 2 employees missing SSN

Step 6: Offer Output Format

After presenting the report, ask the user if they'd like:

1. Markdown table (already shown above)
2. CSV-formatted text — output the same data as comma-separated values that the user can copy-paste into a spreadsheet:

Type,Name,ID,Status,SSN Last 4,DOB,Start Date,Term Date,Email,Address,Workplace
Employee,"Smith, Jane",emp_xxxxx,Active,1234,1990-05-15,2023-01-10,,[email protected],"123 Main St, SF, CA 94105","HQ - 456 Market St"
Employee,"Doe, John",emp_yyyyy,Terminated,5678,1985-11-22,2022-06-01,2024-12-15,[email protected],"789 Oak Ave, Oakland, CA 94612","HQ - 456 Market St"
Contractor,"Freelance, Fred",ctr_xxxxx,Active,9012,1988-03-10,2024-01-15,,[email protected],"321 Pine St, LA, CA 90001",

Quote any fields that contain commas.

Error Handling

• API errors on individual workers: Log the error, continue with remaining workers, and include a list of workers that could not be fetched at the end of the report.
• Large companies (100+ workers): Process in batches with progress updates. Warn the user before starting that this may take a moment.
• Pagination: Always follow cursors until all results are fetched. Never assume a single page contains all workers.
• No workers found: If the company has no employees or contractors, report that clearly rather than showing empty tables.
• Permission errors: If a specific worker can't be fetched (403/404), note it and continue with the rest.