search_employees
Search employee directory by name, job title, email, or employee ID to find basic employee information and obtain employee IDs for detailed lookups.
Instructions
Search the employee directory by name, job title, email, or employee ID. Returns matching employees with basic info (name, title, department, status, supervisor). Use this first to find someone's employee ID, then use get_employee for full details.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| companyId | No | Paylocity company ID (defaults to PAYLOCITY_COMPANY_ID env var) | |
| query | Yes | Search term — matches name, title, email, or employee ID | |
| statusFilter | No | Filter by status (default: all) |
Implementation Reference
- src/server.ts:247-266 (handler)The handler function that executes the "search_employees" tool logic, including filtering and status processing.
async ({ companyId, query, statusFilter }) => { try { const cid = resolveCompanyId(companyId); const dir = await getDirectory(cid); const q = query.toLowerCase(); let results = dir.filter((e) => { const haystack = `${e.employeeId} ${e.firstName} ${e.lastName} ${e.jobTitle} ${e.workEmail}`.toLowerCase(); return haystack.includes(q); }); if (statusFilter === "active") results = results.filter((e) => e.status === "A"); else if (statusFilter === "terminated") results = results.filter((e) => e.status === "T"); return ok({ count: results.length, employees: results }); } catch (e) { return err(e); } - src/server.ts:232-246 (registration)Registration of the "search_employees" tool with its schema definition and input parameters.
server.tool( "search_employees", `Search the employee directory by name, job title, email, or employee ID. Returns matching employees with basic info (name, title, department, status, supervisor). Use this first to find someone's employee ID, then use get_employee for full details.`, { companyId: companyIdParam, query: z .string() .describe("Search term — matches name, title, email, or employee ID"), statusFilter: z .enum(["all", "active", "terminated"]) .optional() .describe("Filter by status (default: all)"), },