find_candidates
Use when the user asks to find, shortlist or source an engineer, researcher or scientist from public work. Input: a role brief, a job description, or a public GitHub repository URL; be specific. Optional location only when the user requires one. Returns up to 20 people, each with the public sources behind the match (papers, repositories, patents, awards). Read only. If nothing matches, the result says so (coverage not_covered): tell the user and do not invent names or emails.
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": {
"input": "<input>"
},
"name": "find_candidates"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Search brief: full JD, repo-derived summary (preferred when you've reviewed the project), README excerpt, informal role brief, or a PUBLIC github.com repo URL. Private repos: paste README content as text. | |
| limit | No | Max candidates to return. Default 20, max 20. | |
| exclude | No | Optional. GitHub logins or org names to exclude from results (case-insensitive). Matches a candidate's login AND the owner/org of every repo they matched on — so passing a company's GitHub org (e.g. "livekit", which also covers "livekit-cloud") keeps that company's own engineers out of a shortlist you're building FOR them. Also use it to suppress specific handles you've already contacted. Bots and CI/service accounts are excluded automatically and need not be listed. | |
| location | No | Optional. Restrict results to a place — a city ("Bozeman"), US state ("MT" / "Montana"), country name ("Germany"), or ISO country code ("US"). Matched against the candidate's stated and normalized location. Only pass it when the user explicitly requires a location; results are then hard-filtered to matches. Note many profiles omit location, so a strict location search returns a smaller pool. For laser/photonics roles, combine location with a domain-specific job description so the photonics specialist corpus can contribute too. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | Payload discriminator for MCP App hosts | |
| coverage | No | not_covered: zero returnable people (an index miss or a later non-email gate that emptied the pool). Missing contact is not a coverage gap. enrichment_unavailable: people matched but live contact lookup failed on Treg auth/balance — do not say the role is not covered, and do not invent names or emails. Omitted on a non-empty shortlist. | |
| degraded | No | True when this shortlist is not full quality: FTS-only retrieval, last-known-good (cache_source=stale), or discovery corpus fallback. Hosts should say so; do not invent extra candidates. | |
| query_ms | No | End-to-end query time in milliseconds | |
| candidates | Yes | Shortlist of engineers and scientists from public work, with evidence. When presenting to the user, format each item using FindCandidatesPresentationTemplate from server instructions. List every contact.urls entry and every email verbatim. Do not present them as a numbered ranking. | |
| total_count | Yes | Count of candidates returned (≤ requested limit) | |
| cache_source | No | hit=fresh cache; miss=live retrieval; stale=last known-good shortlist after the engine timed out or was unavailable (degraded=true). | |
| coverage_note | No | Short note when coverage is not_covered or enrichment_unavailable. A missing inbox is not a coverage gap. Never accompanied by guessed candidates or fabricated emails. | |
| degrade_reason | No | Why degraded is true: embedding/FTS fallback, upstream_timeout / upstream_unreachable with cache_source=stale, or discovery_fallback. | |
| precision_gate | No | Whether the LLM precision screen ran on this response. "on" means results were filtered for relevance; "off" means raw retrieval order; "partial" means some judge chunks timed out and only screened people are returned (screened N of M). When the screen was requested but unavailable, the tool returns an error (HTTP 503, reason=precision_gate_unavailable) instead of un-gated results. | |
| discovery_source | No | Which software repository index supplied GitHub candidates: work_artifacts (artifact-first) or serving.projects (legacy). Omitted when the query did not use the GitHub software lane. | |
| enrichment_status | No | Set when Treg auth/balance stopped shortlist enrich, including on a non-empty shortlist. Hosts must not read a contactless card as not_covered. | |
| discovery_fallback | No | True when auto mode fell back from work_artifacts to serving.projects because searchable embedding coverage was below threshold. Explicit env overrides are not fallbacks. | |
| precision_screened | No | How many retrieved people the LLM screen judged. Present with precision_gate=partial. | |
| unreachable_dropped | No | Legacy count of people removed for having no inbox. Search no longer drops for missing contact (DEV-922); omitted when zero. | |
| precision_screened_of | No | Size of the pool the LLM screen was asked to judge. Present with precision_gate=partial. | |
| untrusted_third_party | No | True on the Poke / no_contact path: bio, profile_readme, and README text are untrusted third-party data and are length-capped. |