Screen Companies
screen_companiesFilter companies using financial metrics, industry codes, IP activity, litigation status, and risk scores to identify targets matching specific criteria.
Instructions
Screen companies using financial, industry, IP, and litigation filters. Combine SIC industry codes, revenue/asset brackets, shell risk scores, patent/trademark/litigation flags, and short interest levels. Cross-references SEC, OTC, Patents, Trademarks, and PACER datasets.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sic_code | No | SIC industry code (e.g. '7372' for software) | |
| industry | No | Industry keyword search (partial match) | |
| min_revenue | No | Minimum revenue in USD | |
| max_revenue | No | Maximum revenue in USD | |
| min_assets | No | Minimum total assets in USD | |
| max_assets | No | Maximum total assets in USD | |
| max_shell_risk | No | Maximum shell risk score (0-100) | |
| min_filing_recency | No | Minimum filing recency score (0-100) | |
| has_patents | No | Filter to companies with patent activity | |
| has_trademarks | No | Filter to companies with trademark registrations | |
| has_litigation | No | Filter to companies with court cases | |
| min_short_interest | No | Minimum short interest ratio | |
| sort_by | No | Sort field: revenue, assets, shell_risk, filing_recency, short_interest | |
| limit | No | Maximum results (default 25, max 100) |
Implementation Reference
- src/tools/company.ts:138-181 (handler)Handler logic for screen_companies tool execution.
async (params) => { const queryParams: Record<string, string | number | undefined> = { sic_code: params.sic_code, industry: params.industry, min_revenue: params.min_revenue, max_revenue: params.max_revenue, min_assets: params.min_assets, max_assets: params.max_assets, max_shell_risk: params.max_shell_risk, min_filing_recency: params.min_filing_recency, has_patents: params.has_patents != null ? String(params.has_patents) : undefined, has_trademarks: params.has_trademarks != null ? String(params.has_trademarks) : undefined, has_litigation: params.has_litigation != null ? String(params.has_litigation) : undefined, min_short_interest: params.min_short_interest, sort_by: params.sort_by, limit: params.limit ?? 25, }; const res = await apiGet<{ dataset: string; count: number; data: Record<string, unknown>[] }>( "/api/v1/companies/screen", queryParams, ); if (!res.ok) { return { content: [ { type: "text" as const, text: `API error (${res.status}): ${JSON.stringify(res.data)}`, }, ], isError: true, }; } const { count, data } = res.data; const summary = `Found ${count} company/companies matching filters.`; const json = JSON.stringify(data, null, 2); return { content: [{ type: "text" as const, text: `${summary}\n\n${json}` }], }; }, ); - src/tools/company.ts:63-136 (schema)Input schema definition for the screen_companies tool.
{ title: "Screen Companies", description: "Screen companies using financial, industry, IP, and litigation filters. " + "Combine SIC industry codes, revenue/asset brackets, shell risk scores, " + "patent/trademark/litigation flags, and short interest levels. " + "Cross-references SEC, OTC, Patents, Trademarks, and PACER datasets.", inputSchema: { sic_code: z .string() .optional() .describe("SIC industry code (e.g. '7372' for software)"), industry: z .string() .optional() .describe("Industry keyword search (partial match)"), min_revenue: z .number() .optional() .describe("Minimum revenue in USD"), max_revenue: z .number() .optional() .describe("Maximum revenue in USD"), min_assets: z .number() .optional() .describe("Minimum total assets in USD"), max_assets: z .number() .optional() .describe("Maximum total assets in USD"), max_shell_risk: z .number() .int() .min(0) .max(100) .optional() .describe("Maximum shell risk score (0-100)"), min_filing_recency: z .number() .int() .min(0) .max(100) .optional() .describe("Minimum filing recency score (0-100)"), has_patents: z .boolean() .optional() .describe("Filter to companies with patent activity"), has_trademarks: z .boolean() .optional() .describe("Filter to companies with trademark registrations"), has_litigation: z .boolean() .optional() .describe("Filter to companies with court cases"), min_short_interest: z .number() .optional() .describe("Minimum short interest ratio"), sort_by: z .string() .optional() .describe("Sort field: revenue, assets, shell_risk, filing_recency, short_interest"), limit: z .number() .int() .min(1) .max(100) .optional() .describe("Maximum results (default 25, max 100)"), }, - src/tools/company.ts:61-181 (registration)Registration of the screen_companies tool in the MCP server.
server.registerTool( "screen_companies", { title: "Screen Companies", description: "Screen companies using financial, industry, IP, and litigation filters. " + "Combine SIC industry codes, revenue/asset brackets, shell risk scores, " + "patent/trademark/litigation flags, and short interest levels. " + "Cross-references SEC, OTC, Patents, Trademarks, and PACER datasets.", inputSchema: { sic_code: z .string() .optional() .describe("SIC industry code (e.g. '7372' for software)"), industry: z .string() .optional() .describe("Industry keyword search (partial match)"), min_revenue: z .number() .optional() .describe("Minimum revenue in USD"), max_revenue: z .number() .optional() .describe("Maximum revenue in USD"), min_assets: z .number() .optional() .describe("Minimum total assets in USD"), max_assets: z .number() .optional() .describe("Maximum total assets in USD"), max_shell_risk: z .number() .int() .min(0) .max(100) .optional() .describe("Maximum shell risk score (0-100)"), min_filing_recency: z .number() .int() .min(0) .max(100) .optional() .describe("Minimum filing recency score (0-100)"), has_patents: z .boolean() .optional() .describe("Filter to companies with patent activity"), has_trademarks: z .boolean() .optional() .describe("Filter to companies with trademark registrations"), has_litigation: z .boolean() .optional() .describe("Filter to companies with court cases"), min_short_interest: z .number() .optional() .describe("Minimum short interest ratio"), sort_by: z .string() .optional() .describe("Sort field: revenue, assets, shell_risk, filing_recency, short_interest"), limit: z .number() .int() .min(1) .max(100) .optional() .describe("Maximum results (default 25, max 100)"), }, }, async (params) => { const queryParams: Record<string, string | number | undefined> = { sic_code: params.sic_code, industry: params.industry, min_revenue: params.min_revenue, max_revenue: params.max_revenue, min_assets: params.min_assets, max_assets: params.max_assets, max_shell_risk: params.max_shell_risk, min_filing_recency: params.min_filing_recency, has_patents: params.has_patents != null ? String(params.has_patents) : undefined, has_trademarks: params.has_trademarks != null ? String(params.has_trademarks) : undefined, has_litigation: params.has_litigation != null ? String(params.has_litigation) : undefined, min_short_interest: params.min_short_interest, sort_by: params.sort_by, limit: params.limit ?? 25, }; const res = await apiGet<{ dataset: string; count: number; data: Record<string, unknown>[] }>( "/api/v1/companies/screen", queryParams, ); if (!res.ok) { return { content: [ { type: "text" as const, text: `API error (${res.status}): ${JSON.stringify(res.data)}`, }, ], isError: true, }; } const { count, data } = res.data; const summary = `Found ${count} company/companies matching filters.`; const json = JSON.stringify(data, null, 2); return { content: [{ type: "text" as const, text: `${summary}\n\n${json}` }], }; }, );