search_policies
Search Medicare coverage policies (LCDs, NCDs, Articles) to find coverage rules for procedures, conditions, or specific medical questions using keyword or semantic search.
Instructions
Search Medicare coverage policies (LCDs, NCDs, Articles). Use this to find policies related to procedures, conditions, or coverage questions. Supports keyword and semantic search modes.
Examples:
search_policies("ultrasound guidance") - find policies about ultrasound
search_policies("diabetes CGM") - find continuous glucose monitor policies
search_policies("", { policy_type: "NCD" }) - list all National Coverage Determinations
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search query - leave empty to browse | |
| mode | No | Search mode: keyword (exact) or semantic (conceptual) | keyword |
| policy_type | No | Filter by policy type | |
| jurisdiction | No | MAC jurisdiction code (e.g., JM, JH, JK) | |
| payer | No | Filter by payer name | |
| status | No | Policy status filter | active |
| limit | No | Results per page | |
| cursor | No | Pagination cursor from previous response | |
| include | No | Additional data: 'summary', 'criteria', 'codes' |
Implementation Reference
- src/index.ts:289-362 (registration)Registration of the 'search_policies' MCP tool, including description, input schema using Zod, and inline async handler function that queries the Verity API /policies endpoint and formats results.
server.registerTool( "search_policies", { description: `Search Medicare coverage policies (LCDs, NCDs, Articles). Use this to find policies related to procedures, conditions, or coverage questions. Supports keyword and semantic search modes. Examples: - search_policies("ultrasound guidance") - find policies about ultrasound - search_policies("diabetes CGM") - find continuous glucose monitor policies - search_policies("", { policy_type: "NCD" }) - list all National Coverage Determinations`, inputSchema: { query: z.string().max(500).optional().describe("Search query - leave empty to browse"), mode: z.enum(["keyword", "semantic"]).default("keyword").describe("Search mode: keyword (exact) or semantic (conceptual)"), policy_type: z .enum(["LCD", "Article", "NCD", "PayerPolicy", "Medical Policy", "Drug Policy"]) .optional() .describe("Filter by policy type"), jurisdiction: z.string().max(10).optional().describe("MAC jurisdiction code (e.g., JM, JH, JK)"), payer: z.string().max(50).optional().describe("Filter by payer name"), status: z.enum(["active", "retired", "all"]).default("active").describe("Policy status filter"), limit: z.number().min(1).max(100).default(20).describe("Results per page"), cursor: z.string().optional().describe("Pagination cursor from previous response"), include: z.string().optional().describe("Additional data: 'summary', 'criteria', 'codes'"), }, }, async ({ query, mode, policy_type, jurisdiction, payer, status, limit, cursor, include }) => { try { const result = await verityRequest<any>("/policies", { params: { q: query, mode, policy_type, jurisdiction, payer, status, limit, cursor, include, }, }); if (!result.data || result.data.length === 0) { return { content: [ { type: "text", text: `No policies found for "${query || "your search"}". Try:\n- Broader search terms\n- Different policy type\n- Remove jurisdiction filter`, }, ], }; } const lines: string[] = [`Found ${result.data.length} policies${result.meta?.pagination?.has_more ? " (more available)" : ""}:\n`]; result.data.forEach((policy: any, i: number) => { lines.push(`${i + 1}. ${formatPolicy(policy)}`); lines.push(""); }); if (result.meta?.pagination?.cursor) { lines.push(`\nMore results available. Use cursor: "${result.meta.pagination.cursor}"`); } return { content: [{ type: "text", text: lines.join("\n") }], }; } catch (error) { return { content: [{ type: "text", text: `Error searching policies: ${error instanceof Error ? error.message : String(error)}` }], }; } } ); - src/index.ts:315-361 (handler)Handler function for search_policies tool: destructures input params, calls verityRequest('/policies') with query parameters, handles empty results or errors, formats policy list using formatPolicy, and returns markdown-formatted text content.
async ({ query, mode, policy_type, jurisdiction, payer, status, limit, cursor, include }) => { try { const result = await verityRequest<any>("/policies", { params: { q: query, mode, policy_type, jurisdiction, payer, status, limit, cursor, include, }, }); if (!result.data || result.data.length === 0) { return { content: [ { type: "text", text: `No policies found for "${query || "your search"}". Try:\n- Broader search terms\n- Different policy type\n- Remove jurisdiction filter`, }, ], }; } const lines: string[] = [`Found ${result.data.length} policies${result.meta?.pagination?.has_more ? " (more available)" : ""}:\n`]; result.data.forEach((policy: any, i: number) => { lines.push(`${i + 1}. ${formatPolicy(policy)}`); lines.push(""); }); if (result.meta?.pagination?.cursor) { lines.push(`\nMore results available. Use cursor: "${result.meta.pagination.cursor}"`); } return { content: [{ type: "text", text: lines.join("\n") }], }; } catch (error) { return { content: [{ type: "text", text: `Error searching policies: ${error instanceof Error ? error.message : String(error)}` }], }; } } - src/index.ts:300-313 (schema)Zod inputSchema for validating parameters of the search_policies tool: query, mode, policy_type, jurisdiction, payer, status, limit, cursor, include.
inputSchema: { query: z.string().max(500).optional().describe("Search query - leave empty to browse"), mode: z.enum(["keyword", "semantic"]).default("keyword").describe("Search mode: keyword (exact) or semantic (conceptual)"), policy_type: z .enum(["LCD", "Article", "NCD", "PayerPolicy", "Medical Policy", "Drug Policy"]) .optional() .describe("Filter by policy type"), jurisdiction: z.string().max(10).optional().describe("MAC jurisdiction code (e.g., JM, JH, JK)"), payer: z.string().max(50).optional().describe("Filter by payer name"), status: z.enum(["active", "retired", "all"]).default("active").describe("Policy status filter"), limit: z.number().min(1).max(100).default(20).describe("Results per page"), cursor: z.string().optional().describe("Pagination cursor from previous response"), include: z.string().optional().describe("Additional data: 'summary', 'criteria', 'codes'"), }, - src/index.ts:107-163 (helper)formatPolicy helper function used by the search_policies handler to format policy data into readable markdown text, supporting detailed mode.
function formatPolicy(policy: any, detailed = false): string { const lines: string[] = []; lines.push(`Policy: ${policy.policy_id} - ${policy.title}`); lines.push(`Type: ${policy.policy_type} | Status: ${policy.status}`); if (policy.jurisdiction) lines.push(`Jurisdiction: ${policy.jurisdiction}`); if (policy.effective_date) lines.push(`Effective: ${policy.effective_date}`); if (policy.retire_date) lines.push(`Retired: ${policy.retire_date}`); if (detailed) { if (policy.description) lines.push(`\nDescription: ${policy.description}`); if (policy.summary) lines.push(`\nSummary: ${policy.summary}`); if (policy.mac) { lines.push(`\nMAC: ${policy.mac.name} (${policy.mac.jurisdiction_name})`); if (policy.mac.states) lines.push(`States: ${policy.mac.states.join(", ")}`); } if (policy.sections) { if (policy.sections.indications) { lines.push(`\n--- Indications ---\n${policy.sections.indications.slice(0, 1000)}${policy.sections.indications.length > 1000 ? "..." : ""}`); } if (policy.sections.limitations) { lines.push(`\n--- Limitations ---\n${policy.sections.limitations.slice(0, 1000)}${policy.sections.limitations.length > 1000 ? "..." : ""}`); } if (policy.sections.documentation) { lines.push(`\n--- Documentation Requirements ---\n${policy.sections.documentation.slice(0, 1000)}${policy.sections.documentation.length > 1000 ? "..." : ""}`); } } if (policy.criteria && Object.keys(policy.criteria).length > 0) { lines.push("\n--- Coverage Criteria ---"); Object.entries(policy.criteria).forEach(([section, blocks]: [string, any]) => { lines.push(`\n[${section.toUpperCase()}]`); blocks.slice(0, 3).forEach((block: any) => { lines.push(` - ${block.text.slice(0, 200)}${block.text.length > 200 ? "..." : ""}`); if (block.tags?.length) lines.push(` Tags: ${block.tags.join(", ")}`); }); if (blocks.length > 3) lines.push(` ... and ${blocks.length - 3} more criteria`); }); } if (policy.codes && Object.keys(policy.codes).length > 0) { lines.push("\n--- Associated Codes ---"); Object.entries(policy.codes).forEach(([system, codes]: [string, any]) => { lines.push(`\n[${system}] (${codes.length} codes)`); codes.slice(0, 10).forEach((c: any) => { lines.push(` - ${c.code}: ${c.display || "No description"} [${c.disposition}]`); }); if (codes.length > 10) lines.push(` ... and ${codes.length - 10} more codes`); }); } } if (policy.source_url) lines.push(`\nSource: ${policy.source_url}`); return lines.join("\n"); } - src/index.ts:25-66 (helper)verityRequest helper function used by all tools including search_policies to make authenticated API requests to the Verity API backend.
async function verityRequest<T>( endpoint: string, options: { method?: "GET" | "POST"; params?: Record<string, string | number | boolean | undefined>; body?: unknown; } = {} ): Promise<T> { const { method = "GET", params, body } = options; // Build URL with query params const url = new URL(`${VERITY_API_BASE}${endpoint}`); if (params) { Object.entries(params).forEach(([key, value]) => { if (value !== undefined && value !== null && value !== "") { url.searchParams.append(key, String(value)); } }); } const headers: Record<string, string> = { Authorization: `Bearer ${VERITY_API_KEY}`, "Content-Type": "application/json", Accept: "application/json", }; const response = await fetch(url.toString(), { method, headers, body: body ? JSON.stringify(body) : undefined, }); const data = await response.json(); if (!response.ok) { const errorMsg = data.error?.message || `API error: ${response.status}`; const hint = data.error?.hint || ""; throw new Error(hint ? `${errorMsg}. Hint: ${hint}` : errorMsg); } return data as T; }