Skip to main content
Glama

Search candidates

searchCandidates
Read-only

Search Clera's vetted candidates who are open to opportunities and recently active or actively looking. Returns profiles with name, photo and LinkedIn, never email or phone: requestIntro is how your company meets a candidate, and the returned id is what it takes. Best results: write the ideal candidate in profile (four fields in Clera's stored profile style) and bind the role with jobId; then candidates are ranked by profile similarity, keyword match and the role's past requests and passes, and each carries fit flags against the role (salary, visa, location, workplace, experience, prior decline). Candidates with a confirmed location or visa conflict against the role are excluded from results (your own contradicting filter overrides that dimension, and missing data never excludes); the other flags are advisory and never block anything. Without profile: newest profiles first, or text relevance when search_term is set. Cannot look a person up by name: names, emails and LinkedIn URLs are not searchable, so searching one returns nothing even when that person is on Clera. Asked about a named person, say name lookup is not possible, then offer listRecommendedCandidates, listPendingIntroRequests, or a search by role and skills. Never returned: candidates already shown to your company, your own employees, or people who work at Clera; a zero result does not prove the person is not on Clera. Until the company has written in its Clera Slack channel, each call, including each page, costs one of 10 searches per day, so set the filters you need before searching rather than running broad passes. Re-fetching your picks with filters.talent_ids alone is free.

Clera privately records this tool's inputs and results for usage tracking and support.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "filters": "<filters>"
    },
    "name": "searchCandidates"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoPage number (default 1).
jobIdNoThe open role this search is for, resolved by name from the job tool's list command whenever the user names or implies a role; never ask for an id and never present a role picker on search. Adds seed ranking from the role's past requests and passes, the role's rubric in the result and fit flags on every candidate. Omit for a clean-slate search: the result then says 'no role: no seeds, no rubric, no fit flags'. Pass it again on filters.talent_ids re-fetches or the flags are gone.
orgIdNoOrganization to act as. Only needed when you belong to more than one organization.
filtersYesSearch filters. All array filters are exact-value matches: get valid values for role_names, skills, job_types, preferred_work and countries from listFilterOptions, and resolve work_history / education_history / boolean_tags values with suggestFilterValues. Start focused and adjust based on the returned counts. A filter that contradicts the bound role (a country the role is not in) still wins; the result states the override.
profileNoThe ideal candidate written in Clera's stored talent-profile style: each field is embedded and compared against that same field on every candidate profile, so match the format, not natural-language prose. At least one field. With jobId, a missing field falls back to the role's own profile text; without jobId it drops out of the ranking. Returns one ranked page of up to per_page candidates (no page 2); search_term stays keywords only.
per_pageNoResults to return. Up to 10 for browsing; the card view shows them all. Up to 50 for a wide scan when you screen candidates yourself against a brief or job description: profiles come back as one dense text line each (oneliner, location, experience, employers, school, three highlight bullets) with no cards and no JSON block, roughly 0.5 KB per profile, so 50 profiles is about 25 KB or 6k tokens. If your client caps tool results below that, you might save the result to a file and screen from there. Put must-have tech in the skills or boolean_tags filters; wide-scan lines carry highlights rather than the full skill list. Then call again with filters.talent_ids set to your picks to display them as cards, each with your fit reasoning underneath.

Output Schema

NameRequiredDescriptionDefault
roleNo
orgIdYes
countsNo
talentsYes
semanticNo
conflictsNo
openRolesYesThe company's open roles, for picking which role an intro request targets.
paginationYes
filterParamsYes

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare read-only, non-destructive behavior; the description adds substantial operational context. It discloses the daily search quota and per-page cost, exclusion rules for confirmed location or visa conflicts, advisory fit flags, never-returned candidate categories, the zero-result caveat, and private input/result logging.

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?

The purpose, return constraints, ranking behavior, name-lookup limitation, and quota are front-loaded, and nearly every sentence carries operational value. It is nevertheless very dense and long, with several run-on clauses that could be split for faster scanning, though it is not padded.

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 complex search tool with nested filters, multiple ranking modes, quota behavior, sibling alternatives, and an output schema, the description covers what an agent must know before calling. Return shape is handled by the output schema, while the description supplies ranking, exclusion, cost, and re-fetch guidance.

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 schema already documents parameter formats and values. The description adds strategic meaning beyond the schema: profile must be written in Clera's four stored-profile fields, jobId adds role seeding/rubric/fit flags and must be passed again on talent_ids re-fetches, and per_page trades card browsing for wide-scan text output.

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 and resource: searching Clera's vetted, active candidates. It also names the return profile fields and explicitly distinguishes the tool from requestIntro and from name lookup, so an agent can identify its role without opening the 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 prescribes writing the ideal candidate in profile and binding the role with jobId for best results, explains fallback ranking without profile, and redirects name lookup to listRecommendedCandidates, listPendingIntroRequests, or a role/skills search. It also says re-fetching picks with filters.talent_ids alone is free and should be done after a wide scan.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources