/** * @fileoverview Match patient demographics to candidate recruiting clinical trials. * Candidates are matched on demographics, location, recruitment status, and a * fuzzy condition search; inclusion/exclusion criteria are never checked. * @module mcp-server/tools/definitions/find-eligible.tool */ import { z } from '@cyanheads/mcp-ts-core'; import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors'; /** The distinct folded words of a place name; see `foldedWords`. */ export declare function placeWords(name: string): Set; /** * Score how directly a study's own listed conditions match the patient's * requested conditions. ClinicalTrials.gov's `query.cond` is a fuzzy relevance * search that pulls in tangential trials via the MeSH umbrella (e.g. a Von * Willebrand bleeding-disorder trial matches "Cardiovascular Disease" through a * distant MeSH ancestor). This score re-ranks those tangential matches below * trials whose own condition list actually names a requested condition — a * transparent, deterministic rule, not a relevance estimate. Recall is * unchanged: every upstream match is still returned, only reordered. * * Tiers (best across the study's conditions × requested conditions): * 3 — exact match (study condition equals a requested condition) * 2 — every significant token of a multi-word requested condition is present * in a study condition, so the study names the same concept or a more * specific subtype — independent of word order ("Type 2 Diabetes" matches * both "Type 2 Diabetes Mellitus" and "Diabetes Mellitus, Type 2"; * "Cardiovascular Disease" matches "Atherosclerotic Cardiovascular * Disease"). Gated to multi-word requests so a single word like * "Hypertension" does not credit the distinct disease "Pulmonary Arterial * Hypertension" as a subtype — it falls to tier 1, below a genuine * "Hypertension" exact match at tier 3. * 1 — a shared significant token ("Type 2 Diabetes" ↔ "Diabetes Mellitus") * 0 — no direct overlap (matched only through upstream fuzziness) */ export declare function conditionMatchScore(studyConditions: string[], requested: string[]): number; export declare const findEligible: import("@cyanheads/mcp-ts-core").ToolDefinition>, unknown>; sex: z.ZodEnum<{ ALL: "ALL"; FEMALE: "FEMALE"; MALE: "MALE"; }>; conditions: z.ZodArray; location: z.ZodObject<{ country: z.ZodString; state: z.ZodOptional; city: z.ZodOptional; }, z.core.$strict>; healthyVolunteer: z.ZodDefault; recruitingOnly: z.ZodDefault; maxResults: z.ZodDefault; locationLimit: z.ZodDefault; }, z.core.$strip>, z.ZodObject<{ studies: z.ZodArray>; totalCount: z.ZodOptional; }, z.core.$strip>, readonly [{ readonly reason: "blank_value"; readonly code: JsonRpcErrorCode.ValidationError; readonly when: "A conditions entry or location.country was supplied blank — empty, whitespace-only, or made only of `\"` characters, invisible format characters such as zero-width spaces, and whitespace, since `\"` is stripped before the query is built — or conditions was an empty list."; readonly recovery: "Supply a value containing non-whitespace, or for a list parameter at least one non-blank entry. Only when the parameter is optional and you meant to leave it unset, omit it entirely instead — omission and a blank value mean different things here."; }, { readonly reason: "field_invalid"; readonly code: JsonRpcErrorCode.ValidationError; readonly when: "A conditions entry carries an AREA[] expression naming a field ClinicalTrials.gov does not recognize or cannot search by value, or putting a valid field where upstream refuses it: a study-level field inside SEARCH[Location](…), or RANGE[] on a field that is not a date, number, or age."; readonly recovery: "Call clinicaltrials_get_field_definitions to browse the field tree; use PascalCase piece names like OverallStatus, Phase, or StudyType. AREA expressions and clinicaltrials_get_field_values take leaf pieces only: LeadSponsorName, not the group LeadSponsor."; readonly thrownBy: "service"; }, { readonly reason: "enum_invalid"; readonly code: JsonRpcErrorCode.ValidationError; readonly when: "A conditions entry carries an AREA[] expression with a value ClinicalTrials.gov does not accept for that enum field, such as AREA[Phase]PHASE9."; readonly recovery: "Call clinicaltrials_get_field_values with fields=[\"OverallStatus\"] or fields=[\"Phase\"] to see the valid enum values the filter accepts."; readonly thrownBy: "service"; }, { readonly reason: "query_parse_error"; readonly code: JsonRpcErrorCode.ValidationError; readonly when: "A conditions entry uses syntax the upstream Essie parser rejects — typically an unmatched `(` or `)`, or a `[` or `]` outside an AREA[…] expression."; readonly recovery: "Field-scoped search uses AREA[FieldName]value, which works in the free-text fields (query, conditionQuery, etc.) as well as in advancedFilter — call clinicaltrials_get_field_definitions to look up the right FieldName. A `[` or `]` outside an AREA[…] / RANGE[…] expression fails; `( )` group sub-expressions and are safe when matched; `,` acts as AND. Free-text fields otherwise take plain words plus AND, OR, NOT."; readonly thrownBy: "service"; }, { readonly reason: "request_too_long"; readonly code: JsonRpcErrorCode.ValidationError; readonly when: "The conditions list or location makes the request URL longer than ClinicalTrials.gov accepts — several hundred conditions in one call."; readonly recovery: "Shorten the longest inputs — a free-text query, advancedFilter, or a long fields or conditions list — or split a long list across several calls with fewer entries each, so the request URL fits within the length ClinicalTrials.gov accepts."; readonly thrownBy: "service"; }, { readonly reason: "rate_limited"; readonly code: JsonRpcErrorCode.RateLimited; readonly when: "ClinicalTrials.gov answered HTTP 429 on every attempt, or the call’s time budget ran out after a 429."; readonly recovery: "ClinicalTrials.gov rate-limited the request after several retries; wait about a minute before trying again."; readonly retryable: true; readonly thrownBy: "service"; }, { readonly reason: "retry_deadline_exceeded"; readonly code: JsonRpcErrorCode.Timeout; readonly when: "ClinicalTrials.gov did not answer within the call’s time budget, which covers every request, retry, and wait the call makes — the search and both funnel counts share it."; readonly recovery: "Retry after a minute or two. If the call asked for a lot at once — a large pageSize, many fields, or many nctIds — ask for less per call, or split the request across several calls."; readonly retryable: true; readonly thrownBy: "service"; }, { readonly reason: "upstream_timeout"; readonly code: JsonRpcErrorCode.Timeout; readonly when: "ClinicalTrials.gov answered HTTP 504 (gateway timeout) or 408 (request timeout), or sent no answer within the per-attempt timeout, on every attempt."; readonly recovery: "Retry after a few minutes. If it fails again, narrow the request — a more specific query or filter, a smaller pageSize, or fewer fields or nctIds — so ClinicalTrials.gov has less to compute and return."; readonly retryable: true; readonly thrownBy: "service"; }, { readonly reason: "upstream_unavailable"; readonly code: JsonRpcErrorCode.ServiceUnavailable; readonly when: "Every attempt failed on ClinicalTrials.gov’s side — HTTP 500, 502, or 503, a dropped connection or one the network gave up opening, or a 200 body that is not the JSON the route serves (an HTML page, unparseable text, the wrong shape) — or it answered with another 5xx, such as 505, or the connection was refused or its host name did not resolve, none of which is retried."; readonly recovery: "Retry the same call unchanged after a few minutes — the arguments were not at fault. If it keeps failing, ClinicalTrials.gov is down; tell the user rather than rewording the query."; readonly retryable: true; readonly thrownBy: "service"; }, { readonly reason: "upstream_rejected"; readonly code: JsonRpcErrorCode.ServiceUnavailable; readonly when: "ClinicalTrials.gov refused the request with a status its API does not use for a bad query — HTTP 501, a 3xx, or a 4xx such as 401, 403, or 410 — or answered with an HTML error page in place of its own 404."; readonly recovery: "Do not retry the same call right away or reword it — ClinicalTrials.gov refused it for a reason unrelated to the arguments, and it will refuse again. Tell the user the registry is not serving this request, and try again later."; readonly retryable: false; readonly thrownBy: "service"; }], { readonly searchCriteria: z.ZodObject<{ conditions: z.ZodArray; location: z.ZodString; age: z.ZodNumber; ageUnit: z.ZodOptional>; sex: z.ZodString; conditionQuery: z.ZodOptional; statusFilter: z.ZodOptional>; advancedFilter: z.ZodOptional; }, z.core.$strip>; readonly funnel: z.ZodObject<{ conditionMatched: z.ZodNumber; locationMatched: z.ZodNumber; demographicsMatched: z.ZodNumber; }, z.core.$strip>; readonly notice: z.ZodOptional; readonly truncated: z.ZodOptional; readonly shown: z.ZodOptional; readonly cap: z.ZodOptional; }>; //# sourceMappingURL=find-eligible.tool.d.ts.map