Skip to main content
Glama

Find similar candidates

similarCandidates
Read-onlyIdempotent

Given one candidate your company has already been shown, return other candidates whose profiles are closest to theirs, ranked by similarity. Use it when someone likes a specific profile and wants more of the same, and after requestIntro to keep the shortlist moving. Chain it: run it again on a result to walk further from the original person. Similarity is computed from the whole profile (role, skills, experience and domain), not from filters, so this takes no search criteria; use searchCandidates when the ask is a requirement rather than a resemblance. Results stay within a band around the starting candidate's years of experience. Each result carries a similarity from 0 to 1 for your own screening: a low number means the open pool had nobody close, so say that instead of presenting a weak match as similar, and never show the number to the user. The same exclusions as searchCandidates apply, so people already shown to your company, your own employees, and people who work at Clera never come back, and the starting candidate is never in their own results.

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": {
      "talentId": "<talentId>"
    },
    "name": "similarCandidates"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoPage number (default 1).
orgIdNoOrganization to act as. Only needed when you belong to more than one organization.
per_pageNoResults to return, up to 10. They are displayed as cards.
talentIdYesThe candidate to match against, as returned by searchCandidates, listRecommendedCandidates or listPendingIntroRequests. Must be someone Clera has already shown your company.

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?

Goes well past the readOnly/idempotent/non-destructive annotations: discloses the experience-band restriction on results, the 0-to-1 similarity score and how to interpret and present it ('never show the number to the user'), the full exclusion set (already-shown people, own employees, Clera staff, self-exclusion), and a data-recording notice.

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-loaded with purpose, then usage, then chaining, then guardrails — a logical order with no wasted setup. It is on the long side and the closing telemetry sentence is boilerplate, but nearly every clause carries decision-relevant information.

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 single-required-parameter lookup with an output schema present, this covers everything an agent needs: when to call it, what it cannot do (no filters), how results are constrained and ranked, how to interpret the similarity score, and which candidates are excluded.

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; the description adds real meaning by stating the tool 'takes no search criteria' and by clarifying that talentId is an already-shown candidate whose own results never include themselves. Pagination is covered by the schema, though the chaining hint ('run it again on a result') implicitly supports using a returned ID as the next talentId.

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 ('return other candidates whose profiles are closest'), names the anchor input ('one candidate your company has already been shown'), and explicitly separates itself from searchCandidates by contrasting resemblance vs. requirement. An agent can identify the tool 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?

Gives concrete triggers ('when someone likes a specific profile and wants more of the same', 'after requestIntro to keep the shortlist moving'), a chaining pattern ('run it again on a result'), and an explicit exclusion routing the agent to searchCandidates when the ask is a requirement rather than a resemblance.

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