DevMatch

find_candidates

Read-onlyIdempotent

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.

Input Schema

Name	Required	Description
`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
`view`	No	Payload discriminator for MCP App hosts
`coverage`	No	Set to not_covered when this search returned zero returnable people. That includes an index miss and a match with no contact coverage. Hosts must say so and must not invent names or emails.
`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. When people matched but none have a stored or Treg-enriched inbox, this says so with a count. 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.
`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	How many retrieved people this search removed because they had no real inbox and no Treg enrichment path (LinkedIn or name+company domain). 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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 19, 2026

changedOutput schema / properties / precision_gate / description

Previous value: -"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."New value: +"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."

changedOutput schema / properties / precision_gate / enum

Previous value: -[
-  "on",
-  "off"
-]New value: +[
+  "on",
+  "off",
+  "partial"
+]

addedOutput schema / properties / precision_screened

Added value: +{
+  "description": "How many retrieved people the LLM screen judged. Present with precision_gate=partial.",
+  "type": "integer"
+}

addedOutput schema / properties / precision_screened_of

Added value: +{
+  "description": "Size of the pool the LLM screen was asked to judge. Present with precision_gate=partial.",
+  "type": "integer"
+}

Changed1 schema field changedOct 17, 2026

changedOutput schema / properties / candidates / description

Previous value: -"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."New value: +"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."

Changed2 schema fields changedOct 5, 2026

changedOutput schema / properties / candidates / items / properties / source / description

Previous value: -"Which corpus this person came from, and therefore what kind of evidence backs them. github = open-source contributions with contact details. orcid = published research, no GitHub, no contact. sbir = federal defense award record. ntrs = NASA technical reports. nrc = nuclear regulatory filings. edgar = mining technical-report consents. photonics = laser/photonics SBIR awards. techport = NASA technology projects. uspto = named inventors on granted US patents. rosap = authors of USDOT technical reports (vehicles, rail, bridges, pavement). osti = authors of DOE technical reports (fusion, nuclear fuel, turbines, grids, materials). usgs = authors of USGS numbered-series reports. erdc = authors of public Army Corps ERDC reports. treesearch = authors of Forest Service agency-series reports (not scientific journals). nist = authors of NIST technical-series reports (not journal articles). noaa = authors of NOAA agency-series reports (technical memoranda and technical reports, not journal articles). nrcan = authors of Natural Resources Canada GEOSCAN reports (not journal articles, not corporate authors). nparc = authors of National Research Council Canada technical reports (not journal articles, not US NRC filings). jaea = authors of Japan Atomic Energy Agency technical reports in JOPSS (JAEA Reports, not journal articles, not the US NRC, not the IAEA). fraunhofer = authors of Fraunhofer Publica technical reports (not journal articles, patents, or dissertations). sintef = authors of SINTEF research reports (Cristin category REPORT, not journal articles). csic = authors of CSIC technical reports (DIGITAL.CSIC type informe técnico, not journal articles). nora = authors of NERC Open Research Archive reports (type Publication - Report, not journal articles). cern = authors of CERN document-server technical reports (CDS set cerncds:REPORT, not journal articles). dlr = authors of DLR elib report-series records (elib set types=monograph (Berichtsreihe), not journal articles). brgm = authors of BRGM InfoTerre public reports (type Rapport, not journal articles or maps). rws = authors of Rijkswaterstaat onderzoeksrapporten (public technical reports). criepi = authors of CRIEPI technical reports (電力中央研究所報告, not journal articles). rivm = authors of RIVM official reports (Rijksinstituut voor Volksgezondheid en Milieu, not journal articles). cgspace = authors of CGSpace reports (CGIAR item type Report, not journal articles or working papers). cirad = authors of CIRAD Agritrop technical documents (EPrints type document_technique, not mission reports or journal articles). rise = authors of RISE Research Institutes of Sweden technical reports (DiVA publicationTypeCode report, not journal articles). sgb = authors of Serviço Geológico do Brasil technical reports (RiGeo Relatórios Técnicos, not journal articles, not Atlas). ga = authors of Geoscience Australia Records (eCat type GA Record, not maps or journals). sgm = authors of Servicio Geológico Mexicano historical technical reports (Archivo Técnico Histórico, not other SGM collections). wamex = authors of WAMEX mineral exploration reports. aris = authors of ARIS mineral assessment reports. gemis = authors of GEMIS minerals exploration reports. gsv = authors of GSV mining tenement reports (not assay registers, borehole logs, plans, or maps). ygs = authors of Yukon Geological Survey open assessment reports, including YMEP reports on that list (not confidential Closed rows, not corporate authors, not publications, not minfile). gsnl = authors of Geological Survey of Newfoundland and Labrador mineral assessment reports (not corporate authors, not the mixed GeoFiles library). novascan = authors of NovaScan assessment reports (Assessment Report ME, not property, open-file, or departmental reports). tasxrept = authors of Mineral Resources Tasmania onshore company reports (TASXREPT, not offshore hydrocarbon reports, not the mixed MRT document index). These are SEPARATE populations, not one enriched record — never merge people across them, and never present a non-github candidate as having open-source contributions."New value: +"Which corpus this person came from, and therefore what kind of evidence backs them. github = open-source contributions with contact details. orcid = published research, no GitHub, no contact. sbir = federal defense award record. ntrs = NASA technical reports. nrc = nuclear regulatory filings. edgar = mining technical-report consents. photonics = laser/photonics SBIR awards. techport = NASA technology projects. uspto = named inventors on granted US patents. rosap = authors of USDOT technical reports (vehicles, rail, bridges, pavement). osti = authors of DOE technical reports (fusion, nuclear fuel, turbines, grids, materials). usgs = authors of USGS numbered-series reports. erdc = authors of public Army Corps ERDC reports. treesearch = authors of Forest Service agency-series reports (not scientific journals). nist = authors of NIST technical-series reports (not journal articles). noaa = authors of NOAA agency-series reports (technical memoranda and technical reports, not journal articles). nrcan = authors of Natural Resources Canada GEOSCAN reports (not journal articles, not corporate authors). nparc = authors of National Research Council Canada technical reports (not journal articles, not US NRC filings). jaea = authors of Japan Atomic Energy Agency technical reports in JOPSS (JAEA Reports, not journal articles, not the US NRC, not the IAEA). fraunhofer = authors of Fraunhofer Publica technical reports (not journal articles, patents, or dissertations). sintef = authors of SINTEF research reports (Cristin category REPORT, not journal articles). csic = authors of CSIC technical reports (DIGITAL.CSIC type informe técnico, not journal articles). nora = authors of NERC Open Research Archive reports (type Publication - Report, not journal articles). cern = authors of CERN document-server technical reports (CDS set cerncds:REPORT, not journal articles). dlr = authors of DLR elib report-series records (elib set types=monograph (Berichtsreihe), not journal articles). brgm = authors of BRGM InfoTerre public reports (type Rapport, not journal articles or maps). rws = authors of Rijkswaterstaat onderzoeksrapporten (public technical reports). criepi = authors of CRIEPI technical reports (電力中央研究所報告, not journal articles). rivm = authors of RIVM official reports (Rijksinstituut voor Volksgezondheid en Milieu, not journal articles). cgspace = authors of CGSpace reports (CGIAR item type Report, not journal articles or working papers). cirad = authors of CIRAD Agritrop technical documents (EPrints type document_technique, not mission reports or journal articles). rise = authors of RISE Research Institutes of Sweden technical reports (DiVA publicationTypeCode report, not journal articles). sgb = authors of Serviço Geológico do Brasil technical reports (RiGeo Relatórios Técnicos, not journal articles, not Atlas). ga = authors of Geoscience Australia Records (eCat type GA Record, not maps or journals). sgm = authors of Servicio Geológico Mexicano historical technical reports (Archivo Técnico Histórico, not other SGM collections). wamex = authors of WAMEX mineral exploration reports. aris = authors of ARIS mineral assessment reports. gemis = authors of GEMIS minerals exploration reports. gsv = authors of GSV mining tenement reports (not assay registers, borehole logs, plans, or maps). ygs = authors of Yukon Geological Survey open assessment reports, including YMEP reports on that list (not confidential Closed rows, not corporate authors, not publications, not minfile). gsnl = authors of Geological Survey of Newfoundland and Labrador mineral assessment reports (not corporate authors, not the mixed GeoFiles library). novascan = authors of NovaScan assessment reports (Assessment Report ME, not property, open-file, or departmental reports). tasxrept = authors of Mineral Resources Tasmania onshore company reports (TASXREPT, not offshore hydrocarbon reports, not the mixed MRT document index). sgc = authors of Servicio Geológico Colombiano technical reports (Koha item type Informes técnicos, not maps or theses). csiro = authors of CSIRO technical reports (Commonwealth Scientific and Industrial Research Organisation publication type Report, not journal articles, not a join to USGS or GitHub). oafd = authors of Ontario Assessment File Database approved assessment files (not non-assessment exploration work, not drill holes, not survey publications, and the catalog has no abstract). sigeom = authors of SIGÉOM GM exploration reports (Rapport de travaux d'exploration minière; ministry series, theses, and maps are not this corpus; the catalog has no abstract). These are SEPARATE populations, not one enriched record — never merge people across them, and never present a non-github candidate as having open-source contributions."