Verilex Data

Instructions

Implementation Reference

• src/tools/otc.ts:31-111 (handler)

  Registration and handler implementation for the query_otc_companies tool. It defines the input schema using Zod and handles the tool execution by making an API request to the backend.

  server.registerTool(
    "query_otc_companies",
    {
      title: "Query OTC Companies",
      description:
        "Search OTC-traded companies from SEC EDGAR. Filter by ticker, company name, " +
        "financial metrics, shell risk score, and filing recency. Includes derived analytics " +
        "like shell risk flags and filing recency scores. ~4,000-6,000 companies. " +
        "Source: SEC EDGAR + FINRA, updated daily.",
      inputSchema: {
        ticker: z
          .string()
          .optional()
          .describe("Ticker symbol (partial match, e.g. ACME)"),
        company_name: z
          .string()
          .optional()
          .describe("Company name (partial match)"),
        has_financials: z
          .boolean()
          .optional()
          .describe("Filter to companies with SEC XBRL financial data"),
        min_filing_recency: z
          .number()
          .int()
          .min(0)
          .max(100)
          .optional()
          .describe("Minimum filing recency score (0-100, higher = more recent filings)"),
        max_shell_risk: z
          .number()
          .int()
          .min(0)
          .max(100)
          .optional()
          .describe("Maximum shell risk score (0-100, lower = less likely to be a shell)"),
        min_revenue: z
          .number()
          .optional()
          .describe("Minimum revenue in USD (from latest SEC XBRL filing)"),
        limit: z
          .number()
          .int()
          .min(1)
          .max(100)
          .optional()
          .describe("Maximum number of results to return (default 25, max 100)"),
      },
    },
    async ({ ticker, company_name, has_financials, min_filing_recency, max_shell_risk, min_revenue, limit }) => {
      const res = await apiGet<OtcQueryResponse>("/api/v1/otc", {
        ticker,
        company_name,
        has_financials: has_financials != null ? String(has_financials) : undefined,
        min_filing_recency,
        max_shell_risk,
        min_revenue,
        limit: limit ?? 25,
      });
  
      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} OTC company/companies.`;
      const json = JSON.stringify(data, null, 2);
  
      return {
        content: [{ type: "text" as const, text: `${summary}\n\n${json}` }],
      };
    },
  );