fmp-ai-tools 0.2.4-beta.0 → 0.2.4-beta.2

package/README.md

@@ -339,6 +339,8 @@ Each tool accepts specific parameters. Here are some common ones:
 - `from` - Start date in YYYY-MM-DD format
 - `to` - End date in YYYY-MM-DD format
 - `name` - For economic indicators: specific indicator name
+- `limit` - Max rows returned by tools that wrap large list endpoints (earnings/economic calendars, institutional and ETF holdings, market performance, executive compensation, congressional trades by name; defaults 20–50). When rows are cut, the tool returns `{ data, truncated: true, note }` saying how many rows exist. Institutional holders (latest filing per holder from the past year) and ETF holdings (latest filing date by default) are sorted largest-first.
+- `symbols` - `getEarningsCalendar` only: return just these companies (a week can hold ~2,000 worldwide)
 
 ## Error Handling
 

package/dist/providers/openai/index.js

@@ -192,6 +192,25 @@ function toToolResponse(res) {
   }
   return JSON.stringify(res.data, null, 2);
 }
+function limitRows(res, limit2, compare) {
+  if (res.success === false || !Array.isArray(res.data)) return res;
+  const rows = compare ? [...res.data].sort(compare) : res.data;
+  return { ...res, data: rows.slice(0, limit2) };
+}
+function toCappedToolResponse(res, limit2, options = {}) {
+  const total = res.success !== false && Array.isArray(res.data) ? res.data.length : 0;
+  const capped = limitRows(res, limit2, options.compare);
+  if (total <= limit2) return toToolResponse(capped);
+  return JSON.stringify(
+    {
+      data: capped.data,
+      truncated: true,
+      note: `Showing ${limit2} of ${total} rows. ${options.hint ?? "Increase `limit` to see more."}`
+    },
+    null,
+    2
+  );
+}
 function toToolError(error) {
   const message = error instanceof Error ? error.message : String(error);
   let type = "unknown";
@@ -273,7 +292,7 @@ var quoteDefinitions = [
       to: zod.z.string().optional().nullable().describe("End date in YYYY-MM-DD format (optional)"),
       limit: zod.z.number().int().positive().default(30).describe("Max number of most-recent days to return (default 30)")
     }),
-    execute: async ({ symbol: symbol2, from, to, limit: limit2 = 30 }) => {
+    execute: async ({ symbol: symbol2, from, to, limit: limit2 }) => {
       const res = await getFMPClient().quote.getHistoricalPrice({
         symbol: symbol2,
         from: from ?? void 0,
@@ -283,7 +302,7 @@ var quoteDefinitions = [
       if (res.success && data && Array.isArray(data.historical)) {
         return toToolResponse({
           ...res,
-          data: { ...data, historical: data.historical.slice(0, limit2) }
+          data: { ...data, historical: data.historical.slice(0, limit2 ?? 30) }
         });
       }
       return toToolResponse(res);
@@ -299,7 +318,7 @@ var quoteDefinitions = [
       to: zod.z.string().optional().nullable().describe("End date in YYYY-MM-DD format (optional)"),
       limit: zod.z.number().int().positive().default(50).describe("Max number of most-recent bars to return (default 50)")
     }),
-    execute: async ({ symbol: symbol2, interval = "5min", from, to, limit: limit2 = 50 }) => {
+    execute: async ({ symbol: symbol2, interval = "5min", from, to, limit: limit2 }) => {
       const res = await getFMPClient().quote.getIntraday({
         symbol: symbol2,
         interval,
@@ -307,7 +326,7 @@ var quoteDefinitions = [
         to: to ?? void 0
       });
       if (res.success && Array.isArray(res.data)) {
-        return toToolResponse({ ...res, data: res.data.slice(0, limit2) });
+        return toToolResponse({ ...res, data: res.data.slice(0, limit2 ?? 50) });
       }
       return toToolResponse(res);
     }
@@ -331,9 +350,11 @@ var companyDefinitions = [
   }),
   defineTool({
     name: "getCompanyExecutiveCompensation",
-    description: "Get the company executive compensation",
-    inputSchema: symbolSchema,
-    execute: async ({ symbol: symbol2 }) => toToolResponse(await getFMPClient().company.getExecutiveCompensation(symbol2))
+    description: "Get the company executive compensation (at most `limit` records)",
+    inputSchema: symbolSchema.extend({
+      limit: zod.z.number().int().positive().default(20).describe("Max number of compensation records to return (default 20)")
+    }),
+    execute: async ({ symbol: symbol2, limit: limit2 }) => toCappedToolResponse(await getFMPClient().company.getExecutiveCompensation(symbol2), limit2 ?? 20)
   }),
   defineTool({
     name: "getStockPeers",
@@ -349,7 +370,7 @@ var statementTool = (name, description, what, call) => defineTool({
   name,
   description,
   inputSchema: zod.z.object({ symbol: symbol(what), period, limit }),
-  execute: async ({ symbol: symbol2, period: period2, limit: limit2 }) => toToolResponse(await call({ symbol: symbol2, period: period2, limit: limit2 }))
+  execute: async ({ symbol: symbol2, period: period2, limit: limit2 }) => toToolResponse(await call({ symbol: symbol2, period: period2, limit: limit2 ?? void 0 }))
 });
 var financialDefinitions = [
   statementTool(
@@ -378,7 +399,7 @@ var financialDefinitions = [
   ),
   statementTool(
     "getFinancialRatios",
-    "Get financial ratios for a company including profitability, liquidity, and efficiency metrics",
+    "Get financial ratios for a company by period: valuation (P/E incl. diluted P/E, PEG, P/B, P/S, P/FCF, EV multiple), profitability margins, liquidity, leverage, efficiency, and per-share metrics",
     "financial ratios",
     (args) => getFMPClient().financial.getFinancialRatios(args)
   ),
@@ -419,7 +440,9 @@ var financialDefinitions = [
       symbol: symbol("earnings historical"),
       limit: zod.z.number().default(10).describe("The number of periods to retrieve")
     }),
-    execute: async ({ symbol: symbol2, limit: limit2 }) => toToolResponse(await getFMPClient().financial.getEarningsHistorical({ symbol: symbol2, limit: limit2 }))
+    execute: async ({ symbol: symbol2, limit: limit2 }) => toToolResponse(
+      await getFMPClient().financial.getEarningsHistorical({ symbol: symbol2, limit: limit2 ?? 10 })
+    )
   }),
   defineTool({
     name: "getFinancialScores",
@@ -435,7 +458,7 @@ var financialDefinitions = [
   }),
   defineTool({
     name: "getFinancialRatiosTTM",
-    description: "Get current trailing-twelve-month (TTM) financial ratios for a company (margins, returns, liquidity)",
+    description: "Get current trailing-twelve-month (TTM) financial ratios for a company (one snapshot row): valuation (P/E incl. diluted P/E, PEG, P/B, P/S, P/FCF, EV multiple), margins, liquidity, leverage, and per-share metrics",
     inputSchema: zod.z.object({ symbol: symbol("TTM financial ratios") }),
     execute: async ({ symbol: symbol2 }) => toToolResponse(await getFMPClient().financial.getFinancialRatiosTTM({ symbol: symbol2 }))
   }),
@@ -458,29 +481,39 @@ var financialDefinitions = [
 ];
 var dateRangeSchema = zod.z.object({
   from: zod.z.string().optional().nullable().describe("Start date in YYYY-MM-DD format (optional)"),
-  to: zod.z.string().optional().nullable().describe("End date in YYYY-MM-DD format (optional)")
+  to: zod.z.string().optional().nullable().describe("End date in YYYY-MM-DD format (optional)"),
+  limit: zod.z.number().int().positive().default(50).describe("Max number of entries to return (default 50)")
 });
 var calendarDefinitions = [
   defineTool({
     name: "getEarningsCalendar",
-    description: "Get earnings calendar showing upcoming and recent earnings announcements",
-    inputSchema: dateRangeSchema,
-    execute: async ({ from, to }) => toToolResponse(
-      await getFMPClient().calendar.getEarningsCalendar({
+    description: "Get earnings calendar showing upcoming and recent earnings announcements, in date order. A week can hold ~2,000 companies worldwide, so pass `symbols` to look up specific companies (e.g. mega-cap tech) instead of scanning the whole calendar.",
+    inputSchema: dateRangeSchema.extend({
+      symbols: zod.z.array(zod.z.string().min(1)).optional().nullable().describe('Only return these symbols (e.g., ["AAPL", "MSFT", "NVDA"])')
+    }),
+    execute: async ({ from, to, symbols, limit: limit2 }) => {
+      const res = await getFMPClient().calendar.getEarningsCalendar({
         from: from ?? void 0,
         to: to ?? void 0
-      })
-    )
+      });
+      const wanted = symbols?.length ? new Set(symbols.map((s) => s.toUpperCase())) : null;
+      const filtered = wanted && res.success !== false && Array.isArray(res.data) ? { ...res, data: res.data.filter((row) => wanted.has(row.symbol.toUpperCase())) } : res;
+      return toCappedToolResponse(filtered, limit2 ?? 50, {
+        hint: "Rows are in date order. Pass `symbols` to find specific companies, or narrow the date range."
+      });
+    }
   }),
   defineTool({
     name: "getEconomicCalendar",
-    description: "Get economic calendar showing upcoming and recent economic events and indicators",
+    description: "Get economic calendar showing upcoming and recent economic events and indicators, in date order (at most `limit` entries; narrow the date range for full coverage)",
     inputSchema: dateRangeSchema,
-    execute: async ({ from, to }) => toToolResponse(
+    execute: async ({ from, to, limit: limit2 }) => toCappedToolResponse(
       await getFMPClient().calendar.getEconomicsCalendar({
         from: from ?? void 0,
         to: to ?? void 0
-      })
+      }),
+      limit2 ?? 50,
+      { hint: "Rows are in date order; narrow the date range to see the rest." }
     )
   })
 ];
@@ -544,17 +577,32 @@ var economicDefinitions = [
 var etfDefinitions = [
   defineTool({
     name: "getETFHoldings",
-    description: "Get ETF holdings for a specific ETF symbol, showing the underlying assets and their weights",
+    description: "Get the largest holdings of an ETF (by portfolio weight), showing the underlying assets and their weights",
     inputSchema: zod.z.object({
       symbol: zod.z.string().min(1, "ETF symbol is required").describe("ETF symbol (e.g., SPY, QQQ, VTI)"),
-      date: zod.z.string().optional().nullable().describe("Date for holdings in YYYY-MM-DD format (optional)")
+      date: zod.z.string().optional().nullable().describe("Holdings date in YYYY-MM-DD format (optional; defaults to the latest filing)"),
+      limit: zod.z.number().int().positive().default(50).describe("Max number of holdings to return, largest weight first (default 50)")
     }),
-    execute: async ({ symbol: symbol2, date }) => {
+    execute: async ({ symbol: symbol2, date, limit: limit2 }) => {
+      const client = getFMPClient();
+      let holdingsDate = date ?? void 0;
+      if (!holdingsDate) {
+        const dates = await client.etf.getHoldingDates(symbol2);
+        if (dates.success !== false && Array.isArray(dates.data)) {
+          holdingsDate = dates.data.reduce(
+            (latest, d) => !latest || d.date > latest ? d.date : latest,
+            void 0
+          );
+        }
+      }
       const params = { symbol: symbol2 };
-      if (date) {
-        params.date = date;
+      if (holdingsDate) {
+        params.date = holdingsDate;
       }
-      return toToolResponse(await getFMPClient().etf.getHoldings(params));
+      return toCappedToolResponse(await client.etf.getHoldings(params), limit2 ?? 50, {
+        compare: (a, b) => b.pctVal - a.pctVal,
+        hint: `Largest positions first, as of ${holdingsDate ?? "the requested date"}.`
+      });
     }
   }),
   defineTool({
@@ -577,14 +625,36 @@ var insiderDefinitions = [
     execute: async ({ symbol: symbol2, page }) => toToolResponse(await getFMPClient().insider.getInsiderTradesBySymbol(symbol2, page))
   })
 ];
+var YEAR_MS = 365 * 24 * 60 * 60 * 1e3;
+var holderKey = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, " ").replace(/\b(inc|corp|corporation|co|llc|ltd|lp|plc|the)\b/g, " ").replace(/\s+/g, " ").trim();
+function currentHolders(rows) {
+  const newest = rows.reduce((max, r) => Math.max(max, Date.parse(r.dateReported) || 0), 0);
+  const latest = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const reported = Date.parse(row.dateReported);
+    if (!(reported >= newest - YEAR_MS)) continue;
+    const key = holderKey(row.holder);
+    const prev = latest.get(key);
+    if (!prev || reported > Date.parse(prev.dateReported)) latest.set(key, row);
+  }
+  return [...latest.values()];
+}
 var institutionalDefinitions = [
   defineTool({
     name: "getInstitutionalHolders",
-    description: "Get institutional holders for a specific stock symbol showing which institutions own shares and their holdings",
+    description: "Get a stock's largest current institutional holders by shares held (each holder's latest 13F filing from the past year)",
     inputSchema: zod.z.object({
-      symbol: zod.z.string().min(1, "Stock symbol is required").describe("Stock symbol (e.g., AAPL, MSFT, GOOGL)")
+      symbol: zod.z.string().min(1, "Stock symbol is required").describe("Stock symbol (e.g., AAPL, MSFT, GOOGL)"),
+      limit: zod.z.number().int().positive().default(20).describe("Max number of holders to return, largest first (default 20)")
     }),
-    execute: async ({ symbol: symbol2 }) => toToolResponse(await getFMPClient().institutional.getInstitutionalHolders({ symbol: symbol2 }))
+    execute: async ({ symbol: symbol2, limit: limit2 }) => {
+      const res = await getFMPClient().institutional.getInstitutionalHolders({ symbol: symbol2 });
+      const current = res.success !== false && Array.isArray(res.data) ? { ...res, data: currentHolders(res.data) } : res;
+      return toCappedToolResponse(current, limit2 ?? 20, {
+        compare: (a, b) => b.shares - a.shares,
+        hint: "Holders are ordered by shares held, largest first."
+      });
+    }
   })
 ];
 var empty = zod.z.object({});
@@ -595,9 +665,11 @@ var snapshotDateSchema = zod.z.object({
 var marketDefinitions = [
   defineTool({
     name: "getMarketPerformance",
-    description: "Get overall market performance data including major indices performance",
-    inputSchema: empty,
-    execute: async () => toToolResponse(await getFMPClient().market.getMarketPerformance())
+    description: "Get overall market performance data including major indices performance (at most `limit` indices)",
+    inputSchema: zod.z.object({
+      limit: zod.z.number().int().positive().default(50).describe("Max number of indices to return (default 50)")
+    }),
+    execute: async ({ limit: limit2 }) => toCappedToolResponse(await getFMPClient().market.getMarketPerformance(), limit2 ?? 50)
   }),
   defineTool({
     name: "getSectorPerformance",
@@ -649,11 +721,11 @@ var newsDefinitions = [
       to: zod.z.string().optional().nullable().describe("End date in YYYY-MM-DD format (optional)"),
       limit: zod.z.number().int().positive().default(20).describe("Max number of articles to return (default 20)")
     }),
-    execute: async ({ from, to, limit: limit2 = 20 }) => toToolResponse(
+    execute: async ({ from, to, limit: limit2 }) => toToolResponse(
       await getFMPClient().news.getStockNews({
         from: from ?? void 0,
         to: to ?? void 0,
-        limit: limit2
+        limit: limit2 ?? 20
       })
     )
   }),
@@ -666,12 +738,12 @@ var newsDefinitions = [
       to: zod.z.string().optional().nullable().describe("End date in YYYY-MM-DD format (optional)"),
       limit: zod.z.number().int().positive().default(20).describe("Max number of articles to return (default 20)")
     }),
-    execute: async ({ symbols, from, to, limit: limit2 = 20 }) => toToolResponse(
+    execute: async ({ symbols, from, to, limit: limit2 }) => toToolResponse(
       await getFMPClient().news.getStockNewsBySymbol({
         symbols,
         from: from ?? void 0,
         to: to ?? void 0,
-        limit: limit2
+        limit: limit2 ?? 20
       })
     )
   })
@@ -693,8 +765,8 @@ var screenerDefinitions = [
       isActivelyTrading: zod.z.boolean().optional().nullable().describe("Restrict to actively trading"),
       limit: zod.z.number().int().positive().default(50).describe("Max number of results to return (default 50)")
     }),
-    execute: async ({ limit: limit2 = 50, ...filters }) => {
-      const params = { limit: limit2 };
+    execute: async ({ limit: limit2, ...filters }) => {
+      const params = { limit: limit2 ?? 50 };
       for (const [key, value] of Object.entries(filters)) {
         if (value !== null && value !== void 0) params[key] = value;
       }
@@ -711,8 +783,12 @@ var searchDefinitions = [
       limit: zod.z.number().int().positive().default(10).describe("Max number of results to return (default 10)"),
       exchange: zod.z.string().optional().nullable().describe('Restrict to a specific exchange (optional, e.g., "NASDAQ")')
     }),
-    execute: async ({ query, limit: limit2 = 10, exchange }) => toToolResponse(
-      await getFMPClient().search.search({ query, limit: limit2, exchange: exchange ?? void 0 })
+    execute: async ({ query, limit: limit2, exchange }) => toToolResponse(
+      await getFMPClient().search.search({
+        query,
+        limit: limit2 ?? 10,
+        exchange: exchange ?? void 0
+      })
     )
   })
 ];
@@ -725,7 +801,9 @@ var analystDefinitions = [
       period: zod.z.enum(["annual", "quarter"]).default("annual").describe("The period type (annual or quarter)"),
       limit: zod.z.number().int().positive().default(10).describe("Max number of periods to return (default 10)")
     }),
-    execute: async ({ symbol: symbol2, period: period2 = "annual", limit: limit2 = 10 }) => toToolResponse(await getFMPClient().analyst.getEstimates({ symbol: symbol2, period: period2, limit: limit2 }))
+    execute: async ({ symbol: symbol2, period: period2 = "annual", limit: limit2 }) => toToolResponse(
+      await getFMPClient().analyst.getEstimates({ symbol: symbol2, period: period2, limit: limit2 ?? 10 })
+    )
   }),
   defineTool({
     name: "getPriceTargetConsensus",
@@ -742,10 +820,10 @@ var analystDefinitions = [
       symbol: zod.z.string().min(1).describe("The stock symbol (e.g., AAPL)"),
       limit: zod.z.number().int().positive().default(20).describe("Max number of grade entries to return (default 20)")
     }),
-    execute: async ({ symbol: symbol2, limit: limit2 = 20 }) => {
+    execute: async ({ symbol: symbol2, limit: limit2 }) => {
       const res = await getFMPClient().analyst.getGrades({ symbol: symbol2 });
       if (res.success && Array.isArray(res.data)) {
-        return toToolResponse({ ...res, data: res.data.slice(0, limit2) });
+        return toToolResponse({ ...res, data: res.data.slice(0, limit2 ?? 20) });
       }
       return toToolResponse(res);
     }
@@ -787,7 +865,7 @@ var technicalDefinitions = [
       timeframe: zod.z.enum(["1min", "5min", "15min", "30min", "1hour", "4hour", "1day", "1week", "1month"]).default("1day").describe("Bar timeframe"),
       limit: zod.z.number().int().positive().default(50).describe("Max number of most-recent bars to return (default 50)")
     }),
-    execute: async ({ symbol: symbol2, type, periodLength = 10, timeframe = "1day", limit: limit2 = 50 }) => {
+    execute: async ({ symbol: symbol2, type, periodLength = 10, timeframe = "1day", limit: limit2 }) => {
       const res = await getFMPClient().technical.getTechnicalIndicator({
         symbol: symbol2,
         type,
@@ -795,12 +873,13 @@ var technicalDefinitions = [
         timeframe
       });
       if (res.success && Array.isArray(res.data)) {
-        return toToolResponse({ ...res, data: res.data.slice(0, limit2) });
+        return toToolResponse({ ...res, data: res.data.slice(0, limit2 ?? 50) });
       }
       return toToolResponse(res);
     }
   })
 ];
+var byNameLimit = zod.z.number().int().positive().default(50).describe("Max number of trades to return (default 50)");
 var symbolSchema3 = zod.z.object({
   symbol: zod.z.string().min(1, "Stock symbol is required").describe("Stock symbol (e.g., AAPL, MSFT, GOOGL)")
 });
@@ -822,19 +901,27 @@ var senateHouseDefinitions = [
   }),
   defineTool({
     name: "getSenateTradingByName",
-    description: "Get senate trading data for a specific senator by name showing their trading activity",
+    description: "Get senate trading data for a specific senator by name showing their trading activity (at most `limit` trades)",
     inputSchema: zod.z.object({
-      name: zod.z.string().min(1, "Name is required").describe("The name of the senator to get trading data for")
+      name: zod.z.string().min(1, "Name is required").describe("The name of the senator to get trading data for"),
+      limit: byNameLimit
     }),
-    execute: async ({ name }) => toToolResponse(await getFMPClient().senateHouse.getSenateTradingByName({ name }))
+    execute: async ({ name, limit: limit2 }) => toCappedToolResponse(
+      await getFMPClient().senateHouse.getSenateTradingByName({ name }),
+      limit2 ?? 50
+    )
   }),
   defineTool({
     name: "getHouseTradingByName",
-    description: "Get house trading data for a specific representative by name showing their trading activity",
+    description: "Get house trading data for a specific representative by name showing their trading activity (at most `limit` trades)",
     inputSchema: zod.z.object({
-      name: zod.z.string().min(1, "Name is required").describe("The name of the representative to get trading data for")
+      name: zod.z.string().min(1, "Name is required").describe("The name of the representative to get trading data for"),
+      limit: byNameLimit
     }),
-    execute: async ({ name }) => toToolResponse(await getFMPClient().senateHouse.getHouseTradingByName({ name }))
+    execute: async ({ name, limit: limit2 }) => toCappedToolResponse(
+      await getFMPClient().senateHouse.getHouseTradingByName({ name }),
+      limit2 ?? 50
+    )
   }),
   defineTool({
     name: "getSenateTradingRSSFeed",