search_by_eligibility_criteria

Find clinical trials matching specific eligibility requirements like age, condition, and inclusion/exclusion criteria to identify suitable studies for patients or research.

Instructions

Advanced search based on detailed eligibility criteria

Input Schema

TableJSON Schema

Name	Required	Description
`minAge`	No	Minimum age (e.g., "18 Years", "6 Months")
`maxAge`	No	Maximum age (e.g., "65 Years", "12 Years")
`sex`	No	Sex eligibility
`healthyVolunteers`	No	Whether study accepts healthy volunteers
`condition`	No	Medical condition filter
`exclusionKeywords`	No	Keywords that should NOT appear in eligibility criteria
`inclusionKeywords`	No	Keywords that should appear in eligibility criteria
`pageSize`	No	Number of results to return (default 10, max 100)

Implementation Reference

build/index.js:1609-1695 (handler)

The handleSearchByEligibilityCriteria method implements the tool logic, including optional exclusion keyword filtering which is done client-side after the API call.

async handleSearchByEligibilityCriteria(args) {
    const params = {
        format: "json",
        pageSize: args?.pageSize || 10,
    };
    if (args?.minAge) {
        params["filter.minimumAge"] = args.minAge;
    }
    if (args?.maxAge) {
        params["filter.maximumAge"] = args.maxAge;
    }
    if (args?.sex) {
        params["filter.sex"] = args.sex;
    }
    if (args?.healthyVolunteers !== undefined) {
        params["filter.healthyVolunteers"] = args.healthyVolunteers;
    }
    if (args?.condition) {
        params["query.cond"] = args.condition;
    }
    if (args?.inclusionKeywords) {
        params["query.eligibility"] = args.inclusionKeywords;
    }
    try {
        const response = await this.axiosInstance.get("/studies", { params });
        const studies = response.data.studies || [];
        let filteredStudies = studies;
        // Apply exclusion keyword filtering if specified
        if (args?.exclusionKeywords) {
            const exclusionWords = args.exclusionKeywords
                .toLowerCase()
                .split(/\s+/);
            filteredStudies = studies.filter((study) => {
                const eligibilityCriteria = study.protocolSection.eligibilityModule?.eligibilityCriteria?.toLowerCase() ||
                    "";
                return !exclusionWords.some((word) => eligibilityCriteria.includes(word));
            });
        }
        const results = filteredStudies.map((study) => ({
            ...this.formatStudySummary(study),
            eligibility: {
                sex: study.protocolSection.eligibilityModule?.sex || "Unknown",
                minimumAge: study.protocolSection.eligibilityModule?.minimumAge ||
                    "Not specified",
                maximumAge: study.protocolSection.eligibilityModule?.maximumAge ||
                    "Not specified",
                healthyVolunteers: study.protocolSection.eligibilityModule?.healthyVolunteers || false,
                criteriaPreview: study.protocolSection.eligibilityModule?.eligibilityCriteria?.substring(0, 200) + "..." || "Not available",
            },
        }));
        return {
            content: [
                {
                    type: "text",
                    text: JSON.stringify({
                        searchCriteria: {
                            minAge: args?.minAge,
                            maxAge: args?.maxAge,
                            sex: args?.sex,
                            healthyVolunteers: args?.healthyVolunteers,
                            condition: args?.condition,
                            inclusionKeywords: args?.inclusionKeywords,
                            exclusionKeywords: args?.exclusionKeywords,
                        },
                        totalCount: response.data.totalCount || 0,
                        resultsShown: results.length,
                        studies: results,
                    }, null, 2),
                },
            ],
        };
    }
    catch (error) {
        if (axios.isAxiosError(error)) {
            return {
                content: [
                    {
                        type: "text",
                        text: `Clinical Trials API error: ${error.response?.data?.message || error.message}`,
                    },
                ],
                isError: true,
            };
        }
        throw error;
    }
}

build/index.js:492-534 (registration)

The tool search_by_eligibility_criteria is registered in the setupToolHandlers method with its schema definition.

    name: "search_by_eligibility_criteria",
    description: "Advanced search based on detailed eligibility criteria",
    inputSchema: {
        type: "object",
        properties: {
            minAge: {
                type: "string",
                description: 'Minimum age (e.g., "18 Years", "6 Months")',
            },
            maxAge: {
                type: "string",
                description: 'Maximum age (e.g., "65 Years", "12 Years")',
            },
            sex: {
                type: "string",
                description: "Sex eligibility",
                enum: ["ALL", "FEMALE", "MALE"],
            },
            healthyVolunteers: {
                type: "boolean",
                description: "Whether study accepts healthy volunteers",
            },
            condition: {
                type: "string",
                description: "Medical condition filter",
            },
            exclusionKeywords: {
                type: "string",
                description: "Keywords that should NOT appear in eligibility criteria",
            },
            inclusionKeywords: {
                type: "string",
                description: "Keywords that should appear in eligibility criteria",
            },
            pageSize: {
                type: "number",
                description: "Number of results to return (default 10, max 100)",
                minimum: 1,
                maximum: 100,
            },
        },
    },
},

Clinical Trials MCP Server