hires_list_candidates
List candidates with optional filters. Supports filtering by job, stage, email, name, LinkedIn, and date ranges. Returns paginated results. Recommended size <= 10: candidate payloads include the full profile answers array and can be large; if the response exceeds the budget the tool returns isErr...
This record as markdown: /tools/com-100hires-100hires/hires-list-candidates.md
What hires_list_candidates does on 100Hires - AI ATS & Recruitment Software
AI agents call hires_list_candidates to retrieve information from 100Hires - AI ATS & Recruitment Software without modifying anything. It is typically the context-gathering step in research, monitoring, and reporting workflows, before the agent takes action elsewhere.
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | — | Plain-text search by name or email. Supports partial matches. |
page | number | — | Page number (1-based). |
size | number | — | Number of items per page. |
view | string | — | Response shape. Default `summary` excludes the `profile` array (custom profile-form answers). Use `full` only when those answers are genuinely needed; call hire |
email | string | — | Exact candidate email filter. |
job_id | number | — | Filter candidates by job ID. |
include | string | — | Comma-separated related data. Supported: `applications` — embeds each candidate's application summaries with job titles and pipeline stages. Recommended when th |
linkedin | string | — | Search by LinkedIn profile URL or alias (e.g. 'johndoe' or full URL). |
stage_id | number | — | Filter candidates by pipeline stage ID. Best used together with job_id. |
full_name | string | — | Candidate full-name filter. |
company_id | number | — | Filter by company ID. Required only when the API key has access to multiple companies. |
created_after | number | string | — | Return only candidates created at or after this time. Unix timestamp (seconds) or ISO-8601 string (e.g. 2026-05-11T00:00:00Z). Fractional seconds accepted but t |
Parameters from the server's own tool schema.
Why hires_list_candidates is rated Low
This is a straightforward query/list operation that retrieves candidate information from the ATS system. It has no side effects—it does not create, modify, delete, or execute any actions. The tool's primary function is to search and fetch candidate records, which is characteristic of Read category tools.
From the tool's definition Tool description states 'List candidates with optional filters' and 'Returns paginated results.' The tool retrieves and queries candidate data without modifying, deleting, or executing operations.
Risk signalsHigh parameter count (13 properties)
Attacks that exploit this kind of access
The rule that runs hires_list_candidates safely
PolicyLayer is an MCP gateway: it sits between your AI agents and 100Hires - AI ATS & Recruitment Software, and checks every tool call against a rule you set before the call runs. Nothing changes on the server itself. For hires_list_candidates, this is the rule to start with:
hires_list_candidates is read-only, so it stays allowed. Everything else on the server is denied unless you say otherwise.
The button opens the PolicyLayer dashboard: create your workspace, connect 100Hires - AI ATS & Recruitment Software, apply this rule, and every hires_list_candidates call is checked against it from then on.
Questions about hires_list_candidates
List candidates with optional filters. Supports filtering by job, stage, email, name, LinkedIn, and date ranges. Returns paginated results. Recommended size <= 10: candidate payloads include the full profile answers array and can be large; if the response exceeds the budget the tool returns isError:true with error_code=response_too_large and retry hints — reduce size, narrow filters, or fetch a single record via hires_get_candidate. It is categorised as a Read tool in the 100Hires - AI ATS & Recruitment Software MCP Server, which means it retrieves data without modifying state.
hires_list_candidates accepts 12 parameters: q, page, size, view, email, job_id, include, linkedin, stage_id, full_name, company_id, created_after. The full parameter table on this page comes from the server's own tool schema.
Register the 100Hires - AI ATS & Recruitment Software MCP server in PolicyLayer and add a rule for hires_list_candidates: allow, deny, rate-limit, or require approval. Point your MCP client at the PolicyLayer proxy URL and the rule is enforced on every call, before it reaches 100Hires - AI ATS & Recruitment Software. Nothing to install.
hires_list_candidates is a Read tool with low risk. Read-only tools are generally safe to allow by default.
Yes. Add a rate_limit block to the hires_list_candidates rule in your PolicyLayer policy. For example, setting max: 10 and window: 60 limits the tool to 10 calls per minute. Rate limits are tracked per agent session and reset automatically.
Set action: deny in the PolicyLayer policy for hires_list_candidates. The AI agent will receive a policy violation error and cannot call the tool. You can also include a reason field to explain why the tool is blocked.
hires_list_candidates is provided by the 100Hires - AI ATS & Recruitment Software MCP server (https://mcp.100hires.com/mcp). PolicyLayer sits as a proxy in front of this server to enforce policies before tool calls reach the server.
More on 100Hires - AI ATS & Recruitment Software, and thousands of servers like it.
Across the catalogue