Greenhouse MCP

list_users

List Greenhouse team members and resolve names or emails to user IDs for interviewers, approvers, and hiring managers. Filter by email or paginate to scan users.

Instructions

List all Greenhouse users (team members, not candidates). Read-only.

This is the primary tool for resolving team member names to user IDs. When another tool needs a user_id (interviewer, approver, hiring manager), use this to find the person by name or email. Filter by email for exact lookup (matches the primary email first, then any secondary address), or paginate to scan. Each user has deactivated (was disabled), primary_email, office_ids and department_ids (get_user adds names and secondary emails).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`email`	No	Filter by exact email address (primary or secondary)
`cursor`	No	Pass next_cursor from the previous response to get the next page
`paginate`	No	'single' for one page, 'all' to auto-fetch every page	single
`per_page`	No	Results per page (max 500)
`deactivated`	No	true = only deactivated users, false = only active; omit for both
`created_after`	No	ISO 8601 datetime — only users created after this
`created_before`	No	ISO 8601 datetime — only users created before this

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv0.5.0Oct 5, 2026

addedInput schema / properties / created_after / description

Added value: +"ISO 8601 datetime — only users created after this"

addedInput schema / properties / created_before / description

Added value: +"ISO 8601 datetime — only users created before this"

addedInput schema / properties / cursor

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Pass next_cursor from the previous response to get the next page",
+  "title": "Cursor"
+}

addedInput schema / properties / deactivated

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "true = only deactivated users, false = only active; omit for both",
+  "title": "Deactivated"
+}

addedInput schema / properties / email / description

Added value: +"Filter by exact email address (primary or secondary)"

removedInput schema / properties / page

Removed value: -{
-  "default": 1,
-  "title": "Page",
-  "type": "integer"
-}

addedInput schema / properties / paginate / description

Added value: +"'single' for one page, 'all' to auto-fetch every page"

addedInput schema / properties / per_page / description
```
Added value: +"Results per page (max 500)"
```

Addedv0.3.4Apr 15, 2026

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and discharges the key part by declaring 'Read-only' and explaining the deactivated/disabled field rename. It also notes get_user's richer return. It doesn't discuss rate limits or error behavior, but the safety and data-shape disclosures are solid for a read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core identity and safety ('List all Greenhouse users ... Read-only'), then purpose, then lookup mechanics. Each sentence contributes; it is slightly long but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter list tool with 100% schema coverage and an output schema, the description covers purpose, safety, routing, and lookup behavior. Nothing an agent needs to call it correctly is missing, and return-value detail is rightly delegated to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: email matches 'the primary email first, then any secondary address', and it frames paginate as a scan-vs-exact-lookup choice. The deactivated field semantics are also restated usefully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('List all Greenhouse users') and immediately disambiguates scope ('team members, not candidates'). It distinguishes itself from the sibling get_user by noting that get_user returns additional names and secondary emails, so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear when-to-use context: 'primary tool for resolving team member names to user IDs' and the trigger ('when another tool needs a user_id'). Also contrasts the email-lookup path vs the paginate-to-scan path. It stops short of an explicit exclusion ('do not use when X'), but the practical routing is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server