Skip to main content
Glama
benmonopoli

Greenhouse MCP

by benmonopoli
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

list_candidates

Retrieve candidate profiles in bulk using date-range, ID, tag, or email filters, and paginate through results for full-database scans. Read-only.

Instructions

List candidates with optional filters. Read-only.

For finding a specific person, use search_candidates_by_name (by name) or search_candidates_by_email (by email) — faster and simpler. Use this tool for bulk operations: date-range queries, fetching by specific IDs, or paginating through the full database. Created and updated date filters can't be combined in one call. Candidates here are profile-only (no applications or attachments) — use get_candidate or list_applications(candidate_id=...) for those.

Input Schema

NameRequiredDescriptionDefault
tagNoFilter by exact candidate tag name
emailNoFilter by exact email address
cursorNoPass next_cursor from the previous response to get the next page
paginateNo'single' for one page, 'all' to auto-fetch every pagesingle
per_pageNoResults per page (max 500)
candidate_idsNoFilter to specific candidate IDs (max 50)
created_afterNoISO 8601 datetime — only candidates created at/after this
updated_afterNoISO 8601 datetime — only candidates updated at/after this
created_beforeNoISO 8601 datetime — only candidates created before this
updated_beforeNoISO 8601 datetime — only candidates updated before this

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv0.5.0
    • addedInput schema / properties / candidate_ids / description
      Added value: +"Filter to specific candidate IDs (max 50)"
    • addedInput schema / properties / created_after / description
      Added value: +"ISO 8601 datetime — only candidates created at/after this"
    • addedInput schema / properties / created_before / description
      Added value: +"ISO 8601 datetime — only candidates 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 / email / description
      Added value: +"Filter by exact email address"
    • 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)"
    • addedInput schema / properties / tag
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Filter by exact candidate tag name",
+  "title": "Tag"
+}
    • addedInput schema / properties / updated_after / description
      Added value: +"ISO 8601 datetime — only candidates updated at/after this"
    • addedInput schema / properties / updated_before / description
      Added value: +"ISO 8601 datetime — only candidates updated before this"
  2. Addedv0.3.4

TDQS

A4.7/5.0
Behavior4/5

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

With no annotations supplied, the description carries the safety burden itself and does so well: it declares 'Read-only', states that results are profile-only (no applications/attachments), and discloses a real constraint that created and updated date filters can't be combined. It stops short of auth/permission or rate-limit context, keeping it out of the top band.

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

Conciseness5/5

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

Front-loads the core purpose and read-only flag, then layers alternatives, use cases, and constraints in tight, waste-free sentences. Every sentence adds routing or constraint value.

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?

An output schema exists, so return-value explanation is unneeded, and the description fills the remaining gaps: read-only scope, profile-only contents, sibling routing, and the date-filter combination limit. Nothing an agent needs to call this correctly is missing.

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 the baseline is 3. The description earns one more by adding a cross-parameter constraint the schema does not encode — that created_* and updated_* filters cannot be combined in a single call — which materially affects how an agent builds the request.

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 candidates') and immediately distinguishes itself from siblings by naming search_candidates_by_name, search_candidates_by_email, get_candidate, and list_applications with the conditions that select each. An agent can route correctly without opening any schema.

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

Usage Guidelines5/5

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

Explicitly covers when to use this tool (bulk operations: date-range queries, fetching by specific IDs, pagination) vs. when not to (finding a specific person, retrieving applications/attachments), and names the alternatives for each case. Nothing is left to inference.

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

Deploy Server

Other Tools