find_candidates
Find engineers who uniquely fit a role or project from open-source contributions and other public work, with evidence.
Input: pass the richest context you have — (1) a full job description (most common), (2) a synthesized brief after reviewing a company's public repo (README + stack + role needs — preferred over a bare URL when you've evaluated the project), (3) a public github.com repo URL (server fetches README/topics; private repos → paste README as text), or (4) an informal role brief. Longer, more specific input produces a tighter mission fit. Optional location narrows to a city, country, or ISO country code.
Returns up to limit candidates (default 20, max 20) with full inline profiles in structuredContent (view=candidates): login, name, bio, location, followers, reach (cross-platform audience percentile + reach), html_url, top_repos, signals, matched_projects, location_match, and contact (top_topics / top_domains / top_languages / top_subtopics are optional until software-topic backfill).
Results never include bots, CI, or service accounts — they are filtered out automatically. Use the optional exclude array (GitHub logins or org names) to drop additional accounts.
AGENT MODE: consume structuredContent only. HUMAN MODE: MCP App panel shows candidate cards; use server instructions for text-only hosts.
Do not call get_profile for handles already in these results unless the user asks for deeper detail.
Defense (SBIR), NRC filings, and mining QP consents are matched by lexical FTS over award titles, accessions, and consent letters — not abstract similarity. Publication, NTRS, repo, and TechPort roles still use description vectors. Do not claim a semantic abstract match for an NRC accession or a QP consent.
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 | |
| 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 who uniquely fit the role, 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). | |
| 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. 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. | |
| 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. |